Kernel Laravel Package

Getting Started

Read the source before you wire it in. orchestra/kernel is thin enough to read end-to-end in an afternoon. Open vendor/orchestra/kernel/src/ and focus on two files: the HTTP kernel and the console kernel. The thing you are buying is their $bootstrappers arrays — those arrays define exactly which steps Orchestra injects into the Laravel boot sequence, and in what order. Extension discovery, config loading, provider registration, and console command wiring all hang off that ordered list. If your install also pulls orchestra/foundation, read that next; the kernel is the layer underneath it, and Foundation is what actually binds the concrete Orchestra classes you'll be using.

Install with an exact pin. This package shadows framework internals — the HTTP pipeline, console registration, and exception handling. A caret range is a standing hazard because a minor bump can reorder bootstrappers or change a base class contract. Pin the minor:

composer require orchestra/kernel:6.0.*

The only release artifact documented here is v6.0.0, targeting Laravel 8. Treat the release notes as your compatibility matrix and do not attempt this on Laravel 10/11 until you've confirmed a newer tag exists in the repo. If none does, that is a scheduling decision, not a coding one.

Day-one task: swap the kernel bindings in bootstrap/app.php. The three singletons you care about are Illuminate\Contracts\Http\Kernel, Illuminate\Contracts\Console\Kernel, and Illuminate\Contracts\Debug\ExceptionHandler. Point them at the Orchestra equivalents (typically under Orchestra\Foundation\* once Foundation is installed). Class namespaces shift between majors — verify against src/ rather than trusting any snippet, including this one.

First use case: get it booting, then prove it boots identically. Run php artisan list, hit one route, and confirm the exception handler renders a 500 correctly. That is the smoke test, not the success criterion. "It boots" is cheap; with a kernel substitution, "it boots identically to vanilla Laravel" is the bar. Stand up the parity harness (below) on the same day you do the cutover, before any feature work resumes.

Implementation Patterns

Wrap it before you use it. The single highest-leverage pattern is to never let application code reference Orchestra kernel classes directly. Introduce your own App\Foundation\Http\Kernel extends Orchestra\Foundation\Http\Kernel (and the console equivalent) and bind those in bootstrap/app.php. Now reverting to Illuminate\Foundation is a one-file PR instead of an archaeology project. This is the difference between a reversible decision and permanent tech debt.

Customize the boot sequence via subclass, never vendor edits. Override $bootstrappers in your wrapper class:

class HttpKernel extends \Orchestra\Foundation\Http\Kernel
{
    protected $bootstrappers = [
        \Illuminate\Foundation\Bootstrap\LoadEnvironmentVariables::class,
        \Illuminate\Foundation\Bootstrap\LoadConfiguration::class,
        // ... Orchestra's extension/config bootstrappers, preserved in order
        \Illuminate\Foundation\Bootstrap\RegisterFacades::class,
        \Illuminate\Foundation\Bootstrap\RegisterProviders::class,
        \Illuminate\Foundation\Bootstrap\BootProviders::class,
    ];
}

Order matters most around RegisterProviders / BootProviders. Anything that needs the extension registry populated must run after provider registration, not before. Copy the vendor array verbatim and add to it rather than retyping it from memory.

Extension registration is the actual daily workflow. The kernel's practical value is that packages participate in a consistent lifecycle rather than relying on raw auto-discovery. Day-to-day, an "extension" is a service provider plus a manifest/registration entry that the discovery layer reads from configured paths. Publish and own the config:

php artisan vendor:publish --tag=orchestra

Commit config/orchestra.php and diff the provider list and extension paths in CI. Config drift in this file is the classic "works locally, fails in CI" failure — the extension registry silently diverges between environments and you spend a day chasing it.

Build the parity harness on day one and run it on every PR. This is the pattern that actually protects you against the failure mode that matters:

$bindings  = array_keys(app()->getBindings());
$providers = array_keys(app()->getLoadedProviders());
$routes    = collect(Route::getRoutes())->map->uri();
$commands  = array_keys(Artisan::all());

Snapshot container bindings, loaded providers, middleware stack order, the route list, and artisan list output against a vanilla-Laravel branch or a recorded fixture. Record every intentional divergence in a file next to the harness so the diff stays legible. Without this, divergence is silent — the app boots, mostly works, and behaves subtly differently in auth or exception handling until it doesn't.

Use Testbench for package-level tests. If you're writing tests against this stack, orchestra/testbench is the intended harness and mirrors kernel bootstrapping. Use it rather than hand-rolling an application instance, or your tests will boot a different kernel than production and pass on a configuration you never ship.

Keep the revert rehearsed. Ship composer.json, composer.lock, and every bootstrap/kernel change as one isolated commit. Rehearse the rollback to stock kernels once, on a branch, before you need it. The exit cost is what turns a reversible experiment into a permanent commitment with a dated exit you never take.

Gotchas and Tips

Silent divergence is the real failure mode. A boot crash is cheap — CI catches it in a minute. The expensive defect is middleware ordering or container resolution differing by a single step, surfacing as a production incident weeks later. The parity harness is not optional tooling; treat a red diff as a release blocker, not a warning.

Type-hints on the concrete application class will bite you. Any third-party package that hints Illuminate\Foundation\Application (the concrete class, not Illuminate\Contracts\Foundation\Application) may fail to resolve under the Orchestra application. Grep for it before cutover. It fails at boot, but it fails late if the code path is only hit on one route — so the grep is cheaper than the incident.

Octane and long-lived workers are a trap. Bootstrappers run once under "boot once" semantics. Never cache request-scoped state in a bootstrapper or in a custom bootstrapper's bootstrap() method. Validate explicitly under Octane if you use it; the failure mode is cross-request state leakage, which is miserable to diagnose because it looks like flaky auth or intermittent user-data bleed and never reproduces locally.

Clear caches after touching extension manifests. Discovery results are cached. When a new extension "isn't loading," the answer is almost always php artisan optimize:clear before it's anything in your code. Make that the first step of any debugging session involving extensions — it costs ten seconds and saves an hour.

You are the QA. Zero stars and zero dependents means no Stack Overflow corpus, no ecosystem peer pressure keeping it working, and effectively a single-maintainer bus factor. Debugging means dd() inside vendor/ and reading source. Budget ramp-up accordingly: roughly a sprint for a mid-level engineer to be productive, more for credible on-call coverage. There is no vendor SLA and no guaranteed security-patch latency.

Upgrade coupling is recurring, not one-time. Every Laravel minor becomes a coordinated two-party upgrade against an external maintainer's schedule. Record the Laravel-minor-to-Orchestra-version mapping in your dependency register, name one owner, and schedule the compatibility check against Laravel's release cadence, not yours.

Extension points, ranked by leverage. If you must extend, in order: (1) override $bootstrappers in your wrapper kernel; (2) add a service provider registered after RegisterProviders; (3) publish and commit config/orchestra.php; (4) last resort, a middleware inserted into the kernel's $middleware / $middlewareGroups arrays. Vendor-file edits are never the answer — they vanish on the next composer update and nobody will remember why the file was dirty.

When in doubt, check whether the requirement can be met on vanilla Laravel plus first-party providers. The kernel buys you extension discovery and an Orchestra-shaped boot sequence. If you don't need those, it costs you a substitution of the bootstrap sequence, the HTTP pipeline, and console registration — a high blast radius for a problem most applications don't have.