Repdoc Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require s9e/repdoc --dev
   

   • Add to composer.json under require-dev to avoid production bloat.

2. First Use Case: Create a Markdown file (e.g., docs/api_example.md) with a PHP snippet and expected output:

   ```php
   $user = new App\Models\User(['name' => 'John Doe']);
   $user->save();
   echo $user->id;
   

   1
   

   Run REPdoc via:

   vendor/bin/repdoc docs/api_example.md
   

   • Expected Output: Validates if the PHP code produces the exact output in the second block.
   • Error Handling: Fails with a diff if outputs mismatch (e.g., Expected "1", got "2").

3. Where to Look First:

   • CLI Command: vendor/bin/repdoc --help for flags (e.g., --output to save results).
   • Markdown Syntax: Ensure files follow the ````php ... ```plain` pattern.
   • Laravel Integration: Check vendor/s9e/repdoc/src/Repdoc.php for extensibility points (e.g., custom evaluators).

Implementation Patterns

Workflows

1. Local Development:

   • Use REPdoc to validate doc examples before merging PRs:

     php artisan repdoc docs/*.md  # Process all doc files
     

   • Integrate with Laravel’s post-update-cmd in composer.json:

     "scripts": {
       "post-update-cmd": [
         "@php artisan repdoc docs/api.md"
       ]
     }
     

2. CI/CD Validation:

   • Add a step to fail builds if doc examples break:

     # .github/workflows/docs.yml
     - name: Validate Documentation Examples
       run: vendor/bin/repdoc docs/api.md || exit 1
     

3. Web Integration:

   • Static Output: Generate HTML from REPdoc and serve via Laravel routes:

     Route::get('/docs/api', function () {
         return file_get_contents(public_path('docs/evaluated.html'));
     });
     

   • Dynamic Evaluation: Use a Laravel Artisan command to cache evaluated docs:

     php artisan repdoc:generate --cache=3600  # Cache for 1 hour
     

Laravel-Specific Patterns

1. Artisan Command Wrapper: Create a custom command to extend REPdoc (e.g., add Laravel-specific evaluators):

   php artisan make:command RepdocDocs
   

   // app/Console/Commands/RepdocDocs.php
   use S9e\Repdoc\Repdoc;
   protected $signature = 'repdoc:docs {path : Path to Markdown file}';
   public function handle() {
       $repdoc = new Repdoc();
       $result = $repdoc->processFile($this->argument('path'));
       $this->info($result);
   }
   

2. Sandboxed Evaluation: Restrict REPdoc to a subset of PHP functions/classes (e.g., Laravel’s App\Models):

   $repdoc = new Repdoc();
   $repdoc->setAllowedFunctions(['App\Models\User', 'App\Models\Post']);
   $repdoc->processFile('docs/model_example.md');
   

3. Markdown Processing Pipeline: Chain REPdoc with Laravel’s Markdown parsers (e.g., spatie/laravel-markdown):

   use Spatie\Markdown\MarkdownRenderer;
   $renderer = new MarkdownRenderer();
   $html = $renderer->toHtml(file_get_contents('docs/example.md'));
   // Inject REPdoc output dynamically
   

Gotchas and Tips

Pitfalls

1. Security Risks:

   • Arbitrary Code Execution: REPdoc evaluates untrusted PHP snippets. Mitigate by:
     • Restricting to trusted doc sources (e.g., Git-approved files).
     • Using ini_set('disable_functions', 'exec,system,...') to block dangerous functions.
     • Sandboxing: Run REPdoc in a Docker container or use box/spout for isolation.

2. Output Mismatches:

   • Non-Deterministic Code: Snippets using time(), rand(), or DB queries will fail. Use fixed seeds or avoid such code in docs.
   • Whitespace Sensitivity: REPdoc compares output exactly, including newlines. Normalize outputs with trim() or preg_replace.

3. Dependency Conflicts:

   • REPdoc may clash with Laravel’s autoloader if docs use use App\Models\.... Prepend paths:

     $repdoc->setIncludePaths([app_path()]);
     

4. Performance:

   • Large Doc Sets: Evaluating hundreds of files in CI will slow builds. Cache results or parallelize with parallel-lint.

Debugging Tips

1. Verbose Mode:

   vendor/bin/repdoc --verbose docs/example.md
   

   • Shows raw eval output and diffs for mismatches.

2. Dry Runs: Use --dry-run to validate syntax without execution:

   vendor/bin/repdoc --dry-run docs/example.md
   

3. Custom Evaluators: Override REPdoc’s default evaluator for Laravel-specific logic:

   $repdoc->setEvaluator(function ($code) {
       // Prepend Laravel autoloader
       require app_path('bootstrap/autoload.php');
       return eval($code);
   });
   

Extension Points

1. Custom Markup: Extend REPdoc to support Laravel Blade snippets or SQL queries:

   // Example: Add a `sql` block type
   $repdoc->addBlockType('sql', function ($code) {
       return DB::selectOne($code)->toJson();
   });
   

2. Output Formatting: Modify output to include Laravel-specific metadata (e.g., timestamps, user context):

   $repdoc->setOutputFormatter(function ($output) {
       return "<div class='laravel-repdoc'>$output</div>";
   });
   

3. CI Integration: Fail builds on specific doc files or output patterns:

   - name: Check API Docs
     run: |
       vendor/bin/repdoc docs/api.md || \
       (echo "API doc validation failed" && exit 1)
   

Laravel-Specific Quirks

1. Environment Variables: REPdoc runs in a clean PHP environment by default. Load Laravel’s .env:

   $repdoc->setEnvironmentVariables([
       'APP_ENV' => 'testing',
       'DB_CONNECTION' => 'sqlite',
   ]);
   

2. Service Providers: Docs using Laravel services (e.g., Auth::user()) require bootstrapping:

   $repdoc->setBootstrap(function () {
       $app = require __DIR__.'/../bootstrap/app.php';
       $app->make(Kernel::class)->bootstrap();
   });
   

3. Testing: Mock REPdoc in PHPUnit tests:

   $repdoc = Mockery::mock(S9e\Repdoc\Repdoc::class);
   $repdoc->shouldReceive('processFile')->andReturn('valid output');