From ecb87978e34e1e39818911ddf2a6bb53da0d407f Mon Sep 17 00:00:00 2001 From: Ollie Read Date: Thu, 5 Feb 2026 17:24:38 +0000 Subject: [PATCH 1/4] feat: Add RFC-0004 for Propagator developer toolkit Introduces initial draft RFC for Propagator, the Sprout dev toolkit package that will provide make commands and inspection tools. --- rfcs/0004-propagator.md | 95 +++++++++++++++++++++++++++++++++++++++++ rfcs/README.md | 1 + 2 files changed, 96 insertions(+) create mode 100644 rfcs/0004-propagator.md diff --git a/rfcs/0004-propagator.md b/rfcs/0004-propagator.md new file mode 100644 index 0000000..20e4969 --- /dev/null +++ b/rfcs/0004-propagator.md @@ -0,0 +1,95 @@ +# RFC-0004: Propagator — Developer Toolkit + +- **Status:** Draft +- **Author:** Ollie Read (@ollieread) +- **Created:** 2026-02-05 +- **Updated:** 2026-02-05 + +## Summary + +Propagator is a developer toolkit for Sprout that provides Artisan commands for code generation, inspection, and other development workflows. It simplifies working with Sprout by offering `make:*` commands for generating tenant-aware classes and inspection commands for understanding the current configuration. + +## Motivation + +Working with Sprout requires creating various classes that follow specific contracts and patterns: tenant models, tenant providers, identity resolvers, and service overrides. Currently, developers must create these manually, referencing documentation and existing implementations. + +A dedicated dev toolkit addresses several pain points: + +1. **Boilerplate reduction** — Generating stubs for common Sprout classes saves time and ensures correct structure +2. **Discoverability** — Inspection commands help developers understand what's registered and configured +3. **Consistency** — Generated code follows established patterns and conventions +4. **Onboarding** — New developers can scaffold components without deep knowledge of internals + +## Detailed Design + +Propagator is a separate package in its own repository, installed as a dev dependency. + +### Make Commands + +#### `make:tenant` + +Generates a tenant model class implementing the `Tenant` contract. + +```bash +php artisan make:tenant Organisation +``` + +#### `make:provider` + +Generates a tenant provider class implementing the `TenantProvider` contract. + +```bash +php artisan make:provider OrganisationProvider +``` + +#### `make:resolver` + +Generates an identity resolver class implementing the `IdentityResolver` contract. + +```bash +php artisan make:resolver CustomResolver +``` + +#### `make:override` + +Generates a service override class implementing the `ServiceOverride` contract. + +```bash +php artisan make:override CustomCacheOverride +``` + +### Inspection Commands + +#### `sprout:list` + +Lists registered tenancies, providers, resolvers, and overrides. + +```bash +php artisan sprout:list +php artisan sprout:list --tenancies +php artisan sprout:list --providers +php artisan sprout:list --resolvers +php artisan sprout:list --overrides +``` + +## Drawbacks + +- **Additional package** — Another package to maintain, even if lightweight +- **Laravel coupling** — Artisan commands tie this specifically to Laravel (though Sprout is Laravel-focused anyway) + +## Alternatives + +- **No toolkit** — Developers create classes manually using documentation +- **Built into Core** — Include commands in the core package (rejected: dev tools shouldn't be a production dependency) + +## Unresolved Questions + +- Should Propagator include testing utilities (factories, assertions, test traits)? +- What additional inspection commands would be valuable? +- Should make commands support customisation options (e.g., `--eloquent` for providers)? + +## Implementation Plan + +1. Create separate repository with package structure and service provider +2. Implement make commands with stub files +3. Implement `sprout:list` command diff --git a/rfcs/README.md b/rfcs/README.md index 0172352..7ac677d 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -40,5 +40,6 @@ You don't need an RFC for: | [0001](./0001-seedling.md) | Seedling — Multi-Database Support | Draft | 2026-02-04 | | [0002](./0002-canopy.md) | Canopy — Domain-Based Tenant Identification | Draft | 2026-02-04 | | [0003](./0003-stacked-identity-resolution.md) | Stacked Identity Resolution | Under Review | 2026-02-04 | +| [0004](./0004-propagator.md) | Propagator — Developer Toolkit | Draft | 2026-02-05 | From 75fab1e4c222b998352e66209f4aaccd1ee0f3b6 Mon Sep 17 00:00:00 2001 From: Ollie Read Date: Thu, 5 Feb 2026 17:28:03 +0000 Subject: [PATCH 2/4] feat: Add Telescope integration to Propagator RFC Telescope integration will make collectors tenant-aware, allowing developers to filter and view entries by tenant. --- rfcs/0004-propagator.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/rfcs/0004-propagator.md b/rfcs/0004-propagator.md index 20e4969..ed04965 100644 --- a/rfcs/0004-propagator.md +++ b/rfcs/0004-propagator.md @@ -72,6 +72,16 @@ php artisan sprout:list --resolvers php artisan sprout:list --overrides ``` +### Telescope Integration + +When Laravel Telescope is detected, Propagator integrates with it to make the various collectors tenant-aware. This allows developers to filter and view Telescope entries by tenant, providing better visibility into tenant-specific behaviour during development. + +The integration hooks into Telescope's watchers to: + +- Tag entries with the current tenant identifier +- Add tenant context to request, job, query, and other recorded entries +- Enable filtering the Telescope UI by tenant + ## Drawbacks - **Additional package** — Another package to maintain, even if lightweight @@ -93,3 +103,4 @@ php artisan sprout:list --overrides 1. Create separate repository with package structure and service provider 2. Implement make commands with stub files 3. Implement `sprout:list` command +4. Implement Telescope integration (conditional on Telescope being installed) From c1933aff7bf4a1510b002e451eeb75e3372f65c5 Mon Sep 17 00:00:00 2001 From: Ollie Read Date: Thu, 5 Feb 2026 17:37:20 +0000 Subject: [PATCH 3/4] feat: Add interactive configuration commands and extension API - Interactive sprout:configure command for managing config files - Extension API for other packages to integrate dynamically --- rfcs/0004-propagator.md | 44 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/rfcs/0004-propagator.md b/rfcs/0004-propagator.md index ed04965..ae8aa95 100644 --- a/rfcs/0004-propagator.md +++ b/rfcs/0004-propagator.md @@ -72,6 +72,40 @@ php artisan sprout:list --resolvers php artisan sprout:list --overrides ``` +### Interactive Configuration Commands + +Propagator provides interactive terminal commands for managing Sprout configuration files, offering a user-friendly UI instead of manual file editing. + +#### `sprout:configure` + +An interactive command for managing Sprout's configuration. Guides developers through setting up tenancies, providers, resolvers, and overrides with prompts and validation. + +```bash +php artisan sprout:configure +php artisan sprout:configure tenancy +php artisan sprout:configure provider +``` + +The interactive UI presents available options, validates input, and writes changes to the appropriate configuration files. + +### Extension API + +Propagator exposes an API that allows other Sprout packages to integrate dynamically. This enables packages to: + +- Register additional configuration options for the interactive commands +- Provide custom make command stubs +- Add package-specific entries to `sprout:list` output +- Extend the configuration UI with their own settings + +For example, Seedling could register its database-related tenancy options so they appear in `sprout:configure tenancy`, and Canopy could add domain configuration options. + +```php +// Example: A package registering options with Propagator +Propagator::extend('tenancy', function (TenancyConfigurator $configurator) { + $configurator->addOption('database', 'Configure tenant database connection'); +}); +``` + ### Telescope Integration When Laravel Telescope is detected, Propagator integrates with it to make the various collectors tenant-aware. This allows developers to filter and view Telescope entries by tenant, providing better visibility into tenant-specific behaviour during development. @@ -97,10 +131,14 @@ The integration hooks into Telescope's watchers to: - Should Propagator include testing utilities (factories, assertions, test traits)? - What additional inspection commands would be valuable? - Should make commands support customisation options (e.g., `--eloquent` for providers)? +- What should the extension API contracts look like? +- How should packages register their configuration options with Propagator? ## Implementation Plan 1. Create separate repository with package structure and service provider -2. Implement make commands with stub files -3. Implement `sprout:list` command -4. Implement Telescope integration (conditional on Telescope being installed) +2. Define the extension API contracts +3. Implement make commands with stub files +4. Implement `sprout:list` command +5. Implement interactive configuration commands +6. Implement Telescope integration (conditional on Telescope being installed) From 24a4db2ed2adcc30ab4f0192bbf4a486e200f287 Mon Sep 17 00:00:00 2001 From: Ollie Read Date: Thu, 5 Feb 2026 17:40:45 +0000 Subject: [PATCH 4/4] feat: Add RFC-0004 to main README index --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index ced069b..9ce818b 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ discuss and evaluate proposals before implementation. - [RFC-0001: Seedling — Multi-Database Support](./rfcs/0001-seedling.md) — Multi-database support - [RFC-0002: Canopy — Domain-Based Tenant Identification](./rfcs/0002-canopy.md) — Domain-based tenant identification - [RFC-0003: Stacked Identity Resolution](./rfcs/0003-stacked-identity-resolution.md) — Stacked Identity Resolution +- [RFC-0004: Propagator — Developer Toolkit](./rfcs/0004-propagator.md) — Developer toolkit - [Index](./rfcs/README.md) — List of all RFCs and their status ### [ADRs](./adrs/)