README

Laravel, optimized. Laravel Optimized is a package for Laravel applications: Eloquent, Blade, validation, queues, mail, Artisan and the testing tools are the ones you already know, Laravel's documentation applies as written, and Laravel packages install and work as they do in any Laravel application.

What it adds is its own application core and a production build step. The work Laravel repeats on every request to find out things that cannot change between deployments (which routes exist, how controllers are built, what each model declares, how a named route's URL is shaped) is done once, by php artisan optimize, and read back from compiled files. Services are built when a request first needs them rather than registered up front.

Each of these steps has a fallback to Laravel's own code, can be switched off on its own, and is tested against the Laravel behaviour it stands in for.

Laravel's layers and this package's

Laravel Optimized uses Laravel's components and layers as they are:

Eloquent and the query builder, migrations and schema
Blade, views and components
Validation, authentication and authorization
Sessions, cookies, encryption and hashing
Cache, queues, events, mail and notifications
Filesystem, logging, HTTP client and the scheduler
Artisan and the testing tools
The container, facades and service providers your application and its packages register

It provides its own:

Application and kernels: LaravelOptimized\Foundation\Application, the HTTP and console kernels and the bootstrap sequence
Components: the core services, built on first use instead of registered by service providers
Routing: the router, the compiled route table, the dispatcher and the middleware pipeline
Container factories: compiled construction for the controllers and middleware routes build
Compiled Eloquent: the model plans and the compiled Model
URL generation: route() from compiled URL templates
Build commands: route:cache, eloquent:cache, optimize, view:warm, optimized:build

Installation

Require the package in a Laravel application:

composer require laravelopenpackages/laravel-optimized

Then point bootstrap/app.php at its application class. Only the import changes:

use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use LaravelOptimized\Foundation\Application;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        //
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        //
    })->create();

Routes, controllers, middleware, models, views and Artisan commands are written as in Laravel. To go back to stock Laravel, restore the Illuminate\Foundation\Application import and run php artisan optimize:clear.

Requirements: PHP 8.3 or later, Laravel 13.

How it works

Services on demand. The framework's core services (routing, sessions, cookies, encryption, views, the database, validation and the rest) come from a table of factories in LaravelOptimized\Components instead of service providers. A service is built the first time something asks for it, so a request only pays for what it uses. Your application's providers and package providers are registered and booted as usual.

Compiled routing. route:cache writes its own route table: exact paths in a lookup map, the rest in grouped regular expressions in registration order. Along with it come each route's middleware stack, controller and argument plan, implicit bindings, and the URL template route() fills in. The container factories for the controllers and middleware those routes use are written next to it, so building them needs no reflection.

Compiled Eloquent. eloquent:cache compiles Laravel's Model from the installed source, with a handful of methods reading from a plan made for each of your models: which boot methods and initializers it has, its class attributes (#[Table], #[Fillable], #[Hidden], ...), its #[ObservedBy] observers and #[ScopedBy] scopes. A method is only replaced when it is exactly the one this package was written against. The compiled Model is only loaded while the installed Laravel version is the one it was made from; otherwise Laravel's Model is used until the next build.

Lazy wiring. Eloquent's connection resolver, the closure signing key and queued job context are set up when their classes are first loaded, not at boot.

Production

Build every cache as part of your deployment:

php artisan optimize

This runs Laravel's config, event, route and view caches, with the compiled route table, container factories and compiled Eloquent. php artisan optimize:clear removes them all.

php artisan optimized:build does the same in one pass and adds view:warm (compiles and parse-checks every Blade view, so a broken template fails the deploy instead of a request), an optimized Composer autoloader, and a checklist of production settings. php artisan optimized:clear reverts it.

Laravel Optimized also runs under Laravel Octane.

Configuration

Every compilation is on by default. To change that, copy config/optimized.php into your application's config/ directory:

Key	Default
`compile.eloquent` (`OPTIMIZED_COMPILE_ELOQUENT`)	`true`	The compiled Eloquent Model
`compile.urls` (`OPTIMIZED_COMPILE_URLS`)	`true`	Compiled URL templates for `route()`
`eloquent.paths`	`[app_path()]`	Where `eloquent:cache` looks for models

Turning a compilation off runs that part on Laravel's code, unchanged.

Commands

Alongside Laravel's Artisan commands:

Command
`route:cache`	The compiled route table and the container factories for what the routes build
`eloquent:cache` / `eloquent:clear`	The compiled Eloquent Model and the model plans
`extensions:cache` / `extensions:clear`	The build steps packages register (EXTENDING.md)
`optimize [--profile]`	Every cache above plus Laravel's; `--profile` times each eager service provider
`view:warm`	Compile, parse-check and opcache-prime every Blade view
`optimized:build`	Every production cache in one pass, with a production checklist
`optimized:clear`	Undo `optimized:build`

Extending

Packages can compile data with each route, add build steps and run routes inside the current request. See EXTENDING.md.

Testing

composer install
composer test       # PHPUnit
composer analyse    # PHPStan

The suite runs an optimized application and a stock Laravel application side by side on the same scenarios (routing, container bindings, package providers, facades, configuration, URL generation, Eloquent models) and compares what each does. vendor/bin/phpunit --bootstrap tests/bootstrap-compiled.php runs the whole suite on the compiled Eloquent Model.

Contributing

Contributions are welcome: bug reports, fixes, tests and improvements.

Open an issue first for anything beyond a small fix, so the approach can be agreed before you spend time on it. Bugs are easiest to fix with the smallest route, model or command that shows them.
Fork the repository and branch from main.
Add a test with the change. Where this package stands in for something Laravel does, the test should show that it does exactly what Laravel does (tests/Compat has the side-by-side helpers). New compiled behaviour also needs a fallback to Laravel's code, and a switch in config/optimized.php when it can be turned off.

Run the checks:

composer test
composer analyse
vendor/bin/phpunit --bootstrap tests/bootstrap-compiled.php   # when touching Eloquent

Follow the code style: comments as docblocks (/** ... */), not //; imported class names rather than fully qualified ones in code; names and comments that say what the code does.
Open a pull request describing what changes and why.

Please report security issues privately through GitHub's security advisories rather than in a public issue.

Versioning

Laravel Optimized follows semantic versioning: breaking changes only in a new major version. See CHANGELOG.md.

Credits and license

Laravel Optimized is created by Zeeshan Ali. It builds on the components of Laravel, created by Taylor Otwell and its contributors, released under the MIT License. Laravel Optimized is not affiliated with or endorsed by Laravel.

Released under the MIT license.

laravelopenpackages / laravel-optimized

Package info

Security

Statistics