Pao Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/pao --dev
   

   • Works with PHP 8.3+, Laravel 12+, and tools like PHPUnit, Pest, Paratest, PHPStan, and Rector.

2. First Use Case:

   • Run a test suite or Artisan command inside an AI agent (e.g., Claude Code, Cursor, or Gemini CLI).
   • PAO automatically detects the agent and outputs structured JSON instead of verbose CLI text.
   • Example:

     php artisan test
     

     Output (in AI agent):

     {
       "tool": "phpunit",
       "result": "passed",
       "tests": 100,
       "passed": 100,
       "duration_ms": 500
     }
     

3. Where to Look First:

   • No configuration needed—PAO hooks into tools via Composer autoloading.
   • Check the README for supported tools and edge cases (e.g., Pest parallel mode).
   • For Laravel, verify Artisan output is cleaned by running:

     php artisan about
     

     (Compare output with/without PAO in an AI agent.)

Implementation Patterns

Core Workflows

1. AI Agent Integration:

   • Detects AI agents via environment variables (e.g., PAO_AGENT=1 or agent-specific headers).
   • Automatically switches to JSON output for tools like:
     • PHPUnit/Pest/Paratest: Test results, durations, and failure details.
     • PHPStan: Error lists with file/line context.
     • Rector: Diffs and applied rules.
     • Artisan: Cleaned command output (no ANSI colors/whitespace).

2. Human-Friendly Fallback:

   • No changes to CLI output when run manually (e.g., php artisan test in terminal).
   • Preserves colors, formatting, and decorations for developers.

3. Laravel-Specific Patterns:

   • Artisan Command Cleanup:
     • Strips ANSI codes, box-drawing characters, and excess whitespace.
     • Example: php artisan migrate:status becomes 75% smaller in token count.
   • Service Provider Auto-Discovery:
     • No manual registration needed in config/app.php.

4. Tool-Specific Patterns:

   • PHPUnit/Pest:
     • Captures raw output (e.g., coverage stats) in a raw array.
     • Example:

       {
         "tool": "pest",
         "raw": ["Coverage: 85%", "Tests: 100/100"]
       }
       

   • PHPStan:
     • Groups errors by file and caps at 30 errors for brevity.
     • Includes fixing instructions (e.g., return.type identifiers).
   • Rector:
     • Uses Rector’s native JSON output for diffs and applied rules.

5. Edge Case Handling:

   • Runtime Exits: Ensures test results are not lost during crashes (fixed in v1.1.1).
   • Boolean Env Vars: Properly parses .env values (e.g., APP_DEBUG=true → bool(true)).

Integration Tips

1. For CI/CD Pipelines:

   • Set PAO_AGENT=1 in your CI environment to force JSON output for AI processing.
   • Example (GitHub Actions):

     env:
       PAO_AGENT: 1
     

   • Use PAO’s output to trigger downstream actions (e.g., Slack alerts for test failures).

2. For Local Development:

   • Disable PAO temporarily by unsetting the agent flag:

     unset PAO_AGENT
     

   • Useful when debugging AI agent-specific issues.

3. Customizing Output:

   • Extend PAO’s TestResult class (used internally) to add custom fields to JSON.
   • Override the PaoServiceProvider in Laravel to modify Artisan output rules.

4. Debugging AI Parsing:

   • Log raw JSON output to verify AI agents can parse it:

     // In a test listener or command
     file_put_contents('pao_debug.json', json_encode($paoOutput, JSON_PRETTY_PRINT));
     

5. Performance:

   • PAO adds minimal overhead (~5–10ms per command) due to agent detection.
   • Disable for non-AI workflows to avoid unnecessary processing.

Gotchas and Tips

Pitfalls

1. Agent Detection False Positives:

   • PAO may incorrectly detect an AI agent if your environment has unusual headers/vars.
   • Fix: Explicitly set PAO_AGENT=1 or unset it if needed:

     export PAO_AGENT=0  # Disable PAO
     

2. Incomplete Output on Runtime Exits:

   • Before v1.1.1: Test results might be lost if a command crashes (e.g., php artisan test fails mid-execution).
   • Fix: Update to v1.1.1+ to ensure results are captured before exit.

3. Boolean Env Var Parsing:

   • Before v1.1.1: .env values like APP_DEBUG=true might not parse as booleans.
   • Fix: Update to v1.1.1 for correct boolean handling.

4. Pest Parallel Mode Quirks:

   • Gotcha: Pest with --parallel may leak raw dots (.) in output.
   • Fix: Update to v1.0.6+ or manually filter output:

     $output = str_replace('.', '', $output);
     

5. Artisan Command-Specific Issues:

   • Some commands (e.g., make:model) may not be optimized by PAO.
   • Workaround: Manually clean output or exclude from PAO’s Artisan processor.

6. PHPStan Error Limits:

   • PAO caps PHPStan errors at 30 per file for brevity.
   • Tip: Use the raw field to access full output if needed.

Debugging Tips

1. Verify PAO Activation:

   • Check if PAO is active by running:

     php artisan pao:debug
     

   • Output should confirm agent detection and tool hooks.

2. Inspect JSON Output:

   • Redirect output to a file to debug:

     php artisan test > pao_output.json
     

   • Validate JSON structure with:

     jq . pao_output.json
     

3. Disable PAO for Testing:

   • Temporarily disable PAO in config/app.php:

     'providers' => [
         // Comment out or remove:
         // \Laravel\Pao\PaoServiceProvider::class,
     ],
     

4. Handle AI Agent-Specific Errors:

   • If an AI agent fails to parse PAO’s JSON:
     • Check for malformed data (e.g., unescaped quotes).
     • Use json_last_error() to validate output:

       $json = json_encode($paoOutput);
       if (json_last_error() !== JSON_ERROR_NONE) {
           throw new \RuntimeException("Invalid JSON: " . json_last_error_msg());
       }
       

5. Custom Tool Support:

   • To add support for a new tool (e.g., Psalm):
     • Extend Laravel\Pao\Contracts\Tool and register it in PaoServiceProvider.
     • Example:

       // app/Providers/PaoServiceProvider.php
       public function registerTools()
       {
           $this->app->singleton(\Laravel\Pao\Contracts\Tool::class, function () {
               return new class implements \Laravel\Pao\Contracts\Tool {
                   public function handle($output) { /* Custom logic */ }
               };
           });
       }
       

Extension Points

1. Modify JSON Schema:

   • Override the TestResult class to add custom fields:

     namespace App\Pao;
     
     use Laravel\Pao\TestResult as BaseTestResult;
     
     class TestResult extends BaseTestResult
     {
         public function __construct()
         {
             parent::__construct();
             $this->customField = 'value';
         }
     }
     

2. Artisan Output Rules:

   • Customize which Artisan commands are cleaned:

     // config/pao.php (if added)
     'artisan' => [
         'commands' => [
             'migrate:*',  // Clean all migrate commands
             '!make:*',    // Exclude make commands
         ],
     ],
     

3. Agent Detection Logic:

   • Extend `Laravel\