themattosdev/leakless

Zero state and memory leak prevention for PHP persistent runtimes (FrankenPHP & Laravel Octane)

v0.5.1 2026-08-19 02:36 UTC

Requires

• php: ^8.2
• ext-pcntl: *
• ext-posix: *

Requires (Dev)

• laravel/pint: ^1.18
• orchestra/testbench: ^9.0 || ^10.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• phpstan/phpstan: ^2.0
• themattosdev/leakless-dev: *@dev

MIT

• Jonathan Gonçalves

Published on Packagist.org on 2026-08-19 02:36 UTC

README

Zero-State & Memory Leak Prevention for PHP Persistent Workers (FrankenPHP & Laravel Octane)

Overview

In traditional PHP-FPM, worker processes terminate after each request, allowing the OS to wipe memory and state. Persistent runtimes like FrankenPHP Worker Mode and Laravel Octane keep PHP in memory across thousands of requests. While significantly faster, persistent workers can suffer from unmonitored C-extension memory growth, dangling database transactions, and polluted global state.

Leakless is an autonomous guardian for persistent PHP: it reads real Linux kernel RSS from /proc/self/statm, rolls back uncommitted PDO transactions, cleans runtime state in finally blocks, and provides static analysis via PHPStan and Pest assertions.

Installation

# Runtime engine (production)
composer require themattosdev/leakless

# Developer tooling, CLI analyzer, and Pest assertions
composer require --dev themattosdev/leakless-dev

Usage

1. Vanilla PHP / FrankenPHP Loop

use TheMattos\Leakless\DTOs\Config;
use TheMattos\Leakless\Integrations\FrankenPhp\FrankenPhp;

FrankenPHP::run(
    app: function () {
        echo json_encode(['status' => 'ok']);
    },
    config: new Config(maxRssMb: 96, maxRequests: 1000),
);

2. Laravel Octane (Zero-Config)

LEAKLESS_ENABLED=true
LEAKLESS_MAX_RSS_MB=96
LEAKLESS_CHECK_TRANSACTIONS=true
LEAKLESS_CHECK_FILE_DESCRIPTORS=false

3. Automated Testing (Pest & PHPUnit)

test('service executes cleanly without leaking memory or state', function () {
    expect(PaymentService::class)->toBeLeakless();

    expect(function () {
        (new PaymentService())->processPendingTransactions();
    })->toRunCleanly(maxDriftMb: 0.25);
});

4. Static Worker Linter CLI

vendor/bin/leakless analyze

Documentation

Full documentation, architecture guides, kernel memory details, and anti-pattern catalogues are available at:

👉 https://leakless.themattos.dev

Testing & Quality

# Run test suite
docker compose run --rm app vendor/bin/pest

# Code style
docker compose run --rm app vendor/bin/pint --test

# Static analysis (Level 9)
docker compose run --rm app composer analyse

License

Open-source software licensed under the MIT License.
Developed by Jonathan Gonçalves.