Lumen Laravel Package

Technical Evaluation

Architecture fit. orchestra/lumen is a compatibility shim, not a platform. Its job is to make Orchestra's service providers, config loading, and container bindings resolve inside Lumen's lighter bootstrap. That means it fits exactly one architecture: an existing Orchestra Platform codebase that must also run on Lumen, or a codebase deliberately sharing code between the two. For any other shape — greenfield service, admin surface, API edge — the package adds a second kernel boundary without adding capability. Architecturally it is a bridge between two ecosystems whose vendor direction is diverging: Lumen's own upstream trajectory is toward slim Laravel and Octane, so a Lumen-specific bridge is a bet against the framework vendor's roadmap. That is a strategic misalignment to record in any design review that cites "lightweight" as the rationale, not a technical footnote.

Integration feasibility. Feasible but never turnkey. Lumen does not auto-discover providers and has no vendor:publish, so the package does nothing on composer require alone — every provider is hand-registered in bootstrap/app.php, every config file hand-copied, and $app->withFacades() is mandatory before Orchestra providers register. The real feasibility gate is Composer resolution: the package sits between two sets of illuminate/* constraints, and composer require orchestra/lumen --dry-run against the exact PHP and Lumen versions is the cheapest possible go/no-go. If that fails there is no upstream fix path to wait for. Boot order is the second gate — anything reading config() inside register() fails with BindingResolutionException because Lumen binds the config repository later than Laravel does. Both are known, diagnosable, and cheap to prove with a single probe route resolving one Orchestra contract.

Technical risk. High and concentrated, because the failure modes are silent or structural rather than loud:

• Constraint drift. Any unrelated composer update can move an illuminate/* package out from under the bridge. This is the first incident, not an edge case.
• Symfony internals dependency. The v5.0.3 release patched construction of Symfony\Component\ErrorHandler\Error\FatalError — the package reaches into Symfony internals, so every Symfony minor bump is a potential break with no upstream owner.
• Silent driver fallback. Lumen does not register session, cache, queue, or broadcast the way Laravel does. An Orchestra provider assuming Laravel defaults can fall back to an in-memory driver in production without erroring.
• Zero dependents, zero stars, low score. No community patch stream, no CVE response, no hiring pool. Every upgrade, security fix, and onboarding hour is an internal line item.
• Bus factor of one. The knowledge lives in whichever engineer read the boot sequence.

Key questions. Before any commitment:

1. Are we pulling orchestra/foundation (full admin/extension surface) or only lighter contracts (orchestra/support, orchestra/memory, orchestra/authorization)? composer show orchestra/lumen --tree answers this, and the first is an order of magnitude harder to keep alive.
2. Does composer require orchestra/lumen --dry-run resolve against our pinned PHP and Lumen versions today?
3. What is the concrete product requirement that depends on Lumen specifically rather than Laravel? If the answer is "lightness," there is no requirement yet.
4. Is this surface internal-only, with no untrusted input paths and no external SLA?
5. Who is the named owner, and what is the funded exit date?
6. Does anything on the request path need queues, scheduling, broadcasting, or a Blade-heavy admin UI? If so, the fit collapses and Laravel is the correct target.

Integration Approach

Stack fit. Acceptable only for an inherited Orchestra-on-Lumen application with a stable internal surface. The supported integration surface is narrow and well-defined: providers registered by hand in bootstrap/app.php in strict order, config copied by hand from vendor/orchestra/lumen/config/, facades enabled, and Orchestra middleware aliased through $app->routeMiddleware(). If the stack needs current PHP/Laravel parity, a security patch stream, or a vendor SLA, it does not fit. Same if hiring viability matters — Orchestra Platform is not a skill you can recruit for.

Migration path. The strongest TPM argument for this package is that its status is the funding case for a move to Laravel. With zero downstream ecosystem and no external help coming, the migration business case writes itself: upgrades, CVE response, and onboarding labour are all internal costs with no free labour to absorb them. Plan the migration as the default trajectory and treat continued use as a time-boxed hold. Two rules make that exit cheap:

• Wrap the bridge. Bind a project-owned interface (e.g. SettingsStore) over orchestra.memory in a project-owned provider, never in the package. When you move to Laravel, you swap one binding and touch no controllers or jobs.
• Keep a migration checklist in the README. Every provider registered and every config key copied by hand is a line item for the Laravel move. This list is the artefact that converts an engineering annoyance into a scoped, costable risk on the roadmap.

If a fork is unavoidable, extend the package's provider and re-register the subclass rather than editing vendor/, and record the fork point in PATCHES.md — there is no upstream to rebase onto.

Compatibility. Pin exact versions and commit the lockfile on the same day the dry-run passes. Treat the Composer graph as a monitored surface, not a settled fact: run composer update --dry-run as a separate CI job so drift surfaces before someone touches an unrelated dependency. Do not rely on Laravel-only drivers — verify the actual driver at runtime (config('cache.default'), config('session.driver'), config('queue.default')) via a health route, not merely that the call succeeded. After any Symfony or Lumen bump, trigger a deliberate fatal in staging to exercise the error-handler path the v5.0.3 patch touched. Provider order matters: the package provider goes last, and any config read happens in boot(), never register().

Sequencing. Five steps, each with an explicit stop condition:

1. Resolve. composer require orchestra/lumen --dry-run on a throwaway branch against exact PHP and Lumen versions. Fail → stop; there is no upstream fix path.
2. Scope. composer show orchestra/lumen --tree to determine whether orchestra/foundation is in the graph. If it is, re-estimate the whole effort before proceeding.
3. Wire. Minimal bootstrap/app.php changes in order: withFacades() → configure() for each key → register the provider last → route group with the Orchestra middleware alias. Copy config by hand.
4. Probe. Register one Orchestra contract and resolve it from a trivial /_probe route. This single step separates "Composer problem" from "boot-order problem" faster than anything else. Then contract-test each Orchestra concern individually — these tests are the changelog, because there is none upstream.
5. Isolate. Keep the Orchestra bootstrap off every hot path. If an admin surface is needed, run it in a separate Lumen application bootstrapped only for that purpose, keeping extension manifests and config aggregation out of the request kernel entirely.

Operational Impact

Maintenance. This is the dominant cost and it is entirely internal. No dependents means no community patch stream, so the package is effectively vendored code you own. Budget a standing maintenance tax: Symfony and Lumen bump testing, Composer constraint monitoring, and periodic error-path validation. Any roadmap item that depends on this package should be re-estimated with that tax attached, or descoped outright.

Support. There is no vendor SLA, no upstream maintainer obligation, and no hiring pool. Support is whoever read the boot sequence — name that person explicitly and treat their departure as a scheduled migration rather than a surprise. Escalation paths must be internal by construction. For inbound proposals naming this package, the governance answer is default-deny: route it through intake and close it before it reaches sprint planning, when rejection is still free.

Scaling. Scales technically — Lumen is fast and the bridge is thin — but not organisationally. The constraint is not throughput, it is knowledge. Every additional service that adopts the bridge multiplies the maintenance surface while the pool of people who can service it stays at one. If throughput is genuinely the driver, Laravel with Octane or a purpose-built service is the better answer and carries an ecosystem. Keep the Orchestra bootstrap off stateless API edges: register only the providers the request path needs, and leave admin/extension providers out of that kernel.

Failure modes. Ranked by likelihood and blast radius:

• Composer resolution failure. Highest likelihood, breaks builds and blocks onboarding. Detected by the dry-run CI job.
• Boot-order failure (BindingResolutionException). Config read inside register(), or facade root unset. Loud, reproducible, cheap to fix — but looks like a package bug when it is a boot-order bug.
• Silent driver fallback. Worst blast radius. An Orchestra provider assumes a Laravel default that Lumen never registered and falls back to in-memory in production. No error, no alert — just lost writes or lost sessions. Mitigated only by the runtime health probe.
• Symfony minor bump breaking the error handler. Reaches into internals; breaks the fatal-error path, which is exactly when you least want it broken. Mitigated by a deliberate fatal in staging post-bump.
• Undetected behaviour change from a transitive Orchestra patch. No changelog to diff. Mitigated only by contract tests per Orchestra concern.

Ramp-up. Effectively non-transferable. Orchestra Platform is not a recruitableskill; a new engineer cannot be onboarded from public documentation because there is no meaningful public documentation. Budget for a written internal runbook covering: the provider registration list in bootstrap/app.php order, the hand-copied config keys, the boot-order rule (boot() not register()), the driver verification route, and the four-step debugging checklist (composer why-not → dump getLoadedProviders() → probe route → compare staging vs local config). Without that runbook, ramp-up cost is a single person's tenure.