Configuration Reference

Leakless is configured via the TheMattos\Leakless\Config object in vanilla PHP, or via .env / config/leakless.php in Laravel Octane.

---

1. Vanilla PHP Configuration

Instantiate the Config object with your desired options:

use TheMattos\Leakless\DTOs\Config;

$config = new Config(
    maxDriftMb: 64,                     // Allowable memory drift above worker baseline (MB)
    maxRssMb: null,                     // Hard emergency ceiling (MB) for OOM prevention (optional)
    consecutiveViolationsThreshold: 5,  // Consecutive requests required before recycling
    recycleCooldownSeconds: 10,         // Minimum seconds between worker restarts (prevents restart storms)
    triggerGcOnBreach: true,            // Re-evaluate physical memory after gc_collect_cycles()
    driftJitterPercentage: 10,          // Random variation to desynchronize worker recycles
    maxRequests: 1000,                  // Ceiling on requests before worker recycling
    checkTransactions: true,            // Auto-rollback uncommitted PDO transactions
    checkFileDescriptors: false,        // Audit unclosed file handles (/proc/self/fd)
    autoRecycleOnViolation: true,       // Graceful worker recycling when breached
    logViolations: true,                // Emit warnings on anomalies
    resettables: [                      // Array of class-strings, objects, or callbacks to auto-reset
        App\Services\CartSession::class,
        fn () => LegacyRegistry::$cache = [],
    ],
    ztsAware: null,                     // Enable ZTS multithread attribution (null = auto-detect via PHP_ZTS)
    threadToleranceMb: 2.0,             // Minimum thread Zend memory growth (MB) to attribute process drift
    unattributedViolationsThreshold: 10,// Consecutive un-attributed breaches before recycling (native C leaks)
);

---

2. Environment Variables (.env)

In Laravel Octane environments, configure Leakless using .env variables:

LEAKLESS_ENABLED=true
LEAKLESS_MAX_DRIFT_MB=64
LEAKLESS_MAX_RSS_MB=null
LEAKLESS_CONSECUTIVE_VIOLATIONS=5
LEAKLESS_RECYCLE_COOLDOWN=10
LEAKLESS_TRIGGER_GC=true
LEAKLESS_DRIFT_JITTER=10
LEAKLESS_MAX_REQUESTS=1000
LEAKLESS_CHECK_TRANSACTIONS=true
LEAKLESS_CHECK_FILE_DESCRIPTORS=false
LEAKLESS_AUTO_RECYCLE=true
LEAKLESS_LOG_VIOLATIONS=true
LEAKLESS_ZTS_AWARE=null
LEAKLESS_THREAD_TOLERANCE_MB=2.0
LEAKLESS_UNATTRIBUTED_THRESHOLD=10

Or publish config/leakless.php:

php artisan vendor:publish --tag="leakless-config"

---

3. Configuration Reference Table

Key	Environment Variable	Default	Description
enabled	LEAKLESS_ENABLED	true	Master toggle to enable or disable Leakless audits.
max_drift_mb	LEAKLESS_MAX_DRIFT_MB	64	Allowable relative RSS growth (in MB) above worker baseline before recycling evaluation.
max_rss_mb	LEAKLESS_MAX_RSS_MB	null	Hard emergency physical RSS ceiling (MB) to prevent Linux OOM Killer SIGKILL.
consecutive_violations	LEAKLESS_CONSECUTIVE_VIOLATIONS	5	Hysteresis: consecutive post-GC breaches required before recycling worker.
recycle_cooldown	LEAKLESS_RECYCLE_COOLDOWN	10	Cooldown window in seconds between worker recycles (prevents restart storms).
trigger_gc	LEAKLESS_TRIGGER_GC	true	Invokes gc_collect_cycles() and re-reads /proc/self/statm on suspected breach.
drift_jitter	LEAKLESS_DRIFT_JITTER	10	Percentage variation applied to max_drift_mb to desynchronize restarts across workers.
max_requests	LEAKLESS_MAX_REQUESTS	null	Maximum request count per worker before triggering graceful recycling (null = unlimited).
check_transactions	LEAKLESS_CHECK_TRANSACTIONS	true	Automatically audits and rolls back open PDO transactions at request completion.
check_file_descriptors	LEAKLESS_CHECK_FILE_DESCRIPTORS	false	Inspects /proc/self/fd for unclosed file handles and lingering network sockets.
auto_recycle	LEAKLESS_AUTO_RECYCLE	true	Automatically stops the worker when thresholds or persistent corruption are confirmed.
log_violations	LEAKLESS_LOG_VIOLATIONS	true	Emits diagnostic logs when uncommitted transactions or state leaks are caught.
resettables	—	[]	List of class-strings, objects, or callbacks to automatically reset at the end of each request.
zts_aware	LEAKLESS_ZTS_AWARE	null	Enable ZTS thread-safe memory attribution (null for auto-detect via PHP_ZTS).
thread_tolerance_mb	LEAKLESS_THREAD_TOLERANCE_MB	2.0	Minimum Zend MM growth (MB) required to attribute process RSS drift to the active thread.
unattributed_violations_threshold	LEAKLESS_UNATTRIBUTED_THRESHOLD	10	Consecutive un-attributed RSS drift checks before recycling (protects against native C leaks).