Pao Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel/pao --dev
   

   • Works with PHP 8.3+, Laravel 12+, PHPUnit 12-13, Pest 4-5, Paratest, and PHPStan.

2. First Use Case:

   • Run any supported tool (e.g., phpunit, pest, phpstan, or artisan) in an AI agent environment (e.g., Claude Code, Cursor, or Gemini CLI).
   • PAO automatically detects the agent and converts output to structured JSON.

3. Where to Look First:

   • Output Format: Check the Before & After section in the README for examples of JSON output.
   • Laravel Artisan: PAO cleans Artisan output (e.g., php artisan about) by stripping ANSI colors and decorations.
   • Debugging: If PAO isn’t activating, verify:
     • The AI agent is supported (see Gotchas).
     • You’re running the tool in an agent environment (not a local terminal).

Implementation Patterns

Usage Patterns

1. Testing Workflows:

   • PHPUnit/Pest/Paratest:

     php artisan test  # Outputs structured JSON in AI agents, raw output locally
     vendor/bin/pest   # Same behavior
     

   • PHPStan:

     vendor/bin/phpstan analyse app --level=max
     

     Output includes errors, error_details (with file paths and line numbers), and a capped list of 30 errors.

2. Laravel Artisan:

   • PAO cleans all Artisan commands in agent environments:

     php artisan migrate:status  # Compact JSON output in AI agents
     php artisan db:show         # Stripped of ANSI colors and decorations
     

   • Supported commands: about, db:show, migrate:status, etc. (see release/v0.1.3).

3. Parallel Testing:

   • Pest/Paratest parallel runs (--parallel) are supported, but raw output (e.g., dots for progress) is captured in a raw array in JSON.

4. Pest Plugins:

   • Output from plugins like --coverage or --profile is included in the raw array of the JSON response.

Integration Tips

1. Local Development:

   • PAO only activates in AI agents. Local terminal output remains unchanged (colors, formatting preserved).
   • Test locally first, then verify AI agent output in your CI/CD or agent environment.

2. Custom Tools:

   • PAO hooks into tools via Composer autoloading. For custom PHP tools, ensure they use PHPUnit/Pest/Paratest/PHPStan under the hood.
   • Extend PAO by publishing a pao.php config file (see Gotchas).

3. CI/CD Pipelines:

   • Use PAO in CI to generate structured test reports for AI-assisted debugging:

     # Example GitHub Actions step
     - run: php artisan test
       env:
         AI_AGENT: "true"  # Optional: Force PAO activation (if agent detection fails)
     

4. Laravel Service Provider:

   • PAO auto-discovers the PAOServiceProvider in Laravel. No manual registration needed.

Gotchas and Tips

Pitfalls

1. Agent Detection:

   • PAO relies on laravel/agent-detector to identify AI agents.
   • Issue: If your agent isn’t listed (e.g., a custom CLI tool), PAO won’t activate.
     • Fix: Extend the detector by publishing the pao.php config:

       // config/pao.php
       return [
           'agents' => [
               'CustomAgent/1.0',  // Add your agent's user-agent string
           ],
       ];
       

   • Debug: Check if PAO is active by running:

     php artisan pao:debug
     

2. Exit Codes:

   • PAO preserves exit codes (e.g., 1 for test failures). Ensure your AI agent handles non-zero exits gracefully.

3. Parallel Testing Quirks:

   • Pest/Paratest parallel runs may leak raw dots (...) into the raw array. This is expected and stripped of ANSI codes.

4. Artisan Command Limitations:

   • PAO only cleans supported Artisan commands. Unsupported commands output raw text.
   • Workaround: Extend PAO by adding custom command handlers in app/Providers/PAOServiceProvider.php.

5. PHPStan Error Capping:

   • PHPStan output caps at 30 errors per file. Use error_details to debug specific issues.

Debugging

1. Verify PAO Activation:

   • Run a test in an AI agent and check the output. If it’s not JSON, PAO isn’t active.
   • Debug Command:

     php artisan pao:debug
     

     Outputs the detected agent and PAO status.

2. Raw Output Leaks:

   • If raw arrays contain unwanted ANSI codes or decorations, update PAO’s cleaning logic in:

     vendor/laravel/pao/src/Tools/ArtisanTool.php
     

     (Note: This is a vendor file; consider forking PAO for custom changes.)

3. Missing Tool Support:

   • PAO doesn’t support your tool? Check if it’s built on PHPUnit/Pest/Paratest/PHPStan.
   • Workaround: Wrap your tool’s output in a custom JSON formatter and pipe it to the agent.

Tips

1. Token Optimization:

   • PAO reduces tokens by 99.8% for tests and 75% for Artisan commands. Use this to:
     • Feed test results directly into AI-powered dashboards.
     • Generate concise summaries for CI/CD reports.

2. Structured Data:

   • Leverage the JSON output for programmatic analysis:

     $output = json_decode(file_get_contents('php://stdout'), true);
     if ($output['result'] === 'failed') {
         // Trigger alerts or rollback logic
     }
     

3. Local Testing:

   • Simulate AI agent output locally by setting the HTTP_USER_AGENT environment variable:

     HTTP_USER_AGENT="Claude Code/1.0" php artisan test
     

4. Extending PAO:

   • Add support for new tools by creating a custom Tool class (e.g., CustomTool) and registering it in PAOServiceProvider.
   • Example:

     $this->app->bind('pao.tools.custom', function () {
         return new CustomTool();
     });
     

5. Performance:

   • PAO adds minimal overhead (~5-10ms per test suite). Benchmark in CI to ensure no regression.