Foundation Laravel Package

Getting Started

illuminate/foundation is not a package you install — it is the framework core that ships inside laravel/framework (the split repos under illuminate/* are read-only mirrors used for Composer autoloading and API docs). You almost certainly already have it.

Confirm what you're running:

composer show laravel/framework | head -5
php artisan --version
ls vendor/laravel/framework/src/Illuminate/Foundation

The directory you care about is vendor/laravel/framework/src/Illuminate/Foundation. Treat it as read-only reference material: when a Laravel behavior surprises you (bootstrap order, container resolution, exception rendering), this is the source of truth.

First use case — reading your own boot sequence. In a modern Laravel app, bootstrap/app.php returns an Application instance built through the Foundation fluent configurator:

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(web: __DIR__.'/../routes/web.php')
    ->withMiddleware(fn (Middleware $m) => $m->trustProxies(at: '*'))
    ->withExceptions(fn (Exceptions $e) => $e->dontReport(SpecificException::class))
    ->create();

Trace from create() → Application::__construct() (which itself registers basePath, environmentPath, etc. into the container) → bootstrap() → the bootstrapper list (LoadEnvironmentVariables, LoadConfiguration, HandleExceptions, RegisterFacades, RegisterProviders, BootProviders, ...). That chain answers 80% of "why is this binding missing / why is this config null" questions.

Quick introspection while developing:

php artisan about          # environment, drivers, cache state
php artisan event:list     # confirms your listeners booted
php artisan tinker --execute="dump(app()->version(), app()->environment());"

Implementation Patterns

1. Register your own providers correctly per version.

• Laravel 11+: bootstrap/providers.php returns an array of provider class names.
• Laravel 10 and below: config/app.php → 'providers' => [...].

Foundation's ProviderRepository compiles this list into bootstrap/cache/services.php. If a provider "isn't loading," that cache file is the first thing to check — not your code.

2. Bind to the container instead of using globals.

Application extends Container, so everything you learn here transfers to any illuminate/container context:

$this->app->singleton(PaymentGateway::class, fn ($app) => new StripeGateway(
    $app['config']->get('services.stripe.secret')
));

Resolve in boot(), register in register(). Foundation enforces this ordering: all register() methods run before any boot() method, which is why cross-provider dependencies must be deferred to boot.

3. Use deferred providers for hot paths.

class ReportingServiceProvider extends ServiceProvider
{
    public function provides(): array { return [Reporter::class]; }
    public function register(): void { $this->app->singleton(Reporter::class, ...); }
}

Foundation skips loading the class entirely until Reporter is requested. This is the single biggest lever for trimming boot time on large apps.

4. Hook the bootstrap sequence instead of hacking index.php.

Add a custom bootstrapper via $app->bootstrapWith([...]) or (11+) the ->withProviders() / ->withMiddleware() fluent surface. Typical legitimate use: preloading secrets from a vault before LoadConfiguration.

5. Middleware and exception handling belong in the configurator.

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(AssignRequestId::class);
    $middleware->alias(['tenant' => EnsureTenant::class]);
})
->withExceptions(function (Exceptions $e) {
    $e->render(function (TenantNotFound $ex) {
        return response()->json(['error' => 'tenant'], 404);
    });
});

Exceptions is Foundation's thin wrapper over the Handler contract — it gives you ordering and $e->stopIgnoring()-style ergonomics that the raw handler doesn't.

6. Testing against Foundation.

Illuminate\Foundation\Testing\TestCase gives you the full app boot, RefreshDatabase, actingAs, HTTP assertions. For package development, don't require Foundation — use orchestra/testbench, which wires the Foundation test case without pinning you to a framework version.

7. Console and scheduling.

Commands are auto-discovered from app/Console/Commands by Application::configure()->withCommands(); schedules live in routes/console.php (11+) or Kernel::schedule() (10-). The Illuminate\Foundation\Console\Kernel also owns optimize:clear, config:cache, and event:cache — worth reading once to understand what each artifact invalidates.

Gotchas and Tips

Never require illuminate/foundation in a library. It drags in the whole framework and will fight the host app's laravel/framework constraint. Depend on illuminate/support, illuminate/contracts, illuminate/container, or illuminate/http instead. If you need the full app in tests, Testbench is the answer.

Version pinning is transitive and brittle. The split illuminate/* packages are version-locked to the corresponding laravel/framework release. composer update on one without the other produces duplicate-class or constraint-solver errors. Always update the whole family, or just require laravel/framework.

Provider caching silently defeats your changes. After editing bootstrap/providers.php, config/*.php, or a deferred provider's provides():

php artisan optimize:clear
# or, targeted:
php artisan config:clear && php artisan clear-compiled

bootstrap/cache/ should be in .gitignore — a committed services.php is a classic "works on my machine" bug.

register() vs boot() ordering bites in packages. Calling config('...') inside register() works only because LoadConfiguration runs earlier in the bootstrapper list; relying on another provider's binding in register() does not. Move it to boot() or use $this->callAfterResolving().

Facades cache their resolved instance. Swapping an implementation via $this->app->bind() after a facade has been resolved has no effect; use Facade::clearResolvedInstance() or, better, swap on the container before anything touches it. In tests, $this->swap() / $this->instance() is the clean path.

Laravel 10 → 11 moved the goalposts. app/Http/Kernel.php, app/Console/Kernel.php, and app/Exceptions/Handler.php are gone in favor of bootstrap/app.php fluent config. Most third-party tutorials and older Stack Overflow answers still assume the Kernel classes; if you copy protected $middlewareGroups into a fresh 11 app, nothing happens.

Debugging boot failures specifically. When the app dies before the exception handler is ready, you get a blank page. Reach for:

php artisan about                    # fails loudly with the real stack
APP_DEBUG=true php -S localhost:8000 -t public

and read Illuminate\Foundation\Bootstrap\HandleExceptions::forwardsTo() — that method decides whether an error is rendered, logged, or swallowed, and it's the usual culprit for "no stack trace."

Extension points worth knowing exist: Application::terminating() callbacks (post-response work), $app->afterResolving() for container hooks, ProviderRepository for provider compilation, and Illuminate\Foundation\Events\* (DiagnosingHealth, Terminating) for framework-level listeners.

File issues upstream. The illuminate/foundation repo is a read-only split; PRs and issues belong in laravel/framework under src/Illuminate/Foundation. Anything you "fix" locally gets blown away by the next composer update.