From 86859e3eb84310840859192502a1b66a27d30b74 Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Sat, 3 Oct 2026 15:16:11 -0400 Subject: [PATCH 1/2] Rename the quick start to Quick start guide and usage The README standard now splits the section into Getting started, the setup a fresh install needs before the first call, and Usage. Every command, tag and env key shown was checked against the package's own provider, config or CLI. --- README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 85285b1..3296c63 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,20 @@ composer require laranail/polyglot php artisan laranail::polyglot.install ``` -## Quick start +## Quick start guide and usage + +### Getting started + +1. `php artisan laranail::polyglot.install` (see Install) publishes the config and prints what is left. +2. Point a service at its URL in `.env`. The default service is `fastapi`: + + ```dotenv + POLYGLOT_FASTAPI_URL=http://127.0.0.1:8000 + ``` + +3. Only HTTP services are on by default. Local scripts stay off until `POLYGLOT_PROCESS_ENABLED=true` (it is code execution), and callbacks stay off until `POLYGLOT_CALLBACKS_ENABLED=true` and `POLYGLOT_CALLBACK_SECRET` is set. + +### Usage ```php use Simtabi\Laranail\Polyglot\Facades\Polyglot; From 20e655722d5c6e023e999c3e1b32a661b313da56 Mon Sep 17 00:00:00 2001 From: Imani Manyara Date: Sat, 3 Oct 2026 15:16:11 -0400 Subject: [PATCH 2/2] Name the package and its config by their real names The docs, the install command and the contributor files still said laranail/python and config/python.php; the package is laranail/polyglot and publishes config/laranail/polyglot.php. --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- CONTRIBUTING.md | 2 +- docs/configuration.md | 2 +- docs/getting-started.md | 2 +- docs/installation.md | 6 +++--- docs/release.md | 4 ++-- docs/tools/callbacks.md | 2 +- src/Commands/InstallCommand.php | 4 ++-- 8 files changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 8106e12..da47ce5 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -9,5 +9,5 @@ - [ ] CHANGELOG.md updated under `[Unreleased]` - [ ] No command is built as a string; commands stay arrays - [ ] Any secret the package injects is registered with the `Redactor` -- [ ] `env()` is still called only in `config/python.php` +- [ ] `env()` is still called only in `config/polyglot.php` - [ ] Security-relevant behaviour has a test that fails without the fix diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a82c838..9d511fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,7 @@ clean before a PR. - **Never build a command string.** Commands are arrays, which bypass the shell. An architecture test asserts `shell_exec`, `exec`, `passthru`, `system`, `proc_open` and `popen` appear nowhere in the package. -- **`env()` is called in `config/python.php` and nowhere else.** Anywhere else +- **`env()` is called in `config/polyglot.php` and nowhere else.** Anywhere else it returns null the moment the host runs `config:cache`. Also asserted. - **A secret the package injects must be registered with the `Redactor`.** If it can reach stderr or an exception message, it will. diff --git a/docs/configuration.md b/docs/configuration.md index acd1177..94f281d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,6 +1,6 @@ # Configuration -Everything in `config/python.php`, published by `php artisan laranail::polyglot.install`. Keys live under +Everything in `config/laranail/polyglot.php`, published by `php artisan laranail::polyglot.install`. Keys live under `laranail.polyglot.*`. Three of these blocks are security boundaries rather than preferences — `process`, `callbacks`, and diff --git a/docs/getting-started.md b/docs/getting-started.md index cecfe93..dba69ca 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -5,7 +5,7 @@ Point a service at a URL: ```php -// config/laranail/python.php +// config/laranail/polyglot.php 'services' => [ 'fastapi' => ['base_url' => env('POLYGLOT_FASTAPI_URL', 'http://127.0.0.1:8000')], ], diff --git a/docs/installation.md b/docs/installation.md index 29847f9..b0d9ce6 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,7 +1,7 @@ # Installation ```bash -composer require laranail/python +composer require laranail/polyglot ``` The service provider and the `Polyglot` facade are auto-discovered. @@ -10,7 +10,7 @@ The service provider and the `Polyglot` facade are auto-discovered. php artisan laranail::polyglot.install ``` -That publishes `config/laranail/python.php` and prints what to do next. +That publishes `config/laranail/polyglot.php` and prints what to do next. ## Requirements @@ -32,7 +32,7 @@ does not read a dependency's own `repositories`: ```json { "repositories": [ - { "type": "vcs", "url": "https://github.com/laranail/python" }, + { "type": "vcs", "url": "https://github.com/laranail/polyglot" }, { "type": "vcs", "url": "https://github.com/laranail/console" }, { "type": "vcs", "url": "https://github.com/laranail/package-tools" } ] diff --git a/docs/release.md b/docs/release.md index bc6ca18..377992a 100644 --- a/docs/release.md +++ b/docs/release.md @@ -1,6 +1,6 @@ # Release process -`laranail/python` is released **tag-driven**: pushing a `vX.Y.Z` tag runs the release workflow, which +`laranail/polyglot` is released **tag-driven**: pushing a `vX.Y.Z` tag runs the release workflow, which publishes the GitHub Release with the CHANGELOG section as its body. `laranail/*` packages resolve through **git VCS repositories rather than Packagist**, so the tag is the @@ -20,7 +20,7 @@ tag per the laranail convention. - `ValueObjects\{Call, CallResult, ProcessCall, ResolvedCommand}` and the shipped enums. - The `Exceptions\*` hierarchy and its codes. - `Testing\PolyglotFake` and its assertions. -- `config/python.php` key shapes and the `POLYGLOT_*` env var names. +- `config/polyglot.php` key shapes and the `POLYGLOT_*` env var names. - The `laranail::polyglot.{doctor,health,run,install,make-service}` command signatures. - **The callback wire format** — the signed string, the header names, and the HMAC construction. A change here breaks every deployed Python service at once, and they do not upgrade in lockstep with diff --git a/docs/tools/callbacks.md b/docs/tools/callbacks.md index b96afb3..98493b3 100644 --- a/docs/tools/callbacks.md +++ b/docs/tools/callbacks.md @@ -9,7 +9,7 @@ it on — see [architecture](../architecture.md) for why absent beats guarded. ## Enabling it ```php -// config/laranail/python.php +// config/laranail/polyglot.php 'callbacks' => [ 'enabled' => true, 'prefix' => 'api/polyglot', diff --git a/src/Commands/InstallCommand.php b/src/Commands/InstallCommand.php index a6496b0..ebb8934 100644 --- a/src/Commands/InstallCommand.php +++ b/src/Commands/InstallCommand.php @@ -16,14 +16,14 @@ final class InstallCommand extends Command protected $name = 'laranail::polyglot.install'; - protected $description = 'Publish the laranail/python configuration.'; + protected $description = 'Publish the laranail/polyglot configuration.'; public function handle(): int { $this->callSilently('vendor:publish', ['--tag' => 'laranail::polyglot-config']); $display = $this->services->display(); - $display->success('Published config/laranail/python.php.'); + $display->success('Published config/laranail/polyglot.php.'); $display->list([ 'Point laranail.polyglot.services.* at your services, and set an auth scheme if they need one.',