Laravel PAO

https://github.com/laravel/pao
Admin
Laravel PAO formats output from PHP tools like PHPUnit, Pest, PHPStan, Rector, and Laravel Artisan...
Tokens:46,095
Snippets:343
Trust Score:9.7
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install and run PHPUnit with laravel/pao

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Phpunit.md

Commands to install the package and run PHPUnit, with an example JSON output showing a passed run.

```bash
composer require laravel/pao --dev
vendor/bin/phpunit
# -> {"tool":"phpunit","result":"passed","tests":2,"passed":2,"duration_ms":8}
```

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

### Install and run Artisan with the provider

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Laravel-ServiceProvider.md

Install the package as a dev dependency and run an Artisan command inside an agent environment (or with PAO_FORCE=1) to see cleaned output.

```bash
composer require laravel/pao --dev
# inside the agent (or with PAO_FORCE=1):
php artisan about
# Environment ..              =>  " Environment ..\n Application Name .. Laravel\n ..." (cleaned)
```

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

### Pest Starter class implementation

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Pest.md

The Starter class extends BaseStarter and uses TestResultParsable. Its start() method registers filters, starts the timer, saves stdout, and handles parallel vs sequential execution.

```php
declare(strict_types=1);

namespace Laravel\Pao\Drivers\Pest;

use Laravel\Pao\Drivers\Concerns\ProfileCollector;
use Laravel\Pao\Drivers\Concerns\TestResultParsable;
use Laravel\Pao\Drivers\Starter as BaseStarter;

/**
 * @internal
 *
 * @codeCoverageIgnore
 */
final class Starter extends BaseStarter
{
    use TestResultParsable;

    public function name(): string
    {
        return 'pest';
    }

    public function start(): void
    {
        $this->registerNullFilter();
        $this->startTimer();
        $this->registerExecutionFinishedSubscriber();
        $this->saveStdout();
        $this->silenceStdout();

        /** @var list<string> $argv */
        $argv = $_SERVER['argv'] ?? [];

        if (in_array('--parallel', $argv, true)) {
            ProfileCollector::startTimerFromNanoseconds(hrtime(true));
            ProfileCollector::executionStarted();
        } else {
            $this->registerProfileSubscriber();
        }
    }
}
```

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

### Starter class implementation

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Paratest.md

The Starter class extends BaseStarter and uses TestResultParsable. Its start() method registers filters, starts the timer, silences stdout, and appends --runner with WrapperRunner::class to $_SERVER['argv'].

```php
declare(strict_types=1);

namespace Laravel\Pao\Drivers\Paratest;

use Laravel\Pao\Drivers\Concerns\TestResultParsable;
use Laravel\Pao\Drivers\Starter as BaseStarter;

/**
 * @internal
 *
 * @codeCoverageIgnore
 */
final class Starter extends BaseStarter
{
    use TestResultParsable;

    public function name(): string
    {
        return 'paratest';
    }

    public function start(): void
    {
        $this->registerNullFilter();
        $this->startTimer();
        $this->registerExecutionFinishedSubscriber();
        $this->silenceStdout();

        /** @var list<string> $serverArgv */
        $serverArgv = $_SERVER['argv'];

        $argv = $serverArgv;

        $argv[] = '--runner';
        $argv[] = WrapperRunner::class;

        $_SERVER['argv'] = $argv;
    }
}
```

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

### Execution::start(AgentResult $agent, array $argv): void

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Execution.md

Starts the execution process by resolving the driver from the binary name in argv[0] and invoking its start method. Throws ShouldNotHappenException if already running.

```APIDOC
## Execution::start(AgentResult $agent, array $argv): void

### Description
Starts the execution process by resolving the driver from the binary name in argv[0] and invoking its start method. Throws ShouldNotHappenException if already running.

### Method
Static method

### Signature
`public static function start(AgentResult $agent, array $argv): void`

### Parameters
- `agent` (AgentResult) - Required - Output of `AgentDetector::detect()` from the autoloader
- `argv` (array<int, string>) - Required - The full process argument vector; `argv[0]` is the invoked binary basename

### Returns
`void`. Side effects:
- resolves the driver by `basename($argv[0])` — exact `match` arms: `'paratest'`, `'pest'`, `'phpstan'`/`'phpstan.phar'`, `'phpunit'`, `'rector'`; anything else yields `null` and the call is a no-op (no instance is created);
- stores the singleton instance and calls the driver's `Starter::start()`.

### Throws
- `ShouldNotHappenException` - If `start()` is called while an `Execution` instance already exists (`self::running()` is `true`).
```

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

### PHPUnit Starter class implementation

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Phpunit.md

The `Starter` class extends the base starter and uses the `TestResultParsable` trait. The `start()` method registers null filter, starts timer, registers execution finished and profile subscribers, and appends `--no-output` to `$_SERVER['argv']` if not already present.

```php
declare(strict_types=1);

namespace Laravel\Pao\Drivers\Phpunit;

use Laravel\Pao\Drivers\Concerns\TestResultParsable;
use Laravel\Pao\Drivers\Starter as BaseStarter;

/**
 * @internal
 *
 * @codeCoverageIgnore
 */
final class Starter extends BaseStarter
{
    use TestResultParsable;

    public function name(): string
    {
        return 'phpunit';
    }

    public function start(): void
    {
        $this->registerNullFilter();
        $this->startTimer();
        $this->registerExecutionFinishedSubscriber();
        $this->registerProfileSubscriber();

        /** @var list<string> $serverArgv */
        $serverArgv = $_SERVER['argv'];

        $argv = $serverArgv;

        if (! in_array('--no-output', $argv, true)) {
            $argv[] = '--no-output';
        }

        $_SERVER['argv'] = $argv;
    }
}
```

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

### Execution::start() - Resolve driver and start execution

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Execution.md

Starts the Execution singleton by resolving a driver from the invoked binary basename. Throws ShouldNotHappenException if already running. The match arms cover 'paratest', 'pest', 'phpstan'/'phpstan.phar', 'phpunit', and 'rector'; any other binary results in a no-op. When a driver is resolved, stores the singleton and calls the driver's Starter::start().

```php
/**
 * @param  array<int, string>  $argv
 */
public static function start(AgentResult $agent, array $argv): void
{
    if (self::running()) {
        throw new ShouldNotHappenException;
    }

    $binary = basename($argv[0] ?? '');

    $starter = match ($binary) {
        'paratest' => new Drivers\Paratest\Starter,
        'pest' => new Drivers\Pest\Starter,
        'phpstan', 'phpstan.phar' => new Drivers\Phpstan\Starter,
        'phpunit' => new Drivers\Phpunit\Starter,
        'rector' => new Drivers\Rector\Starter,
        default => null,
    };

    if ($starter instanceof Driver) {
        self::$instance = new self(
            $agent,
            $starter,
        );

        $starter->start();
    }
}
```

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

### Install and run Rector commands

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Rector.md

Commands to install the laravel/pao package as a dev dependency and run Rector with a dry-run. The dry-run output shows a failed result with changed_files set to 2.

```bash
composer require laravel/pao --dev
vendor/bin/rector --dry-run
# -> {"tool":"rector","result":"failed","totals":{"changed_files":2,"errors":0}, ...}
```

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

### Install and run Pest with coverage

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Pest.md

Installs the laravel/pao package as a dev dependency and runs Pest with coverage. The output shows a JSON result with the tool name 'pest', a passed status, and test counts.

```bash
composer require laravel/pao --dev
vendor/bin/pest --coverage
# -> {"tool":"pest","result":"passed","tests":2,"passed":2,"duration_ms":80,"raw":["..."]}
```

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

### Install and run Paratest driver

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Paratest.md

Install the laravel/pao package as a dev dependency and invoke the paratest driver with the --parallel flag. The output shows a JSON result with tool name, pass status, test counts, and duration.

```bash
composer require laravel/pao --dev
vendor/bin/paratest --parallel
# -> {"tool":"paratest","result":"passed","tests":1002,"passed":1002,"duration_ms":2100}
```

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

### JSON output envelope example

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/index.md

Example of the JSON document emitted by PAO, preceded by the driver name. The document is encoded with JSON_UNESCAPED_SLASHES, JSON_INVALID_UTF8_SUBSTITUTE, and JSON_THROW_ON_ERROR, followed by PHP_EOL.

```json
{ "tool": "phpunit", "result": "passed", "tests": 1002, "passed": 1002, "duration_ms": 321 }
```

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

### Pest JSON result example

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Pest.md

Example JSON output from the Pest driver, showing the tool, result, test counts, duration, and raw output from coverage/profile reports.

```json
{
  "tool": "pest",
  "result": "passed",
  "tests": 1002,
  "passed": 1002,
  "duration_ms": 1520,
  "raw": [
    "Http/Controllers/Controller 100.0%",
    "Models/User 0.0%",
    "Total: 33.3 %"
  ]
}
```

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

### PHPUnit raw output before PAO

Source: https://github.com/laravel/pao/blob/1.x/README.md

Example of verbose PHPUnit output for 1,002 tests, showing progress dots and summary. Used to illustrate the original output format before PAO processing.

```text
PHPUnit 12.5.14 by Sebastian Bergmann and contributors.

.............................................................   61 / 1002 (  6%)
.............................................................  122 / 1002 ( 12%)
...
..........................                                    1002 / 1002 (100%)

Time: 00:00.321, Memory: 46.50 MB

OK (1002 tests, 1002 assertions)
```

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

### Phpstan Starter class implementation

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Phpstan.md

The `Starter` class extends the base starter and implements the `name()` and `start()` methods. It checks if transformation is needed, captures stderr, ensures `--error-format=json` and `--no-progress` are set, and silences stdout. The class is marked `@internal` and `@codeCoverageIgnore`.

```php
declare(strict_types=1);

namespace Laravel\Pao\Drivers\Phpstan;

use Laravel\Pao\Drivers\Starter as BaseStarter;
use Laravel\Pao\OutputCleaner;
use Laravel\Pao\UserFilters\CaptureFilter;
use Laravel\Pao\UserFilters\StderrCaptureFilter;

/**
 * @internal
 *
 * @codeCoverageIgnore
 */
final class Starter extends BaseStarter
{
    public function name(): string
    {
        return 'phpstan';
    }

    public function start(): void
    {
        /** @var array<int, string> $argv */
        $argv = $_SERVER['argv'];

        if (! $this->shouldTransform($argv)) {
            return;
        }

        $this->captureStderr();

        $argv = $this->ensureErrorFormatJson($argv);
        $argv = $this->ensureNoProgress($argv);
        $_SERVER['argv'] = $argv;

        $this->silenceStdout();
    }
}
```

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

### Install Laravel PAO via Composer

Source: https://github.com/laravel/pao/blob/1.x/README.md

Installs the Laravel PAO package as a dev dependency. Requires PHP 8.3+ and works with PHPUnit 12-13, Pest 4-5, Paratest, PHPStan, Rector, and Laravel 12+.

```bash
composer require laravel/pao --dev
```

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

### Execution::current() method

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Execution.md

Returns the singleton instance. Throws ShouldNotHappenException if no instance exists, which occurs when the process never went through start() or the binary was unmatched (match default => null).

```php
public static function current(): self
{
    return self::$instance ?? throw new ShouldNotHappenException;
}
```

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

### Example JSON result from TestResultParsable::parse()

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Paratest.md

Shows the JSON structure emitted by the trait parser when the wrapper fills Starter::$testResult. Includes tool, result, test counts, and failure details.

```json
{
  "tool": "paratest",
  "result": "failed",
  "tests": 1002,
  "passed": 999,
  "assertions": 1200,
  "duration_ms": 2100,
  "failed": 3,
  "failures": [
    {
      "test": "Tests\\Fixtures\\FailingTest::testThatFails",
      "file": "/app/tests/Fixtures/FailingTest.php",
      "line": 34,
      "message": "Failed asserting that 2 equals 1"
    }
  ]
}
```

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

### durationMs(): calculate elapsed time in milliseconds

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Concerns-ProfileCollector.md

Returns the elapsed wall time in milliseconds since the timer started, or 0 when no timer was started. This value is used as the duration_ms key in every test-driver result.

```php
public static function durationMs(): int
{
    if (! self::$startTime instanceof HRTime) {
        return 0;
    }

    $startNs = (self::$startTime->seconds() * 1_000_000_000) + self::$startTime->nanoseconds();

    return (int) round((hrtime(true) - $startNs) / 1_000_000);
}
```

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

### Basic cleanup of captured stdout

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/OutputCleaner.md

Basic cleanup example applied to a captured stdout fragment before it becomes the 'raw' array. Shows stripping of ANSI color codes and collapsing of multiple blank lines into one.

```php
<?php

use Laravel\Pao\OutputCleaner;

$raw = "\e[32m  Http/Controllers/Controller 100.0% \e[0m\n\n\nModels/User 0.0%\n";

echo OutputCleaner::clean($raw);
// " Http/Controllers/Controller 100.0% \nModels/User 0.0%\n"
```

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

### Rector Starter class definition

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Rector.md

The main class definition for the Rector driver. It extends the base Starter, forces JSON output format, and starts output buffering to capture Rector's output.

```php
declare(strict_types=1);

namespace Laravel\Pao\Drivers\Rector;

use Laravel\Pao\Drivers\Starter as BaseStarter;

/**
 * @internal
 *
 * @codeCoverageIgnore
 */
final class Starter extends BaseStarter
{
    private ?int $outputBufferLevel = null;

    public function name(): string
    {
        return 'rector';
    }

    public function start(): void
    {
        /** @var array<int, string> $argv */
        $argv = $_SERVER['argv'];

        if (! $this->shouldTransform($argv)) {
            return;
        }

        $argv = $this->ensureOutputFormatJson($argv);
        $_SERVER['argv'] = $argv;
        $GLOBALS['argv'] = $argv;

        $this->outputBufferLevel = ob_get_level();
        ob_start();
    }

```

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

### Clean run JSON result

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Rector.md

Example output when Rector runs without making any changes. The result is 'passed' with changed_files and errors both zero.

```json
{
  "tool": "rector",
  "result": "passed",
  "totals": { "changed_files": 0, "errors": 0 }
}
```

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

### Using Driver interface in Autoload.php (shutdown emitter and dispatch guard)

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Contracts-Driver.md

Shows the two usage sites of the Driver interface. The shutdown emitter calls parse() to get the result array, defaulting to empty when null; the dispatch guard inside Execution::start() filters starters by instanceof Driver, ensuring unmatched binaries are no-ops.

```php
// src/Autoload.php — shutdown emitter
$result = $execution->driver->parse() ?: [];
```

```php
// src/Autoload.php — dispatch guard inside Execution::start()
if ($starter instanceof Driver) {
    self::$instance = new self($agent, $starter);
    $starter->start();
}
```

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

### Changes applied JSON result

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Rector.md

Example output when Rector applies changes. Default behavior treats applied changes as success, so result is 'passed' with changed_files set to 1 and a file_diffs array containing the diff and applied rector.

```json
{
  "tool": "rector",
  "result": "passed",
  "totals": { "changed_files": 1, "errors": 0 },
  "file_diffs": [
    {
      "file": "app/Models/User.php",
      "diff": "--- Original\n+++ New\n@@ ...",
      "applied_rectors": ["Rector\\Php54\\Rector\\Array_\\LongArrayToShortArrayRector"]
    }
  ],
  "changed_files": ["app/Models/User.php"]
}
```

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

### Driver interface contract (src/Contracts/Driver.php)

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Contracts-Driver.md

Defines the polymorphic contract for all tool drivers. The start() method must be called synchronously during autoload before the tool binary executes, name() returns a stable short identifier used as the tool JSON key, and parse() runs at shutdown and must not rely on framework state.

```php
declare(strict_types=1);

namespace Laravel\Pao\Contracts;

/**
 * @internal
 */
interface Driver
{
    public function start(): void;

    public function name(): string;

    /**
     * @return array<string, mixed>|null
     */
    public function parse(): ?array;
}
```

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

### Driver interface definition

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/types.md

Defines the Driver contract with start(), name(), and parse() methods. The parse() method returns an array or null. The interface is marked @internal.

```php
/**
 * @internal
 */
interface Driver
{
    public function start(): void;

    public function name(): string;

    /**
     * @return array<string, mixed>|null
     */
    public function parse(): ?array;
}
```

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

### Execution private constructor

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Execution.md

Private constructor for `Execution`. Instances are created only inside `start()`. The `$agent` and `$driver` are promoted readonly public properties; `$stdout` and `$filter` are optional promoted public properties with default `null`.

```php
/**
 * @param  resource|null  $stdout
 * @param  resource|null  $filter
 */
private function __construct(
    public readonly AgentResult $agent,
    public readonly Driver $driver,
    public mixed $stdout = null,
    public mixed $filter = null,
) {
    //
}
```

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

### parse() method

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Concerns-TestResultParsable.md

Returns an array of test result data or null. Returns null when no TestResult is resolvable or when zero tests ran and execution never started.

```php
/**
 * @return array<string, mixed>|null
 */
public function parse(): ?array
{
    $testResult = $this->resolveTestResult();

    if (! $testResult instanceof TestResult) {
        return null;
    }

    if ($testResult->numberOfTestsRun() > 0 || ProfileCollector::hasExecutionStarted()) {
        return $this->parseTestResult($testResult);
    }

    return null;
}
```

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

### Extract subcommand from argv with commandName

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Starter.md

Returns the first argument that does not start with a hyphen, or null if all arguments after the binary are flags. Used by PHPStan and Rector drivers to identify the subcommand (e.g., analyse/analyze or process/p).

```php
/**
 * @param  array<int, string>  $argv
 */
protected function commandName(array $argv): ?string
{
    foreach (array_slice($argv, 1) as $arg) {
        if (! str_starts_with($arg, '-')) {
            return $arg;
        }
    }

    return null;
}
```

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

### Failed invocation JSON result

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Rector.md

Example output when Rector fails to run, such as due to an unknown file. Contains a fatal_errors array.

```json
{"tool":"rector","result":"failed","fatal_errors":["..."]}
```

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

### Example JSON result shape for an errored PHPUnit run

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Phpunit.md

Shows the JSON structure emitted when a test errors, including `errors` and `error_details` fields with test details.

```json
{
  "tool": "phpunit",
  "result": "failed",
  "tests": 2,
  "passed": 0,
  "assertions": 1,
  "duration_ms": 35,
  "errors": 1,
  "error_details": [
    {
      "test": "Tests\\Fixtures\\ErrorTest::testThatErrors",
      "file": "/app/tests/Fixtures/ErrorTest.php",
      "line": 7,
      "message": "Something went wrong"
    }
  ]
}
```

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

### Dry run that would change files JSON result

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Rector.md

Example output when a dry run detects files that would be changed. The result is 'failed' so the agent knows the tree needs edits.

```json
{
  "tool": "rector",
  "result": "failed",
  "totals": { "changed_files": 1, "errors": 0 }
}
```

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

### Execution::current() null instance guard

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/errors.md

Trigger condition for ShouldNotHappenException: thrown when Execution::current() is called while no instance has been created, meaning the process never ran Execution::start() or the invoked binary did not match any driver arm in start(), leaving self::$instance null.

```php
public static function current(): self
{
    return self::$instance ?? throw new ShouldNotHappenException;
}

```

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

### Laravel Artisan output before and after PAO

Source: https://github.com/laravel/pao/blob/1.x/README.md

PAO automatically cleans Artisan command output in agent environments, stripping ANSI colors, box-drawing characters, and excess whitespace. This example shows the before and after for the about command, reducing characters from 2,111 to 535.

```text
# Before (without PAO) — 2,111 characters
  Environment ................................................................
  Application Name ................................................... Laravel
  Laravel Version ..................................................... 13.3.0
  PHP Version .......................................................... 8.5.4
  Debug Mode ......................................................... ENABLED
```

```text
# After (with PAO) — 535 characters
 Environment ..
 Application Name .. Laravel
 Laravel Version .. 13.3.0
 PHP Version .. 8.5.4
 Debug Mode .. ENABLED
```

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

### ProfileCollector static class with state properties

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Concerns-ProfileCollector.md

Static class definition showing the private properties that hold process-global state: execution flag, high-resolution start time, prepared timestamp, and collected per-test duration entries. Imported symbols include TestMethod, HRTime, and Finished.

```php
declare(strict_types=1);

namespace Laravel\Pao\Drivers\Concerns;

use PHPUnit\Event\Code\TestMethod;
use PHPUnit\Event\Telemetry\HRTime;
use PHPUnit\Event\Test\Finished;

/**
 * @internal
 *
 * @codeCoverageIgnore
 */
final class ProfileCollector
{
    private static bool $executionStarted = false;

    private static ?HRTime $startTime = null;

    private static float $preparedAt = 0.0;

    /** @var list<array{test: string, file: string, duration_ms: int}> */
    private static array $entries = [];
```

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

### Failing analysis JSON output with truncation

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Phpstan.md

Shows the JSON object for a failed analysis with 50 errors, truncated to two example error details. Includes a hint to pass -v for all errors and an instructions field.

```json
{
  "tool": "phpstan",
  "result": "failed",
  "errors": 50,
  "error_details": { "/app/Http/Controllers/Controller.php": [
    { "line": 9, "message": "Method Controller::index() should return int but returns string.", "identifier": "return.type" },
    { "line": 14, "message": "Call to an undefined method Controller::doesNotExist().", "identifier": "method.notFound" }
  ]},
  "truncated": true,
  "hint": "Pass -v to see all errors.",
  "instructions": "Each error has an associated identifier..."
}
```

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

### Example JSON result shape for a failed PHPUnit run

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Phpunit.md

Shows the JSON structure emitted by the `TestResultParsable::parse()` method at shutdown for a run with a failing test. Includes `tool`, `result`, `tests`, `passed`, `assertions`, `duration_ms`, `failed`, and `failures` array with test details.

```json
{
  "tool": "phpunit",
  "result": "failed",
  "tests": 2,
  "passed": 1,
  "assertions": 3,
  "duration_ms": 42,
  "failed": 1,
  "failures": [
    {
      "test": "Tests\\Fixtures\\FailingTest::testThatFails",
      "file": "/app/tests/Fixtures/FailingTest.php",
      "line": 12,
      "message": "Failed asserting that 1 equals 2"
    }
  ]
}
```

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

### Execution::restoreStdout() method

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Execution.md

Removes the agent_output_capture stream filter from STDOUT (installed by Starter::silenceStdout()), restoring normal stdout behavior, and nulls the stored filter resource. Safe to call repeatedly. Called by the shutdown emitter before re-writing cleaned captured output. No parameters; returns void.

```php
public function restoreStdout(): void
{
    if (is_resource($this->filter)) {
        stream_filter_remove($this->filter);

        $this->filter = null;
    }
}
```

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

### ExampleStarter subclass extending Starter

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Starter.md

Shows a hypothetical subclass that consumes the Starter plumbing, using methods like captureStderr(), addOption(), and silenceStdout(). The exact pattern is used by Phpstan\Starter::start().

```php
final class ExampleStarter extends Starter
{
    public function name(): string
    {
        return 'example';
    }

    public function start(): void
    {
        $argv = $_SERVER['argv'];

        if (in_array('--json-only', $argv, true)) {
            return;
        }

        $this->captureStderr();
        $_SERVER['argv'] = $this->addOption($argv, '--json-only');
        $this->silenceStdout();
    }
}
```

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

### ServiceProvider boot() method with guards and event listener

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Laravel-ServiceProvider.md

The boot() method checks PAO_DISABLE, console context, unit tests, and agent detection before binding OutputStyle and listening for CommandStarting to disable decoration.

```php
declare(strict_types=1);

namespace Laravel\Pao\Laravel;

use Illuminate\Console\Events\CommandStarting;
use Illuminate\Console\OutputStyle;
use Illuminate\Contracts\Events\Dispatcher;
use Illuminate\Support\ServiceProvider as LaravelServiceProvider;
use Laravel\AgentDetector\AgentDetector;

/**
 * @internal
 *
 * @codeCoverageIgnore
 */
final class ServiceProvider extends LaravelServiceProvider
{
    public function boot(): void
    {
        if (filter_var($_SERVER['PAO_DISABLE'] ?? false, FILTER_VALIDATE_BOOLEAN)) {
            return;
        }

        if (! $this->app->runningInConsole()) {
            return;
        }

        if ($this->app->runningUnitTests()) {
            return;
        }

        if (! AgentDetector::detect()->isAgent && ! filter_var($_SERVER['PAO_FORCE'] ?? false, FILTER_VALIDATE_BOOLEAN)) {
            return;
        }

        $this->app->bind(OutputStyle::class, PaoOutputStyle::class);

        /** @var Dispatcher $events */
        $events = $this->app->make(Dispatcher::class);
        $events->listen(CommandStarting::class, function (CommandStarting $event): void {
            $event->output->setDecorated(false);
        });
    }
}
```

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

### Execution::running() method

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Execution.md

Returns true when a singleton instance has been created, indicating a supported tool binary was dispatched by the autoloader. No parameters, no exceptions.

```php
public static function running(): bool
{
    return self::$instance instanceof Execution;
}
```

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

### Execution::running()

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Execution.md

Returns true when a singleton instance has been created, indicating a supported tool binary was dispatched by the autoloader. Takes no parameters and returns a boolean.

```APIDOC
## Execution::running()

### Description
Returns `true` when a singleton instance has been created (i.e. a supported tool binary was dispatched by the autoloader). No parameters, no exceptions.

### Method
`public static function running(): bool`

### Parameters
None.

### Return Value
- **bool** - `true` if a singleton instance exists, `false` otherwise.

### Example
```php
$isRunning = Execution::running();
```
```

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

### Starter abstract class definition

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Starter.md

Defines the abstract base class for all tool drivers, implementing the Driver interface and importing necessary classes for stream filtering.

```php
declare(strict_types=1);

namespace Laravel\Pao\Drivers;

use Laravel\Pao\Contracts\Driver;
use Laravel\Pao\Execution;
use Laravel\Pao\UserFilters\CaptureFilter;
use Laravel\Pao\UserFilters\NullFilter;
use Laravel\Pao\UserFilters\StderrCaptureFilter;

/**
 * @internal
 *
 * @codeCoverageIgnore
 */
abstract class Starter implements Driver
{
```

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

### Autoload.php header with namespace and imports

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Autoload.md

The opening of the procedural script, declaring strict types, ignoring code coverage, and importing the AgentDetector class.

```php
declare(strict_types=1);

/** @codeCoverageIgnoreStart */

namespace Laravel\Pao;

use Laravel\AgentDetector\AgentDetector;
```

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

### PaoOutputStyle::__construct(InputInterface $input, OutputInterface $output)

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Laravel-PaoOutputStyle.md

Constructor that accepts console input and output. It disables decoration on the output before calling the parent constructor.

```APIDOC
## PaoOutputStyle::__construct(InputInterface $input, OutputInterface $output)

### Description
Initializes the PaoOutputStyle with the given input and output. The output's decoration is disabled before the parent constructor is invoked.

### Method
Constructor

### Signature
`public function __construct(InputInterface $input, OutputInterface $output)`

### Parameters
- **$input** (InputInterface) - Required - Console input (passed to parent)
- **$output** (OutputInterface) - Required - Console output; `setDecorated(false)` is called on it before the parent constructor is invoked.

### Returns
Nothing.
```

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

### Execution::start() double initialization guard

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/errors.md

Trigger condition for ShouldNotHappenException: thrown when Execution::start() is called while an Execution instance already exists, e.g., two autoload hooks racing or a second call from any code path. Normally cannot fire because the autoloader runs once per process; it is a defensive invariant.

```php
public static function start(AgentResult $agent, array $argv): void
{
    if (self::running()) {
        throw new ShouldNotHappenException;
    }
    ...
```

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

### Module graph of PAO

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/index.md

ASCII diagram showing the class hierarchy and relationships between PAO components, including the Autoload hook, Execution, drivers, filters, and supporting classes.

```text
src/Autoload.php                     (global hook, procedural)
└── Execution::start()               src/Execution.php
    └── Driver (interface)           src/Contracts/Driver.php
        └── Starter (abstract)       src/Drivers/Starter.php  — stream-filter plumbing
            ├── Phpunit\Starter      src/Drivers/Phpunit/Starter.php    use TestResultParsable
            ├── Pest\Starter         src/Drivers/Pest/Starter.php       use TestResultParsable
            │   └── Pest\Plugin      src/Drivers/Pest/Plugin.php        (Pest argument hook)
            ├── Paratest\Starter     src/Drivers/Paratest/Starter.php   use TestResultParsable
            │   └── Paratest\WrapperRunner  src/Drivers/Paratest/WrapperRunner.php
            ├── Phpstan\Starter      src/Drivers/Phpstan/Starter.php    (own parse())
            └── Rector\Starter       src/Drivers/Rector/Starter.php     (own parse())

Laravel\Pao\OutputCleaner           src/OutputCleaner.php  — regex cleaning, used by
                                    Autoload, Phpstan\Starter, PaoOutputStyle
Laravel\Pao\UserFilters              src/UserFilters/ — php_user_filter stream filters
    ├── NullFilter                   (drops STDOUT bytes)
    ├── CaptureFilter                (captures + passes through STDOUT bytes)
    └── StderrCaptureFilter          (captures + passes through STDERR bytes)

Laravel\Pao\Drivers\Concerns
    ├── TestResultParsable (trait)   src/Drivers/Concerns/TestResultParsable.php
    └── ProfileCollector             src/Drivers/Concerns/ProfileCollector.php

Laravel\Pao\Laravel
    ├── ServiceProvider              src/Laravel/ServiceProvider.php
    └── PaoOutputStyle               src/Laravel/PaoOutputStyle.php

Laravel\Pao\Exceptions
    └── ShouldNotHappenException     src/Exceptions/ShouldNotHappenException.php
```

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

### PaoOutputStyle class implementation

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Laravel-PaoOutputStyle.md

Defines the PaoOutputStyle class that extends Illuminate\Console\OutputStyle. The constructor disables decorated output, and the write and writeln methods clean messages before passing them to the parent, unless the OUTPUT_RAW flag is set.

```php
declare(strict_types=1);

namespace Laravel\Pao\Laravel;

use Illuminate\Console\OutputStyle;
use Laravel\Pao\OutputCleaner;
use Symfony\Component\Console\Formatter\OutputFormatter;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

/**
 * @internal
 *
 * @codeCoverageIgnore
 */
final class PaoOutputStyle extends OutputStyle
{
    private static ?OutputFormatter $formatter = null;

    public function __construct(InputInterface $input, OutputInterface $output)
    {
        $output->setDecorated(false);

        parent::__construct($input, $output);
    }

    /**
     * @param  string|iterable<string>  $messages
     */
    #[\\Override]
    public function write(string|iterable $messages, bool $newline = false, int $options = 0): void
    {
        parent::write($this->clean($messages, ($options & self::OUTPUT_RAW) === 0), $newline, $options);
    }

    /**
     * @param  string|iterable<string>  $messages
     */
    #[
\Override]
    public function writeln(string|iterable $messages, int $type = self::OUTPUT_NORMAL): void
    {
        parent::writeln($this->clean($messages, ($type & self::OUTPUT_RAW) === 0), $type);
    }
}
```

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

### Recovery path using Execution::running() and current()

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Execution.md

Shows the recovery path used by src/Autoload.php, the only production caller. It checks that the process ID matches and that Execution::running() is true, then retrieves the current Execution instance, parses the driver output, and restores stdout.

```php
register_shutdown_function(function () use ($pid): void {
    if (getmypid() !== $pid || ! Execution::running()) {
        return;
    }

    $execution = Execution::current();
    $result = $execution->driver->parse() ?: [];
    $execution->restoreStdout();
});
```

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

### Double-start guard with ShouldNotHappenException

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Execution.md

Demonstrates the double-start guard: calling Execution::start() twice throws a ShouldNotHappenException instead of corrupting state. The catch block shows the exception message and issue URL.

```php
<?php

use Laravel\Pao\Execution;
use Laravel\Pao\Exceptions\ShouldNotHappenException;

try {
    Execution::start($agent, $argv);
    Execution::start($agent, $argv); // throws ShouldNotHappenException
} catch (ShouldNotHappenException $e) {
    // "This should not have happened. Please report this issue at
    //  https://github.com/laravel/pao/issues/new"
}
```

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

### Compose TestResultParsable trait in a driver class

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Concerns-TestResultParsable.md

Shows how to use the TestResultParsable trait in a driver class. The trait is consumed by declaration only, and drivers inherit the parse() method. The composing class's start() calls protected helpers, and the autoloader calls the trait's parse() at shutdown.

```php
final class Starter extends BaseStarter
{
    use TestResultParsable;

    public function name(): string
    {
        return 'phpunit';
    }
}
```

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

### Composer autoload and extra configuration

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/configuration.md

Composer configuration for the package, enabling autoloading, Laravel service provider auto-discovery, Pest plugin registration, and runtime dependencies.

```json
"autoload": {
    "files": ["src/Autoload.php"],
    "psr-4": { "Laravel\\Pao\\": "src/" }
},
"extra": {
    "laravel": {
        "providers": ["Laravel\\Pao\\Laravel\\ServiceProvider"]
    },
    "pest": {
        "plugins": ["Laravel\\Pao\\Drivers\\Pest\\Plugin"]
    }
},
"require": { "php": "^8.3", "laravel/agent-detector": "^2.0.2" }
```

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

### Shutdown emitter JSON write

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Autoload.md

Prepends the tool name to the result and writes the JSON document to STDOUT with specific flags.

```php
$result = ['tool' => $execution->driver->name()] + $result;

fwrite(STDOUT, json_encode($result, JSON_UNESCAPED_SLASHES | JSON_INVALID_UTF8_SUBSTITUTE | JSON_THROW_ON_ERROR).PHP_EOL);
```

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

### Plugin class implementing HandlesArguments

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Pest.md

Defines the `Plugin` class that implements `Pest\Contracts\Plugins\HandlesArguments`. The `handleArguments` method checks if PAO is running via `Execution::running()`; if not, it returns arguments unchanged. Otherwise, it appends `--no-output` and `--no-progress` flags if not already present, ensuring they are not forced on human developers.

```php
declare(strict_types=1);

namespace Laravel\Pao\Drivers\Pest;

use Laravel\Pao\Execution;
use Pest\Contracts\Plugins\HandlesArguments;

/**
 * @internal
 *
 * @codeCoverageIgnore
 */
final class Plugin implements HandlesArguments
{
    public function __construct()
    {
        //
    }

    /**
     * @param  array<int, string>  $arguments
     * @return array<int, string>
     */
    public function handleArguments(array $arguments): array
    {
        if (! Execution::running()) {
            return $arguments;
        }

        if (! in_array('--no-output', $arguments, true)) {
            $arguments[] = '--no-output';
        }

        if (! in_array('--no-progress', $arguments, true)) {
            $arguments[] = '--no-progress';
        }

        return $arguments;
    }
}
```

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

### Environment mutation for output handling

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Autoload.md

Unsets `COLLISION_PRINTER` and sets `PEST_PARALLEL_NO_OUTPUT` to '1' to control output behavior.

```php
unset($_SERVER['COLLISION_PRINTER']);
$_SERVER['PEST_PARALLEL_NO_OUTPUT'] = '1';
```

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

### parse() method implementation

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Rector.md

Parses buffered Rector output. Returns null for empty output, raw output on decode failure, failed result with fatal errors, or a valid report with a computed 'result' key. The result is 'failed' if errors > 0 or if changed files > 0 and dry-run is active.

```php
/**
 * @return array<string, mixed>|null
 */
public function parse(): ?array
{
    $captured = trim($this->bufferedOutput());

    if ($captured === '') {
        return null;
    }

    $start = strpos($captured, '{');

    if ($start !== false && $start > 0) {
        $captured = substr($captured, $start);
    }

    /** @var array<string, mixed>|null $data */
    $data = json_decode($captured, associative: true);

    if (! is_array($data) || ! is_array($data['totals'] ?? null)) {
        $fatalErrors = is_array($data) ? $this->fatalErrors($data) : [];

        if ($fatalErrors !== []) {
            return [
                'result' => 'failed',
                'fatal_errors' => $fatalErrors,
            ];
        }

        return [
            'raw' => [$captured],
        ];
    }

    $changedFiles = $data['totals']['changed_files'] ?? 0;
    $errors = $data['totals']['errors'] ?? 0;

    if (! is_int($changedFiles) || ! is_int($errors)) {
        return [
            'raw' => [$captured],
        ];
    }

    return [
        'result' => $errors > 0 || ($changedFiles > 0 && $this->isDryRun()) ? 'failed' : 'passed',
    ] + $data;
}
```

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

### Normalize Artisan-style decorated output

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/OutputCleaner.md

Normalizing Artisan-style decorated output. Strips ANSI color codes and collapses the run of dots into '..'.

```php
<?php

use Laravel\Pao\OutputCleaner;

$output = "\e[32m  Application Name \e[0m..................... \e[33mLaravel\e[0m";

echo OutputCleaner::clean($output);
// " Application Name .. Laravel"
```

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

### OutputCleaner class with clean() method

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/OutputCleaner.md

The complete OutputCleaner class with its static clean() method. It applies a fixed pipeline of eight preg_replace steps to strip OSC/ANSI sequences, control characters, the Unicode replacement character, box-drawing and decorative symbols, collapse dot runs, collapse whitespace, and collapse blank lines. No exceptions are thrown; the casts guarantee a string return.

```php
declare(strict_types=1);

namespace Laravel\Pao;

/**
 * @internal
 *
 * @codeCoverageIgnore
 */
final class OutputCleaner
{
    public static function clean(string $output): string
    {
        $output = (string) preg_replace('/\e\][^\x07\e]*(?:\x07|\e\\\\)/', '', $output);
        $output = (string) preg_replace('/\e\[[0-?]*[ -\/]*[@-~]/', '', $output);
        $output = (string) preg_replace('/[\x00-\x09\x0B\x0C\x0E-\x1F\x7F]/', '', $output);
        $output = (string) preg_replace('/\x{FFFD}/u', '', $output);
        $output = (string) preg_replace('/[─━│┌┐└┘├┤┬┴┼▓░▒═║╔╗╚╝╠╣╦╩╬➜▶►⚠✖✔●◆■▪→←↑↓▕⨯✕]+/u', '', $output);
        $output = (string) preg_replace('/\.{3,}/', '..', $output);
        $output = (string) preg_replace('/[ \t]+/', ' ', $output);

        return (string) preg_replace('/\n\s*\n/', "\n", $output);
    }
}
```

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

### parse() method with docblock and implementation

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Drivers-Phpstan.md

Public method that captures and resets STDOUT/STDERR buffers, falls back to fallback() when STDOUT is empty, and otherwise parses JSON. Returns ?array<string, mixed> or null.

```php
/**
 * @return array<string, mixed>|null
 */
public function parse(): ?array
{
    $captured = trim(CaptureFilter::output());

    CaptureFilter::reset();

    $stderr = trim(StderrCaptureFilter::output());

    StderrCaptureFilter::reset();

    if ($captured === '') {
        return $this->fallback($stderr);
    }
    ...
```

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

### Agent check with PAO_FORCE override

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Autoload.md

Detects the agent and returns early unless an agent is detected or `PAO_FORCE` is truthy.

```php
$agent = AgentDetector::detect();

if (! $agent->isAgent && ! filter_var($_SERVER['PAO_FORCE'] ?? false, FILTER_VALIDATE_BOOLEAN)) {
    return;
}
```

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

### registerExecutionFinishedSubscriber method implementation

Source: https://github.com/laravel/pao/blob/1.x/_autodocs/api-reference/Concerns-TestResultParsable.md

Registers an anonymous ExecutionFinishedSubscriber that sets the executionFinished flag to true when the execution finishes. The subscriber is created with a closure that is invoked in the notify method. Any exceptions during registration are caught and ignored.

```php
protected function registerExecutionFinishedSubscriber(): void
{
    try {
        $markFinished = function (): void {
            $this->executionFinished = true;
        };

        EventFacade::instance()->registerSubscriber(
            new readonly class($markFinished) implements ExecutionFinishedSubscriber
            {
                public function __construct(private \Closure $markFinished) {}

                public function notify(ExecutionFinished $event): void
                {
                    ($this->markFinished)();
                }
            },
        );
    } catch (\Throwable) {
        //
    }
}
```
Tokens:
Raw