Ranger Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/ranger
   

   Add to config/app.php under providers:

   Laravel\Ranger\RangerServiceProvider::class,
   

2. First Run:

   use Laravel\Ranger\Ranger;
   
   $ranger = app(Ranger::class);
   $ranger->run();
   

   This triggers introspection of all registered components (routes, models, etc.).

3. First Use Case: Log discovered routes to a file:

   $ranger->onRoute(function (Components\Route $route) {
       file_put_contents(
           storage_path('logs/routes.log'),
           $route->uri . "\n",
           FILE_APPEND
       );
   });
   

Key Entry Points

• Ranger::run(): Kickstart introspection.
• Ranger::on*(): Register callbacks for specific components (e.g., onRoute, onModel).
• DTOs: Access structured data via Components\* classes (e.g., Components\Route, Components\Model).

Implementation Patterns

Core Workflows

1. Component Discovery:

   $ranger->onModel(function (Components\Model $model) {
       // Process model metadata (e.g., fillables, casts, relationships)
       tap($model->fillable, function ($fillables) {
           // Example: Validate fillable fields against a schema
       });
   });
   

2. Conditional Processing: Use DTO properties to filter components:

   $ranger->onRoute(function (Components\Route $route) {
       if (str_starts_with($route->uri, 'admin/')) {
           // Handle admin routes
       }
   });
   

3. Aggregation: Collect data into a structured format:

   $routes = collect([]);
   $ranger->onRoute(fn (Components\Route $route) => $routes->push($route));
   return $routes->toArray();
   

4. Integration with Laravel Events: Trigger custom events after introspection:

   $ranger->onModel(function (Components\Model $model) {
       event(new ModelDiscovered($model->class));
   });
   

Advanced Patterns

• Dynamic Callbacks: Register callbacks conditionally (e.g., only in local environment):

  if (app()->environment('local')) {
      $ranger->onRoute(fn (Components\Route $route) => Log::debug($route->uri));
  }
  

• DTO Extension: Extend DTOs for custom metadata:

  $ranger->onRoute(function (Components\Route $route) {
      $route->setMetadata(['owner' => 'auth.user']);
  });
  

• Batch Processing: Use Ranger::batch() for large codebases:

  $ranger->batch(100)->run(); // Process 100 components at a time
  

Gotchas and Tips

Pitfalls

1. Performance:

   • Introspection can be slow for large apps. Use batch() or run during off-peak hours.
   • Avoid running in production unless necessary (e.g., debugging).

2. Beta API:

   • DTO structures may change before v1.0.0. Pin versions in composer.json:

     "laravel/ranger": "^0.5.0"
     

3. Circular Dependencies:

   • Complex relationships (e.g., polymorphic models) may cause infinite loops. Use ->ignore():

     $ranger->ignore('App\Models\CircularModel');
     

4. Environment Variables:

   • .env values are parsed at runtime. For static analysis, mock or pre-process them.

Debugging

• Verbose Output: Enable debug mode to log skipped components:

  $ranger->debug(true);
  

• Component Filtering: Isolate issues by narrowing callbacks:

  $ranger->onRoute(fn (Components\Route $route) =>
      $route->uri === '/problematic' ? dd($route) : null
  );
  

Tips

1. Custom DTOs: Extend Laravel\Ranger\Components\Component for project-specific data:

   class CustomModel extends Components\Model {
       public function isCritical() { ... }
   }
   

2. Artisan Command: Wrap Ranger in a command for CLI access:

   use Laravel\Ranger\Ranger;
   
   class IntrospectCommand extends Command {
       protected $signature = 'ranger:introspect';
       public function handle() {
           app(Ranger::class)->run();
       }
   }
   

3. Testing: Mock Ranger in tests:

   $ranger = Mockery::mock(Ranger::class);
   $ranger->shouldReceive('onRoute')->once();
   

4. Exclude Directories: Skip irrelevant paths (e.g., tests/):

   $ranger->ignoreDirectory(base_path('tests'));
   

5. Post-Introspection: Use Ranger::finished() to run cleanup or analysis:

   $ranger->finished(function () {
       // Generate a report after all components are processed
   });