Laravel Debug Container Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bernardosecades/laravel-debug-container
   

   Register the provider in bootstrap/app.php under APP_ENV === 'development':

   $app->register(\BernardoSecades\Laravel\DebugContainer\DebugContainerServiceProvider::class);
   

2. First Use Case: Run the debug command to inspect registered services:

   php artisan debug:container
   

   This outputs a structured list of all services in the container, including bindings, aliases, and singleton status.

Where to Look First

• Command Output: Focus on the debug:container output to identify:
  • Service names and their concrete classes.
  • Singleton vs. non-singleton bindings.
  • Aliases and their target bindings.
• Service Provider Registration: Check bootstrap/app.php to confirm the provider is conditionally loaded (e.g., only in development).

Implementation Patterns

Usage Patterns

1. Debugging Dependency Injection:

   • Use debug:container to verify if a service is registered before troubleshooting App\Services\MyService::class resolution failures.
   • Compare expected vs. actual bindings to catch typos or misconfigurations in bind()/singleton() calls.

2. Workflows:

   • Pre-Deployment Check: Run debug:container in staging to ensure no unexpected services are registered (e.g., debug-only bindings).
   • Onboarding: Teach junior devs to use this command to explore the container structure during pair programming.

3. Integration Tips:

   • Custom Artisan Commands: Extend the command to filter services by prefix (e.g., debug:container --prefix="App\Services").
   • CI/CD: Add php artisan debug:container to a custom script in your pipeline to fail builds if critical services are missing.

Example Workflow

# Debug a missing service
php artisan debug:container | grep -i "AuthService"

# Verify singleton status
php artisan debug:container --singletons-only

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Avoid running debug:container in production (provider is env-gated, but double-check).
   • The command iterates over all bindings, which could be slow in large apps with thousands of services.

2. Output Parsing:

   • The output is raw; pipe to grep/awk for specific data (e.g., php artisan debug:container | grep "App\\").
   • No JSON/structured output by default (consider wrapping the command in a script for programmatic use).

3. Dynamic Bindings:

   • Services bound dynamically (e.g., via afterResolving()) may not appear in the output. Run the command after the app boots fully.

Debugging Tips

• Missing Services:

  • If a service isn’t listed, check if it’s bound in a service provider’s boot() method (bindings in register() are container-wide, but boot() bindings are context-specific).
  • Verify the provider is registered in config/app.php under providers.

• Singleton Confusion:

  • Use --singletons-only to confirm if a service is a singleton. Non-singletons may resolve differently across requests.

Extension Points

1. Customize Output: Override the command class (\BernardoSecades\Laravel\DebugContainer\Commands\DebugContainerCommand) to:

   • Add columns (e.g., "Bound In Provider").
   • Filter by tags or custom metadata.

2. Add Metadata: Extend the container’s getBindings() logic to include custom tags:

   // In a service provider
   $this->app->bind('MyService', function () {
       return new MyService();
   })->withMetadata(['tag' => 'auth']);
   

   Then modify the command to display metadata.

3. Integration with Laravel IDE Helper: Use the output to generate/update ide-helper models for better autocompletion.

Config Quirks

• No Configuration File: The package relies solely on the service provider and command. All behavior is hardcoded.
• Environment Check: Ensure APP_ENV=development is set when testing locally (the provider won’t register otherwise).