Laravel Test Lanes

https://github.com/mozex/laravel-test-lanes
Admin
Give every concurrent Laravel test run its own databases by claiming a machine-unique lane for each...
Tokens:35,784
Snippets:223
Trust Score:8.5
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Package configuration with install command

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/service-provider.md

Declares package capabilities: sets the name, publishes the config file, registers the cleanup command, and configures the install command to publish config and ask to star the repository.

```php
$package
    ->name('laravel-test-lanes')
    ->hasConfigFile()
    ->hasCommand(CleanupCommand::class)
    ->hasInstallCommand(function (InstallCommand $command): void {
        $command
            ->publishConfigFile()
            ->endWith(fn (InstallCommand $command) => $this->askToStar($command));
    });
```

--------------------------------

### Published config file example

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/service-provider.md

Example of a user-edited config file showing that user values override defaults for specific keys while others are filled from package defaults.

```php
// config/test-lanes.php (published, user-edited)
return [
    'enabled' => false,                        // user wins
    'locks' => [
        'pgsql' => 'App\Locks\CustomLock',     // user wins for pgsql
        // mysql and mariadb are filled in from the package defaults
    ],
];
```

--------------------------------

### Artisan commands for install and cleanup

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/service-provider.md

Commands to publish the config file and to drop free lane databases.

```bash
# Publishes config/test-lanes.php (then asks to star the repo)
php artisan test-lanes:install

# Drops free lane databases (see cleanup-command.md)
php artisan test-lanes:cleanup
```

--------------------------------

### Install Test Lanes Configuration

Source: https://github.com/mozex/laravel-test-lanes/blob/main/README.md

Run this command to publish the configuration file at config/test-lanes.php.

```bash
php artisan test-lanes:install
```

--------------------------------

### Example: TestLanes::poolSize()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Example usage of TestLanes::poolSize(). It returns the configured pool size, which defaults to 256. The comment indicates the default value.

```php
use Mozex\TestLanes\TestLanes;

$pool = TestLanes::poolSize(); // 256 by default
```

--------------------------------

### TestLanes::register()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Documentation for the static `register()` method of the `Mozex\TestLanes\TestLanes` class, including its purpose, behavior, and usage examples.

```APIDOC
## `register`

### Description
Registers the test-lanes token resolver with Laravel's parallel-testing machinery, routing every test run through a per-process lane database.

### Method
`public static function register(): void`

### Parameters
None.

### Return Type
`void`

### Throws
None. Failures surface later through `claim()`.

### Behavior
- Reads `test-lanes.enabled` from config (default `true`); returns immediately if disabled.
- Sets `$_SERVER['LARAVEL_PARALLEL_TESTING']` to `1`.
- Registers `fn (): string => self::claim()` as the token resolver via `ParallelTesting::resolveTokenUsing()`.
- Idempotent: calling twice re-registers the same resolver and re-sets the flag.

### Usage Notes
- The service provider calls this automatically when `APP_ENV=testing`.
- Call manually from `createApplication()` in your base `TestCase` when running under another environment.
- Calling earlier (e.g., in `Pest.php`) causes a facade root error.

### Example: Manual registration from a base TestCase
```php
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use Mozex\TestLanes\TestLanes;

abstract class TestCase extends BaseTestCase
{
    public function createApplication()
    {
        $app = parent::createApplication();

        TestLanes::register();

        return $app;
    }
}
```

### Example: Switching the package off entirely
Set the config `enabled` key to `false` (or export `TEST_LANES_ENABLED=false`). `register()` then does nothing.

```php
// config/test-lanes.php
return [
    'enabled' => false,
    // ...
];
```
```

--------------------------------

### TestLanes::claim()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Documentation for the TestLanes::claim() static method, including its signature, parameters, return type, exceptions, and usage examples.

```APIDOC
## `TestLanes::claim()`

### Description
Returns the lane token for the current process, either the already-held lane or a newly acquired one from the pool. If the default connection is in-memory SQLite, it returns an empty string to disable parallel testing.

### Method
`TestLanes::claim()`

### Signature
```php
public static function claim(): string
```

### Parameters
None.

### Return Type
`string` — the lane token (`'lane' . $lane`, e.g. `lane1`), or an empty string `''` for an in-memory SQLite suite.

### Throws
| Error | Condition |
|-------|-----------|
| `TestLanesException::holderConnectionFailed` | The lock-holder PDO connection could not be opened (wraps the underlying `PDOException`). |
| `TestLanesException::unsupportedDriver` | The active connection's driver has no entry in the `test-lanes.locks` config map. |
| `TestLanesException::urlConfiguredConnection` | The connection is configured with a `url` key instead of discrete `host`/`port`/`database` keys. |
| `TestLanesException::invalidPoolSize` | The configured `test-lanes.pool_size` resolves below 1. |
| `TestLanesException::poolExhausted` | Every lane in the pool is held by another process. |

### Description
Returns the lane this process already holds, if any. Otherwise it takes Laravel's current default database connection and:
1. If the connection's database name is `:memory:` (in-memory SQLite), returns `''` — the parallel machinery switches itself off for a suite that already has a private database per process. This bail is deliberately **not** memoized: an app that boots on `:memory:` and later points the default connection at a real server must claim a real lane on its next call, not inherit the no-op answer.
2. Resolves the `AdvisoryLock` implementation for the connection's driver and reads the connection config from the `database.connections.<name>` config tree.
3. Opens the holder connection (a raw PDO handle).
4. Computes the lock namespace with `namespaceFor(databaseName)` and the pool size with `poolSize()`.
5. Iterates lanes 1..pool and returns the first whose advisory lock it can take (`tryAcquire`). Sets `$holder` and `$lane` before returning.

The lane is handed back to Laravel every time the parallel machinery asks for a token (the resolver stays registered, and `ParallelTesting` memoizes the token per app instance anyway).

### Example: basic claim
```php
use Illuminate\Support\Facades\DB;
use Mozex\TestLanes\TestLanes;

// Called by the token resolver registered through TestLanes::register().
// After the first call every later call returns the same lane:
$lane = TestLanes::claim();   // e.g. "lane1"

DB::statement("SELECT current_database()"); // the suite now runs on {base}_test_lane1
```

### Example: error handling
```php
use Mozex\TestLanes\Exceptions\TestLanesException;
use Mozex\TestLanes\TestLanes;

try {
    $lane = TestLanes::claim();
} catch (TestLanesException $e) {
    // holderConnectionFailed, unsupportedDriver, urlConfiguredConnection,
    // invalidPoolSize, or poolExhausted
    report($e->getMessage());

    // Suggested remediation depends on the cause:
    // - poolExhausted:     raise TEST_LANES_POOL_SIZE if the concurrency is real
    // - unsupportedDriver: map an AdvisoryLock class under "locks" in config/test-lanes.php
    // - holderConnectionFailed: check the server, credentials, and that the base database exists
    // - urlConfiguredConnection: switch the connection to discrete host/port/database keys
}
```
```

--------------------------------

### Install Laravel Test Lanes via Composer

Source: https://github.com/mozex/laravel-test-lanes/blob/main/README.md

Install the package as a development dependency in your Laravel project.

```bash
composer require mozex/laravel-test-lanes --dev
```

--------------------------------

### Publish config with php artisan test-lanes:install

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/configuration.md

Publishes the package configuration file to config/test-lanes.php. Run this artisan command to make the configuration available for customization.

```bash
php artisan test-lanes:install
```

--------------------------------

### Basic claim example

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Basic usage of TestLanes::claim() to obtain a lane token. The token is memoized per app instance, so subsequent calls return the same lane.

```php
use Illuminate\Support\Facades\DB;
use Mozex\TestLanes\TestLanes;

// Called by the token resolver registered through TestLanes::register().
// After the first call every later call returns the same lane:
$lane = TestLanes::claim();   // e.g. "lane1"

DB::statement("SELECT current_database()"); // the suite now runs on {base}_test_lane1
```

--------------------------------

### Custom driver configuration in config/test-lanes.php

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/advisory-lock.md

Shows how to map a custom advisory lock implementation under the 'locks' key in the config file. The example adds 'my_driver' alongside the default pgsql, mysql, and mariadb mappings.

```php
// config/test-lanes.php
use App\Locks\MyDriverAdvisoryLock;
use Mozex\TestLanes\Locks\PgsqlAdvisoryLock;
use Mozex\TestLanes\Locks\MysqlAdvisoryLock;

return [
    'enabled' => (bool) env('TEST_LANES_ENABLED', true),
    'pool_size' => (int) env('TEST_LANES_POOL_SIZE', 256),
    'locks' => [
        'pgsql' => PgsqlAdvisoryLock::class,
        'mysql' => MysqlAdvisoryLock::class,
        'mariadb' => MysqlAdvisoryLock::class,
        'my_driver' => MyDriverAdvisoryLock::class,
    ],
];
```

--------------------------------

### Recover from TestLanesException by configuration

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/test-lanes-exception.md

Recover from TestLanesException by checking the message for 'locks' to handle unsupportedDriver by running artisan('test-lanes:install') after mapping an AdvisoryLock in config/test-lanes.php under "locks". For other errors (holderConnectionFailed, invalidPoolSize, urlConfiguredConnection, poolExhausted), rethrow the exception because each message names its own fix.

```php
use Mozex\TestLanes\Exceptions\TestLanesException;

try {
    $lanes = TestLanes::claim();
} catch (TestLanesException $e) {
    if (str_contains($e->getMessage(), 'locks')) {
        // unsupportedDriver — map an AdvisoryLock for the driver in
        // config/test-lanes.php under "locks"
        artisan('test-lanes:install');
    } else {
        // holderConnectionFailed, invalidPoolSize, urlConfiguredConnection,
        // or poolExhausted — each message names its own fix
        throw $e;
    }
}
```

--------------------------------

### configurePackage method signature

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/service-provider.md

Method signature for configuring the package, accepting a Spatie Package instance.

```php
public function configurePackage(Package $package): void
```

--------------------------------

### Basic cleanup run

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/cleanup-command.md

Runs the cleanup command with no options. The output shows two lane databases being dropped and a summary line.

```bash
php artisan test-lanes:cleanup
```

```text
Dropped [my_app_test_lane1].
Dropped [my_app_test_lane2].
Dropped 2 lane databases.
```

--------------------------------

### Run test suite and individual checks

Source: https://github.com/mozex/laravel-test-lanes/blob/main/CLAUDE.md

Commands to execute the full test suite, individual linting, static analysis, type coverage, and unit tests.

```bash
# Run all checks (formatting + static analysis + type coverage + tests)
composer test

# Individual checks
composer lint                  # Fix code formatting (Pint)
composer test:lint             # Check code formatting without fixing
composer test:types            # PHPStan static analysis (level 6)
composer test:type-coverage    # Pest type coverage (minimum 100%)
composer test:unit             # Run Pest tests

# Run a single test file
./vendor/bin/pest tests/LocksTest.php

# Run a single test by name
./vendor/bin/pest --filter="test name here"
```

--------------------------------

### Manual TestLanes::register() in base TestCase

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Manual registration from a base TestCase's createApplication() when the suite runs under a non-testing environment. Calling register() earlier (e.g. in Pest.php) makes the ParallelTesting facade throw "A facade root has not been set".

```php
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use Mozex\TestLanes\TestLanes;

abstract class TestCase extends BaseTestCase
{
    public function createApplication()
    {
        $app = parent::createApplication();

        TestLanes::register();

        return $app;
    }
}

```

--------------------------------

### TestLanesServiceProvider class with repository property

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/service-provider.md

Defines the service provider class with a protected repository URL property used by the star question, browser-opener fallback note, and printed link.

```php
class TestLanesServiceProvider extends PackageServiceProvider
{
    protected string $repository = 'https://github.com/mozex/laravel-test-lanes';
}
```

--------------------------------

### Error handling for URL-configured connection

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/cleanup-command.md

Shows the error when the --connection option points to a URL-configured connection. The command throws a TestLanesException instead of guessing the connection details.

```php
// A URL-configured connection is refused rather than guessed at.
php artisan test-lanes:cleanup --connection=legacy
// Mozex\TestLanes\Exceptions\TestLanesException:
// "Test lanes cannot read the URL-configured [legacy] connection. ..."
```

--------------------------------

### openInBrowser method signature

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/service-provider.md

Protected method that opens the repository URL in the browser. Returns true on success, false on failure.

```php
protected function openInBrowser(): bool
```

--------------------------------

### Test Lanes Configuration File

Source: https://github.com/mozex/laravel-test-lanes/blob/main/README.md

The config/test-lanes.php file allows you to toggle the package, set the pool size, and map advisory locks for different database drivers.

```php
return [
    'enabled' => (bool) env('TEST_LANES_ENABLED', true),

    'pool_size' => (int) env('TEST_LANES_POOL_SIZE', 256),

    'locks' => [
        'pgsql' => PgsqlAdvisoryLock::class,
        'mysql' => MysqlAdvisoryLock::class,
        'mariadb' => MysqlAdvisoryLock::class,
    ],
];
```

--------------------------------

### Custom Driver Configuration

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/advisory-lock.md

Shows how to register a custom advisory lock driver in the configuration file.

```APIDOC
## Custom Driver Configuration

### Description
To implement a custom advisory lock driver, map your implementation under `locks` in `config/test-lanes.php`.

### Configuration Example

```php
// config/test-lanes.php
use App\Locks\MyDriverAdvisoryLock;
use Mozex\TestLanes\Locks\PgsqlAdvisoryLock;
use Mozex\TestLanes\Locks\MysqlAdvisoryLock;

return [
    'enabled' => (bool) env('TEST_LANES_ENABLED', true),
    'pool_size' => (int) env('TEST_LANES_POOL_SIZE', 256),
    'locks' => [
        'pgsql' => PgsqlAdvisoryLock::class,
        'mysql' => MysqlAdvisoryLock::class,
        'mariadb' => MysqlAdvisoryLock::class,
        'my_driver' => MyDriverAdvisoryLock::class,
    ],
];
```
```

--------------------------------

### Connect and use PgsqlAdvisoryLock directly

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/advisory-lock.md

Directly connect to a PostgreSQL advisory lock backend and acquire/release a lock. Use only when implementing or debugging a lock backend; normal usage goes through TestLanes::lock(). The connect() call throws PDOException on failure.

```php
use Mozex\TestLanes\Locks\PgsqlAdvisoryLock;

$config = [
    'host' => '127.0.0.1',
    'port' => 5432,
    'database' => 'my_app_test',
    'username' => 'postgres',
    'password' => 'postgres',
];

$pdo = (new PgsqlAdvisoryLock())->connect($config); // throws PDOException on failure

// Both lock backends are consumed in the same shape by TestLanes::claim():
$acquired = $pgsql->tryAcquire($pdo, 123456789, 1); // bool
$pgsql->release($pdo, 123456789, 1);
```

--------------------------------

### MysqlAdvisoryLock

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/advisory-lock.md

Documentation for the MysqlAdvisoryLock class, including its public methods connect, tryAcquire, and release, along with protected helper methods.

```APIDOC
## `MysqlAdvisoryLock`

### Description
Implements the `AdvisoryLock` interface for MySQL and MariaDB drivers, providing advisory locking via `GET_LOCK`/`RELEASE_LOCK`.

### Methods

#### `connect`

```php
public function connect(array $config): PDO
```

Builds the DSN `mysql:host={host};port={port}`; a `dbname` is appended only when the config's `database` key is non-empty. Returns a new PDO handle with `PDO::ERRMODE_EXCEPTION`.

##### Parameters
- **$config** (array) - Required - Configuration array with the following keys:
  - `host` (string) - Optional - Default `'127.0.0.1'` - Server host.
  - `port` (int) - Optional - Default `3306` - Server port.
  - `database` (string) - Optional - Database name; appended to DSN only when non-empty.
  - `username` (string) - Optional - Credential, passed through `credential()`.
  - `password` (string) - Optional - Credential, passed through `credential()`.

##### Returns
- **PDO** - A new PDO connection with `ERRMODE_EXCEPTION`.

#### `tryAcquire`

```php
public function tryAcquire(PDO $connection, int $namespace, int $lane): bool
```

Attempts to acquire an advisory lock with a zero timeout (never waits). Returns `true` if acquired, `false` otherwise.

##### Parameters
- **$connection** (PDO) - Required - The PDO connection.
- **$namespace** (int) - Required - Namespace identifier for the lock.
- **$lane** (int) - Required - Lane identifier for the lock.

##### Returns
- **bool** - `true` if the lock was acquired, `false` otherwise.

#### `release`

```php
public function release(PDO $connection, int $namespace, int $lane): void
```

Releases an advisory lock.

##### Parameters
- **$connection** (PDO) - Required - The PDO connection.
- **$namespace** (int) - Required - Namespace identifier for the lock.
- **$lane** (int) - Required - Lane identifier for the lock.

##### Returns
- **void** - No return value.

#### `key` (protected)

```php
protected static function key(int $namespace, int $lane): string
```

Returns the user-level lock name used for `GET_LOCK`/`RELEASE_LOCK`.

##### Parameters
- **$namespace** (int) - Required - Namespace identifier.
- **$lane** (int) - Required - Lane identifier.

##### Returns
- **string** - The lock name in the format `{namespace}-test-lane-{lane}`.

#### `credential` (protected)

```php
protected static function credential(array $config, string $key): ?string
```

Returns the credential value from the config array if set, otherwise `null`.

##### Parameters
- **$config** (array) - Required - Configuration array.
- **$key** (string) - Required - Configuration key to retrieve.

##### Returns
- **?string** - The credential value or `null` if not set.
```

--------------------------------

### Error handling for unknown connection

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/cleanup-command.md

Shows the error when the --connection option names an unknown connection. The command exits with a FAILURE status and prints an error line.

```bash
php artisan test-lanes:cleanup --connection=nope
```

```text
The [nope] connection is not configured.
```

--------------------------------

### Cleanup with a live claimant

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/cleanup-command.md

Runs the cleanup command while a test process is still using a lane. The command deliberately does not drop the database of a live run.

```bash
php artisan test-lanes:cleanup
```

```text
Kept [my_app_test_lane3]: its lane is claimed by a running test process.
Dropped [my_app_test_lane1].
Dropped 1 lane database, kept 1 in use.
```

--------------------------------

### TestLanesException class definition with factory signatures

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/test-lanes-exception.md

Shows the class declaration and the signatures of its five static factories. Each factory returns an instance of the exception with a descriptive message. The holderConnectionFailed factory chains the original PDOException as the previous cause.

```php
class TestLanesException extends RuntimeException
{
    public static function holderConnectionFailed(string $connection, array $config, PDOException $previous): self
    public static function invalidPoolSize(int $size): self
    public static function unsupportedDriver(string $driver, array $supported): self
    public static function urlConfiguredConnection(string $connection): self
    public static function poolExhausted(int $poolSize): self
}
```

--------------------------------

### Create advisory lock with TestLanes::lock()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Creates a fresh advisory lock instance for the given PDO driver. Reads the test-lanes.locks config map, falling back to the built-in map when the key is missing. Throws TestLanesException::unsupportedDriver for drivers not in the resolved map.

```php
use Mozex\TestLanes\TestLanes;

$lock = TestLanes::lock('pgsql'); // PgsqlAdvisoryLock instance
```

--------------------------------

### CleanupCommand signature and description

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/cleanup-command.md

Defines the command signature and description for the Artisan command. The signature includes an optional --connection option that defaults to the default connection. The description is used in the Artisan command list.

```php
protected $signature = 'test-lanes:cleanup
    {--connection= : The connection whose lane databases should be dropped (defaults to the default connection)}';

protected $description = 'Drop lane databases left behind by finished test runs';
```

--------------------------------

### Disable TestLanes via config/test-lanes.php

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Disables the package by setting the config 'enabled' key to false. register() then does nothing: no token resolver is registered and serial runs are not routed through the parallel-testing machinery.

```php
// config/test-lanes.php
return [
    'enabled' => false,
    // ...
];

```

--------------------------------

### Published config/test-lanes.php

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/configuration.md

The full published configuration file for the package. It defines the enabled flag, pool size, and the driver-to-implementation map for advisory locks. The defaults are resolved from environment variables TEST_LANES_ENABLED and TEST_LANES_POOL_SIZE.

```php
<?php

declare(strict_types=1);

use Mozex\TestLanes\Locks\MysqlAdvisoryLock;
use Mozex\TestLanes\Locks\PgsqlAdvisoryLock;

return [
    'enabled' => (bool) env('TEST_LANES_ENABLED', true),

    'pool_size' => (int) env('TEST_LANES_POOL_SIZE', 256),

    'locks' => [
        'pgsql' => PgsqlAdvisoryLock::class,
        'mysql' => MysqlAdvisoryLock::class,
        'mariadb' => MysqlAdvisoryLock::class,
    ],
];
```

--------------------------------

### Catching TestLanesException specifically or as RuntimeException

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/test-lanes-exception.md

Shows how to catch the exception specifically or as a generic RuntimeException fallback. The import statement is included. The comment references the full catalog in errors.md.

```php
use Mozex\TestLanes\Exceptions\TestLanesException;

try {
    TestLanes::claim();
} catch (TestLanesException $e) {
    // specific handling, see the full catalog in errors.md
} catch (RuntimeException $e) {
    // generic fallback
}
```

--------------------------------

### Handle unsupported driver error from TestLanes::lock()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Shows how to handle the TestLanesException thrown when an unsupported driver is passed to lock(). The error message indicates the driver name, and the fix is to map a custom AdvisoryLock implementation under 'locks' in config/test-lanes.php or disable the package.

```php
use Mozex\TestLanes\Exceptions\TestLanesException;
use Mozex\TestLanes\TestLanes;

try {
    TestLanes::lock('sqlserver');
} catch (TestLanesException $e) {
    // "Test lanes have no lock primitive for the [sqlserver] driver..."
    // Fix: map your own Mozex\TestLanes\Locks\AdvisoryLock implementation
    // under "locks" in config/test-lanes.php, or disable the package.
}
```

--------------------------------

### Catch and inspect TestLanesException

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/test-lanes-exception.md

Wrap TestLanes::claim() in a try-catch to catch TestLanesException and log the message with error_log(). Use this for basic inspection of failures.

```php
use Mozex\TestLanes\Exceptions\TestLanesException;
use Mozex\TestLanes\TestLanes;

try {
    TestLanes::claim();
} catch (TestLanesException $e) {
    error_log($e->getMessage());
}
```

--------------------------------

### Invoke test-lanes:cleanup command

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/cleanup-command.md

Invokes the cleanup command. The first command uses the default connection; the second specifies a connection name. The command drops lane databases left behind by finished test runs, skipping lanes with held locks.

```bash
php artisan test-lanes:cleanup
php artisan test-lanes:cleanup --connection=name
```

--------------------------------

### Calculate max_connections for test workers

Source: https://github.com/mozex/laravel-test-lanes/blob/main/README.md

Formula to determine the required database connection limit based on workers, concurrent runs, and connection overhead.

```text
max_connections >= connections per worker x (workers x concurrent runs) + headroom
```

--------------------------------

### TestLanesException::urlConfiguredConnection

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/test-lanes-exception.md

Factory method for the exception thrown when a connection uses a URL-style config.

```APIDOC
## `urlConfiguredConnection`

### Description
Creates a `TestLanesException` for when a connection is configured with a `url` key instead of discrete host, port, and database keys. The message instructs to use discrete keys.

### Method
`TestLanesException::urlConfiguredConnection` (static factory)

### Parameters
- **`$connection`** (`string`) - Required - The connection name whose config carries a `url` key.

### Returns
`self` - A new `TestLanesException` instance.

### Message
```
Test lanes cannot read the URL-configured [{connection}] connection. Configure the connection with discrete host, port, and database keys instead of a DB_URL-style value.
```

### Thrown By
- `TestLanes::connectionConfig()` (via `TestLanes::claim()`)
- `CleanupCommand::handle()`
```

--------------------------------

### Cleanup test lane databases

Source: https://github.com/mozex/laravel-test-lanes/blob/main/resources/boost/skills/laravel-test-lanes/SKILL.md

Executes the cleanup command for test lanes by specifying the test database name via the DB_DATABASE environment variable.

```bash
DB_DATABASE=app_testing php artisan test-lanes:cleanup
```

--------------------------------

### Manually Register TestLanes in TestCase

Source: https://github.com/mozex/laravel-test-lanes/blob/main/README.md

Register the package manually in your base TestCase if your test suite runs in an environment other than testing.

```php
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use Mozex\TestLanes\TestLanes;

abstract class TestCase extends BaseTestCase
{
    public function createApplication()
    {
        $app = parent::createApplication();

        TestLanes::register();

        return $app;
    }
}
```

--------------------------------

### TestLanes class declaration with static properties

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Shows the class declaration with its two protected static properties: $holder (a ?PDO holding the advisory lock) and $lane (a ?string lane token). Both default to null.

```php
class TestLanes
{
    protected static ?PDO $holder = null;

    protected static ?string $lane = null;
}

```

--------------------------------

### AdvisoryLock interface definition

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/types.md

The package's only exported interface. Implement it to teach lane claiming a new database driver. The connect() method must open a PDO handle Laravel does not manage, tryAcquire() returns false when another process holds the lock, and release() releases a lane's lock.

```php
interface AdvisoryLock
{
    /**
     * Open a PDO handle Laravel does not manage, so the lock outlives any
     * reconnect or purge on the framework's own connections.
     *
     * @param  array<string, mixed>  $config
     */
    public function connect(array $config): PDO;

    /**
     * Take a lane's lock without waiting. Returns false when another process
     * already holds it.
     */
    public function tryAcquire(PDO $connection, int $namespace, int $lane): bool;

    /**
     * Release a lane's lock taken on this connection.
     */
    public function release(PDO $connection, int $namespace, int $lane): void;
}
```

--------------------------------

### TestLanes::lock()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Creates a new advisory lock instance for the given PDO driver. Reads the lock implementation from the `test-lanes.locks` config, falling back to built-in implementations for pgsql, mysql, and mariadb. Throws an exception for unsupported drivers.

```APIDOC
## `lock`

```php
public static function lock(string $driver): AdvisoryLock
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `driver` | `string` | — | PDO driver name of the active connection (e.g. `pgsql`, `mysql`, `mariadb`). |

**Return type:** `AdvisoryLock` — a fresh instance of the configured lock implementation for the driver.

**Throws:**

| Error | Condition |
|-------|-----------|
| `TestLanesException::unsupportedDriver` | `$driver` has no entry in the `test-lanes.locks` config map. The supported list is taken from the keys of the resolved map. |

**What it does:** Reads `test-lanes.locks` from the config. When the key is missing entirely it falls back to the built-in map `['pgsql' => PgsqlAdvisoryLock::class, 'mysql' => MysqlAdvisoryLock::class, 'mariadb' => MysqlAdvisoryLock::class]` — this fallback matters when the app cached its config before the package was installed and the provider's merge never ran. Unknown drivers fail loudly by design: a constant fallback would silently reinstate the exact database collision the package exists to prevent. See [advisory-lock.md](advisory-lock.md) for how to teach the package a new driver.

### Example: basic

```php
use Mozex\TestLanes\TestLanes;

$lock = TestLanes::lock('pgsql'); // PgsqlAdvisoryLock instance
```

### Example: error handling

```php
use Mozex\TestLanes\Exceptions\TestLanesException;
use Mozex\TestLanes\TestLanes;

try {
    TestLanes::lock('sqlserver');
} catch (TestLanesException $e) {
    // "Test lanes have no lock primitive for the [sqlserver] driver..."
    // Fix: map your own Mozex\TestLanes\Locks\AdvisoryLock implementation
    // under "locks" in config/test-lanes.php, or disable the package.
}
```
```

--------------------------------

### Handle PDOException from MysqlAdvisoryLock::connect()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/advisory-lock.md

Catch PDOException when connecting directly to the MySQL advisory lock backend. The exception is thrown for server down, bad credentials, or missing base database. In normal flow, TestLanes::claim() converts this to TestLanesException::holderConnectionFailed.

```php
use Mozex\TestLanes\Locks\MysqlAdvisoryLock;
use PDOException;

try {
    (new MysqlAdvisoryLock())->connect($config);
} catch (PDOException $e) {
    // server down, bad credentials, or the base database does not exist
}
```

--------------------------------

### Mozex\TestLanes\Locks\AdvisoryLock

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/types.md

The `AdvisoryLock` interface is the package's only exported interface, used to extend lane claiming to new database drivers. It defines three methods: `connect`, `tryAcquire`, and `release`.

```APIDOC
## `Mozex\TestLanes\Locks\AdvisoryLock`

### Description
Interface that teaches lane claiming a new database driver. Implementations: `PgsqlAdvisoryLock`, `MysqlAdvisoryLock`.

### Methods

#### `connect(array<string, mixed> $config): PDO`

Opens a PDO handle Laravel does not manage, so the lock outlives any reconnect or purge on the framework's own connections.

##### Parameters
- **$config** (array<string, mixed>) - Required - Resolved Laravel `database.connections.<name>` entry.

##### Returns
- **PDO** - A PDO handle.

#### `tryAcquire(PDO $connection, int $namespace, int $lane): bool`

Takes a lane's lock without waiting. Returns `false` when another process already holds it.

##### Parameters
- **$connection** (PDO) - Required - The PDO connection.
- **$namespace** (int) - Required - The namespace.
- **$lane** (int) - Required - The lane.

##### Returns
- **bool** - `true` if acquired, `false` if already held.

#### `release(PDO $connection, int $namespace, int $lane): void`

Releases a lane's lock taken on this connection.

##### Parameters
- **$connection** (PDO) - Required - The PDO connection.
- **$namespace** (int) - Required - The namespace.
- **$lane** (int) - Required - The lane.

##### Returns
- **void** - No return value.
```

--------------------------------

### Release a claimed lane with TestLanes::release()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Releases the currently claimed lane by clearing the static holder and lane state. The token resolver stays registered, so the next token resolution claims a lane again, possibly a different one. Calling it without a prior claim is a no-op.

```php
use Mozex\TestLanes\TestLanes;

TestLanes::release(); // next claim() may return a different lane
```

--------------------------------

### TestLanes::poolSize()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Static method on the TestLanes class that returns the configured lane pool size, defaulting to 256, and validates that the value is at least 1.

```APIDOC
## `poolSize`

### Description
Returns the configured lane pool size, defaulting to 256, and validates that it is at least 1.

### Method
`TestLanes::poolSize()`

### Signature
```php
public static function poolSize(): int
```

### Parameters
None.

### Return Type
`int` — the configured lane pool size (default `256`).

### Throws
| Error | Condition |
|-------|-----------|
| `TestLanesException::invalidPoolSize` | The configured `test-lanes.pool_size` value resolves below 1. |

### Example
```php
use Mozex\TestLanes\TestLanes;

$pool = TestLanes::poolSize(); // 256 by default
```
```

--------------------------------

### Error handling for claim()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Error handling for TestLanes::claim() when it throws TestLanesException. The exception can be one of holderConnectionFailed, unsupportedDriver, urlConfiguredConnection, invalidPoolSize, or poolExhausted, each with its own remediation.

```php
use Mozex\TestLanes\Exceptions\TestLanesException;
use Mozex\TestLanes\TestLanes;

try {
    $lane = TestLanes::claim();
} catch (TestLanesException $e) {
    // holderConnectionFailed, unsupportedDriver, urlConfiguredConnection,
    // invalidPoolSize, or poolExhausted
    report($e->getMessage());

    // Suggested remediation depends on the cause:
    // - poolExhausted:     raise TEST_LANES_POOL_SIZE if the concurrency is real
    // - unsupportedDriver: map an AdvisoryLock class under "locks" in config/test-lanes.php
    // - holderConnectionFailed: check the server, credentials, and that the base database exists
    // - urlConfiguredConnection: switch the connection to discrete host/port/database keys
}
```

--------------------------------

### TestLanes::namespaceFor()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Computes a lock namespace for a given database name by hashing it with crc32 and masking into the positive int4 range. This prevents lane collisions between different base databases on the same server.

```APIDOC
## `namespaceFor`

```php
public static function namespaceFor(string $database): int
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `database` | `string` | — | Base database name whose lock namespace is computed. |

**Return type:** `int` — `crc32($database) & 0x7FFFFFFF`: the crc32 hash masked into the positive int4 range. The mask is load-bearing — crc32 is unsigned 32-bit while Postgres advisory lock keys are signed int4, and real database names overflow without it. The namespace keeps one base database's lanes from colliding with another's on the same server.

### Example

```php
use Mozex\TestLanes\TestLanes;

$namespace = TestLanes::namespaceFor('my_app_test'); // always >= 0
```
```

--------------------------------

### test-lanes:cleanup

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/cleanup-command.md

Drops lane databases left behind by finished test runs. Skips lanes with held locks. Optionally specify a connection.

```APIDOC
## [ARTISAN] test-lanes:cleanup

### Description
Drops lane databases left behind by finished test runs. Skips lanes with held locks to avoid interfering with live test processes.

### Method
Artisan command

### Endpoint
`php artisan test-lanes:cleanup`

### Parameters
#### Options
- `--connection` (string) - Optional - The connection whose lane databases should be dropped. Defaults to `DB::getDefaultConnection()`.

### Request Example
```bash
php artisan test-lanes:cleanup
php artisan test-lanes:cleanup --connection=name
```

### Response
#### Exit Status
- `self::SUCCESS` on completion
- `self::FAILURE` when the named connection is not configured

```

--------------------------------

### poolSize() method signature

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Signature of the poolSize() method. It returns an integer representing the configured lane pool size, defaulting to 256. Throws TestLanesException::invalidPoolSize if the configured value is below 1.

```php
public static function poolSize(): int
```

--------------------------------

### claim() method signature

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Signature of the claim() method. It returns the lane token (e.g., 'lane1') or an empty string for in-memory SQLite suites.

```php
public static function claim(): string
```

--------------------------------

### TestLanesException::holderConnectionFailed

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/test-lanes-exception.md

Factory method for the exception thrown when the lock-holder PDO connection fails to open.

```APIDOC
## `holderConnectionFailed`

### Description
Creates a `TestLanesException` for when the package's own lock-holder PDO connection cannot be opened. The exception message includes the connection name, host, port, database, and the underlying PDO error.

### Method
`TestLanesException::holderConnectionFailed` (static factory)

### Parameters
- **`$connection`** (`string`) - Required - Connection name (e.g. `DB::getDefaultConnection()`).
- **`$config`** (`array<string, mixed>`) - Required - The connection's resolved config; `host`, `port`, and `database` are read from it with defaults `'127.0.0.1'`, `''`, `''` for the message.
- **`$previous`** (`PDOException`) - Required - The underlying PDO connection failure, chained as the cause.

### Returns
`self` - A new `TestLanesException` instance.

### Message
```
Test lanes could not open its lock-holder connection to [{host}:{port}/{database}] for the [{connection}] connection: {previous message}. The holder is the package's own PDO handle, separate from Laravel's; check that the server is running, the credentials are right, and the base database exists. If this suite does not need a database at all, set TEST_LANES_ENABLED=false to switch lanes off.
```

### Thrown By
- `TestLanes::claim()` (`src/TestLanes.php`)
- `CleanupCommand::handle()` (`src/Commands/CleanupCommand.php`)
```

--------------------------------

### Compute lock namespace with TestLanes::namespaceFor()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Computes the lock namespace for a base database name using crc32 masked into the positive int4 range. The mask is load-bearing because crc32 is unsigned 32-bit while Postgres advisory lock keys are signed int4. The namespace prevents lane collisions between different base databases on the same server.

```php
use Mozex\TestLanes\TestLanes;

$namespace = TestLanes::namespaceFor('my_app_test'); // always >= 0
```

--------------------------------

### AdvisoryLock Interface

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/advisory-lock.md

The AdvisoryLock interface defines the contract for custom lock drivers. It includes three methods: connect, tryAcquire, and release.

```APIDOC
## AdvisoryLock Interface

### Description
Defines the contract for advisory lock backends used by lane claiming. Implement this interface to support additional database drivers.

### Methods

#### connect
- **Signature**: `connect(array $config): PDO`
- **Description**: Opens a PDO handle that Laravel does not manage, so the lock outlives any reconnect or purge on the framework's own connections. `$config` is the resolved `database.connections.<name>` array (`array<string, mixed>`).
- **Parameters**:
  - `$config` (array<string, mixed>) - Required - The database connection configuration array.
- **Returns**: `PDO` - A PDO instance.

#### tryAcquire
- **Signature**: `tryAcquire(PDO $connection, int $namespace, int $lane): bool`
- **Description**: Takes a lane's lock without waiting. Returns `false` when another process already holds it.
- **Parameters**:
  - `$connection` (PDO) - Required - The PDO connection to use.
  - `$namespace` (int) - Required - The namespace for the lock.
  - `$lane` (int) - Required - The lane (pool slot, 1-based) to lock.
- **Returns**: `bool` - `true` if the lock was acquired, `false` otherwise.

#### release
- **Signature**: `release(PDO $connection, int $namespace, int $lane): void`
- **Description**: Releases a lane's lock taken on this connection.
- **Parameters**:
  - `$connection` (PDO) - Required - The PDO connection to use.
  - `$namespace` (int) - Required - The namespace for the lock.
  - `$lane` (int) - Required - The lane (pool slot, 1-based) to release.
- **Returns**: `void`
```

--------------------------------

### TestLanesException::unsupportedDriver

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/test-lanes-exception.md

Factory method for the exception thrown when the driver has no lock primitive.

```APIDOC
## `unsupportedDriver`

### Description
Creates a `TestLanesException` for when the PDO driver has no lock primitive configured. The message lists the supported drivers and suggests configuration options.

### Method
`TestLanesException::unsupportedDriver` (static factory)

### Parameters
- **`$driver`** (`string`) - Required - The PDO driver name with no lock primitive.
- **`$supported`** (`list<string>`) - Required - The keys of the resolved `test-lanes.locks` map, joined into the message.

### Returns
`self` - A new `TestLanesException` instance.

### Message
```
Test lanes have no lock primitive for the [{driver}] driver, so concurrent runs would share databases. Use one of [{supported}], map your own AdvisoryLock class under "locks" in config/test-lanes.php, or set TEST_LANES_ENABLED=false to switch lanes off.
```

### Thrown By
- `TestLanes::lock()` (`src/TestLanes.php`, line 143)
- `CleanupCommand::handle()`
```

--------------------------------

### TestLanes::release()

Source: https://github.com/mozex/laravel-test-lanes/blob/main/_autodocs/api-reference/testlanes.md

Releases the currently claimed test lane by clearing the static holder and lane state. This frees the advisory lock server-side when the holder connection is closed. Calling it without a prior claim is a no-op.

```APIDOC
## `release`

```php
public static function release(): void
```

**Parameters:** none

**Return type:** `void`

**What it does:** Gives the claimed lane back by clearing the static `$holder` and `$lane` state. Closing the holder connection is what actually frees the advisory lock server-side; the package's own test suite uses this method between tests. The token resolver stays registered, so the very next token resolution claims a lane again, possibly a different one. Calling it without a prior claim is a no-op.

### Example

```php
use Mozex\TestLanes\TestLanes;

TestLanes::release(); // next claim() may return a different lane
```
```
Tokens:
Raw