Laravel Scale

Laravel Scale is a production-focused, modular package suite for Laravel applications that need database performance, scalability, and reliability from thousands to billions of records.

Highlights

• Multi-package architecture with independent installable modules
• Adapter-based database support (MySQL, MariaDB, PostgreSQL, SQLite, SQL Server)
• Architecture-ready aliases for Oracle and CockroachDB drivers
• Query intelligence: slow queries, duplicate queries, N+1 detection, fingerprinting
• Index intelligence recommendations
• Lifecycle tooling: archive and cleanup commands
• Health scoring and report generation
• Optional integrations: Debugbar, Telescope, Pulse, OpenTelemetry

Package Layout

• laravel-scale/core
• laravel-scale/database
• laravel-scale/query
• laravel-scale/index
• laravel-scale/cache
• laravel-scale/lifecycle
• laravel-scale/monitor
• laravel-scale/report
• laravel-scale/debugbar (optional)
• laravel-scale/telescope (optional)
• laravel-scale/pulse (optional)
• laravel-scale/opentelemetry (optional)

Installation

Prerequisites:

• PHP 8.2+
• Laravel 10, 11, or 12

Primary Packagist package (this repository):

composer create-project yoosuf/laravel-scale

Install from source packages in an existing Laravel app:

composer config repositories.laravel-scale vcs "https://github.com/yoosuf/laravel-scale"
composer require "laravel-scale/core:dev-main as 1.0.99" "laravel-scale/query:dev-main as 1.0.99" "laravel-scale/index:dev-main as 1.0.99" "laravel-scale/cache:dev-main as 1.0.99" "laravel-scale/monitor:dev-main as 1.0.99"

When laravel-scale/* packages are published on Packagist, you can install them directly:

composer require laravel-scale/core laravel-scale/query laravel-scale/index laravel-scale/cache laravel-scale/monitor

Package Names vs PHP Namespace

• Composer package on Packagist: yoosuf/laravel-scale
• Module package names: laravel-scale/*
• PHP namespace used by the code: LaravelScale\\...

Publish configuration:

php artisan vendor:publish --tag=scale-config

Run a quick health check:

php artisan scale:doctor
php artisan scale:health

If your app currently runs on PHP 8.1 during local development, install with:

composer require "laravel-scale/core:dev-main as 1.0.99" "laravel-scale/query:dev-main as 1.0.99" "laravel-scale/index:dev-main as 1.0.99" "laravel-scale/cache:dev-main as 1.0.99" "laravel-scale/monitor:dev-main as 1.0.99" --ignore-platform-req=php

Use --ignore-platform-req=php for local dev only. Recommended setup is PHP 8.2+.

For a step-by-step setup guide, see docs/getting-started.md.

Configuration

config/scale.php:

return [
    'enabled' => true,
    'driver' => 'auto',
    'monitoring' => [
        'enabled' => true,
        'sampling' => 10,
    ],
    'query' => [
        'slow_threshold' => 500,
    ],
    'storage' => [
        'enabled' => true,
    ],
];

Facade API

use LaravelScale\Facades\Scale;

Scale::analyze();
Scale::health();
Scale::report();
Scale::score();
Scale::chunk(App\Models\Order::class);
Scale::cursor(App\Models\Order::class);

Commands

• php artisan scale:doctor
• php artisan scale:queries
• php artisan scale:indexes
• php artisan scale:database
• php artisan scale:health
• php artisan scale:report --format=json
• php artisan scale:archive
• php artisan scale:cleanup

Extending Database Drivers

use LaravelScale\Facades\Scale;

Scale::extendDatabaseDriver('custom', App\Scale\Drivers\CustomDriver::class);

Event System

Events include:

• SlowQueryDetected
• IndexRecommendationCreated
• NPlusOneDetected
• HealthScoreChanged
• ArchiveCompleted
• StorageWarning

Testing

composer test
composer analyse
vendor/bin/php-cs-fixer fix --dry-run --diff

License

MIT