Support Core Laravel Package

Technical Evaluation

Architecture fit. orchestra/support-core is a foundation library, not a feature package. Its contents — service-provider base classes, reusable traits, string/array/HTML helpers, and extension contracts — are the commodity plumbing every Laravel service writes for itself. That means it does not slot into a product architecture as a capability; it slots in as a convention layer. The architecture question is therefore not "does this fit our domain" but "do we want one shared convention layer, and is this the one we standardize on." Its natural home is Orchestra Platform extension work and multi-codebase Laravel estates with visible drift (three HTML escapers, four incompatible extension interfaces). For a single service, the overlap with illuminate/support (Str, Arr, Htmlable) makes it a net-negative addition.

Integration feasibility. Technically trivial. v7.0.0 requires Laravel 9+ (transitively PHP 8.0+), installs with a single composer require orchestra/support-core:^7.0, and in most realistic scenarios arrives transitively via orchestra/testbench or another Orchestra component. The day-one value is concrete and low-risk: subclass the Orchestra provider base instead of hand-rolling register()/boot()/mergeConfigFrom() for the Nth time. The high-risk surface is the helpers and traits, because those end up inside application code where replacement becomes a codebase-wide edit. Feasibility is high; the constraint is governance, not engineering.

Technical risk. Four risks dominate, and none are exotic:

• Adoption and lifecycle. Zero listed dependents, composite score 0.3, single-maintainer ecosystem project, no published support or deprecation policy, and no vendor support tier. If this becomes load-bearing through transitivity, we are accepting an unmaintained-dependency risk on whatever path it sits — acceptable for internal tooling, materially different on a customer-facing request path.
• Constraint ambiguity. The release note says only "Laravel Framework v9+". That is ambiguous between "9.x only" and "9 through 12", and that single line decides whether the next framework major is a bump or a migration. "9+" is not an automatic forward-compatibility guarantee.
• Undisclosed breaking surface. A major bump whose only stated change is framework support typically also raises PHP minimums, tightens illuminate/* constraints, and may reshape helper signatures. Assume breakage; diff src/ between locked v6 and v7 rather than trusting the note.
• Silent behavioural and global-space hazards. Helpers autoloaded via files can fatal on redeclaration if we define a same-named function, and HTML/string helpers sit directly on rendering paths where an escaping change is security-relevant.

Key questions.

1. What is the actual illuminate/* and php constraint in the installed composer.json — ^9.0 (dead end at Laravel 10) or a multi-major range?
2. Does the package auto-register anything via extra.laravel.providers, or does it stay inert until we extend it?
3. Are helpers autoloaded via files? If so, which function names are now reserved in our global namespace?
4. What do we actually compile against — what does grep -rn 'Orchestra\\Support' app/ packages/ return today?
5. Is the package direct or transitive (composer why orchestra/support-core), and can we exclude it if we don't want it?
6. Who owns the usage policy — is application code permitted to call its helpers directly, or only through internal adapters?
7. Is any of this on a customer-facing path, or is it confined to internal tooling and package scaffolding?
8. What is the exit cost today, measured in call sites rather than opinion?

Integration Approach

Stack fit. Laravel 9+ / PHP 8.0+ only. Do not attempt this on a Laravel 8 host — you get a resolver failure or an unsupported workaround. It is designed to stay framework-agnostic where possible, but the operative constraint is the Laravel floor, and the package is a first-class fit for Orchestra Platform work and a marginal fit everywhere else. Approve it as scoped foundation for Orchestra-based work; do not let it become the platform-wide standard by accident.

Migration path.

1. Inventory before touching anything. composer why orchestra/support-core (transitive? from what? excludable?) → composer show orchestra/support-core (what actually resolved) → grep the illuminate/php constraints → grep -rn 'Orchestra\\Support' app/ packages/. That grep result is the blast radius; capture it before and after every bump.
2. Sequence the bump behind the framework work. v7 is an input to a Laravel 8→9 upgrade, never an isolated composer update. If we're on Laravel 8, stay on the last v6 release, plan the framework upgrade first, and treat v6 as having no security-patch commitment.
3. Diff, don't trust. Compare the src/ tree between locked v6 and v7 to surface the undisclosed breaking-change surface the one-line changelog omits.
4. Bump, then verify by test. Because v7 changes no behaviour by design, a green suite after the bump is the verification. Use php artisan about, php artisan config:cache, and one end-to-end feature test that resolves a real binding.
5. Pin ^7.0 explicitly in every composer.json that inherits it, even transitively, so resolver drift is visible in the diff rather than discovered in an incident.
6. Install the fence on day one. One adapter file wrapping every helper we consume, so an abandonment or a dropped Laravel major is a one-file swap, not a refactor. This is the single highest-leverage control in the whole integration.

Compatibility. Two compatibility obligations: the runtime floor (Laravel 9+/PHP 8.0+) and the behavioural contract of the HTML/string helpers. Treat the latter as API. Use contract-first integration where possible — bind our own implementations to interfaces in our provider rather than extending Orchestra's concrete classes — so Orchestra stays out of our type signatures and a future replacement is a rebind, not a rewrite. Apply trait composition only to classes we own; traits are compile-time coupling, and use-ing them inside models or jobs makes mocking invasive. Guard any helper we add with function_exists() to avoid a fatal redeclare against the package's files autoload.

Sequencing (recommended order).

1. Dependency inventory and blast-radius grep.
2. Constraint confirmation from the installed composer.json (this gates the roadmap answer).
3. Framework upgrade (8→9) completed and green.
4. support-core v7 bump, pinned, isolated in its own PR.
5. Wrapper adapter + contract bindings in place.
6. Explicit regression tests for escaping, quotes, entities, and multi-byte input.
7. Usage policy documented: which helpers and traits are sanctioned, who approves new ones.
8. Add to dependency-review cadence; re-confirm support manually at each Laravel major.

Operational Impact

Maintenance. We own the surface, not the vendor. The package gives us no changelog beyond one line, no deprecation policy, and no support tier, so the maintenance burden we're accepting is our own documentation of what we use. Mitigations are cheap and should be non-negotiable: the wrapper adapter, a documented inventory of helpers and traits in use, explicit pins, and a rollback path that is one composer require line rather than a refactor. Add the package to the dependency-review cadence and re-verify framework support by hand at each Laravel major — the "9+" wording buys us nothing automatically.

Support. There is no vendor support tier, effectively no external user base to lean on, and a single-maintainer ecosystem project behind it. Practically, internal escalation goes to whoever on our side adopted it. That is a fine arrangement for package scaffolding and internal tooling; it is not an arrangement to put on a customer-facing request path without a written risk acceptance.

Scaling. Runtime footprint is negligible — it is a thin utility layer, and performance is a non-issue. The scaling concerns are organizational: (a) the more codebases that adopt it, the harder the build-vs-buy answer is to reverse, so the usage policy should scale with adoption rather than lag it; and (b) helper changes bypass config:cache because files autoloads aren't cached, meaning a helper change requires composer dump-autoload and won't be caught by the usual config-clear reflex. Standardize once at the platform level rather than letting each team decide, or you get the drift you adopted the package to eliminate.

Failure modes (ranked by likelihood × impact).

• Silent escaping regression on a rendering path. Highest impact. Mitigation: explicit output assertions for entities, quotes, and multi-byte input after the bump; never bypass Blade's {{ }} with a raw helper call on user input.
• Fatal helper redeclaration. Global files autoload plus a same-named function equals a hard fatal. Mitigation: function_exists() guards on everything we add.
• Stale composer.lock or an unknown transitive constraint. The most common day-to-day cause of "clearly exists but won't resolve." Mitigation: the debugging checklist — composer why → composer show → grep the constraint → php artisan about → config:cache → one feature test through the binding.
• Deferred-provider ordering. If the base provider defers registration, bindings expected at boot() may not exist, producing BindingResolutionException on a class that plainly exists. Mitigation: check deferral before restructuring anything.
• Published config/assets drifting. Published copies don't auto-update, and vendor:publish --force overwrites edits. Mitigation: review the diff before forcing in production-adjacent environments.
• Roadmap surprise at the next Laravel major. Mitigation: treat framework-major readiness as a manual gate, not an assumption.

Ramp-up. Low, and that's part of the appeal. The API surface is small and conventional — a provider base class, a handful of traits, helpers, and contracts — so a Laravel-competent engineer is productive in under a day. The ramp-up that actually matters is the policy ramp, not the API: engineers must learn the two rules that keep the exit reversible — don't call helpers directly, call the adapter; don't apply traits to vendor classes. If those two rules are in the contributing guide and enforced in review, onboarding cost stays near zero and the build-vs-buy decision remains reversible. If they aren't, the coupling cost compounds silently and we discover it at the next framework major.