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, PHPStan, and Rector.

2. First Use Case: Run your existing test suite or tool (e.g., phpunit, pest, phpstan) in an AI agent environment (e.g., Claude Code, Cursor, Gemini CLI). PAO automatically detects the agent and converts verbose output to structured JSON.

   Example:

   phpunit
   

   Output (in AI agent):

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

3. Laravel-Specific: For Artisan commands (e.g., php artisan migrate:status), PAO strips ANSI colors and excess whitespace by default in AI environments. No additional configuration is needed.

Where to Look First

• Documentation: README.md for tool-specific examples (PHPUnit, Pest, PHPStan, etc.).
• Release Notes: Check v1.1.1 for fixes related to runtime exits and boolean env values.
• Integration: PAO hooks into tools via Composer autoloading. For Laravel, a service provider is auto-discovered for Artisan commands.

First Practical Use

1. Test a CI Pipeline: Run your test suite in a CI environment where an AI agent might process logs (e.g., GitHub Actions with Claude Code integration). Verify the output is now structured JSON, reducing log noise and token usage.

2. Debug Artisan Commands: Use php artisan about or php artisan db:show in an AI environment. Observe the cleaned output (e.g., 75% fewer tokens) while retaining all critical information.

Implementation Patterns

Usage Patterns

1. Zero-Configuration Integration:

   • Install via Composer. PAO auto-detects AI agents (e.g., Claude Code, Cursor) and activates automatically.
   • No need to modify phpunit.xml, pest.php, or other config files.

2. Tool-Specific Workflows:

   • PHPUnit/Pest/Paratest: Replace verbose test output with structured JSON, including test counts, durations, and failure details.

     {
       "tool": "pest",
       "result": "failed",
       "tests": 10,
       "failed": 2,
       "failures": [
         {
           "file": "tests/Unit/UserTest.php",
           "line": 20,
           "message": "Failed assertion: User::find(1) should return User."
         }
       ]
     }
     

   • PHPStan: Convert static analysis errors into actionable JSON with file paths and line numbers.

     {
       "tool": "phpstan",
       "result": "failed",
       "errors": 2,
       "error_details": {
         "app/Http/Controllers/UserController.php": [
           {
             "line": 15,
             "message": "Method UserController::store() should return void but returns string."
           }
         ]
       }
     }
     

   • Rector: Use Rector’s native JSON output format, enhanced with file diffs and applied rectors.

     {
       "tool": "rector",
       "result": "success",
       "totals": {
         "changed_files": 1,
         "errors": 0
       },
       "file_diffs": [
         {
           "file": "app/Models/User.php",
           "diff": "--- Original\n+++ New\n@@ -1 +1 @@\n-public $name;\n+public string $name;"
         }
       ]
     }
     

   • Laravel Artisan: Clean command output by stripping ANSI colors, box-drawing characters, and whitespace. Example:

     php artisan about
     

     Output (before PAO):

     Environment ................................................................
     Application Name ................................................... Laravel
     

     Output (after PAO):

     Environment ..
     Application Name .. Laravel
     

3. Conditional Activation: PAO only activates in AI agent environments. Human-readable output remains unchanged in local terminals or CI pipelines without AI integration.

Workflows

1. AI-Assisted Development:

   • Use PAO in tools like Cursor or Gemini CLI to parse test results, PHPStan errors, or Rector diffs programmatically.
   • Example: Automate test triage by filtering result: "failed" from PAO’s JSON output.

2. CI/CD Optimization:

   • Reduce log noise in CI by enabling PAO for tools like PHPUnit or Pest. Structured JSON is easier to parse and archive.
   • Example GitHub Actions step:

     - name: Run tests with PAO
       run: phpunit
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Triggers PAO in AI agents
     

3. Local Development:

   • Disable PAO temporarily for local debugging by excluding AI agents (e.g., run tests in a non-agent terminal).
   • Re-enable for AI-assisted pair programming sessions.

Integration Tips

1. Laravel-Specific:

   • Ensure your Laravel app uses PHP 8.3+ and Laravel 12+ for full Artisan support.
   • Test Artisan commands like migrate:status, db:show, and about in AI environments to verify cleaned output.

2. Custom Tools:

   • Extend PAO for unsupported tools by implementing the Pao\Contracts\Tool interface. See Pao’s source for details.

3. Environment Variables:

   • PAO respects PAO_ENABLED (if set to false, it disables agent detection). Useful for CI pipelines where AI agents are not involved.

     PAO_ENABLED=false phpunit  # Disables PAO
     

4. Debugging:

   • Add PAO_DEBUG=true to log agent detection and output transformations.

     PAO_DEBUG=true pest
     

Gotchas and Tips

Pitfalls

1. Agent Detection:

   • PAO relies on AI agent-specific headers or environment variables. If an agent isn’t detected, output remains unchanged.
   • Fix: Ensure your AI tool (e.g., Cursor, Gemini CLI) sends the correct X-Agent header or sets PAO_AGENT=true.

2. Boolean Environment Variables:

   • Older versions of PAO had issues parsing boolean env values (e.g., PAO_ENABLED=true vs. PAO_ENABLED=1).
   • Fix: Use PAO_ENABLED=true or PAO_ENABLED=false explicitly. Updated in v1.1.1.

3. Runtime Exits:

   • Tools like Pest or PHPUnit might exit abruptly (e.g., due to fatal errors), causing truncated output.
   • Fix: Updated in v1.1.1. Ensure you’re on the latest version.

4. Artisan Command Output:

   • Some Artisan commands (e.g., tinker) may not be fully supported or may include unsanitized output.
   • Tip: Test critical commands in your AI environment to verify output quality.

5. Parallel Testing:

   • Pest’s --parallel mode or Paratest may leak raw output (e.g., dots or progress bars) in some versions.
   • Fix: Updated in v1.1.0. Ensure you’re using Pest 4-5 or Paratest’s latest version.

Debugging Tips

1. Verify Agent Detection:

   • Run with PAO_DEBUG=true to see if PAO detects your AI agent:

     PAO_DEBUG=true pest
     

   • Expected output includes:

     [PAO] Detected agent: cursor/1.0
     

2. Check Output Format:

   • Ensure JSON output includes the tool field (added in v1.0.2). Example:

     {
       "tool": "phpunit",  // Critical for parsing
       "result": "passed",
       ...
     }
     

3. Handle Missing Fields:

   • If failures or error_details are missing in PHPUnit/PHPStan output, ensure your tool version is supported (e.g., PHPUnit 12-13, PHPStan 1.0