Tag Debug Laravel Package

Getting Started

Minimal Setup in Laravel

To start using egulias/tag-debug in Laravel, install it via Composer:

composer require egulias/tags-debug

First Use Case: Inspecting Tagged Services

Leverage the package to debug tagged services in Laravel's container (which is built on Symfony's DIC). Add this to a service provider's boot() method or a custom Artisan command:

use Egulias\TagDebug\Tag\TagFetcher;
use Egulias\TagDebug\Tag\FilterList;
use Illuminate\Support\ServiceProvider;

class DebugServiceProvider extends ServiceProvider
{
    public function boot()
    {
        $container = $this->app->getContainer();
        $fetcher = new TagFetcher($container);

        $filters = new FilterList();
        $tags = $fetcher->fetch($filters);

        // Dump all tagged services (e.g., in Tinker or a debug route)
        dd($tags);
    }
}

Quick Debugging via Artisan

Create a custom Artisan command for ad-hoc debugging:

php artisan make:command DebugTags

Then implement:

use Egulias\TagDebug\Tag\TagFetcher;
use Egulias\TagDebug\Tag\FilterList;

class DebugTagsCommand extends Command
{
    protected $signature = 'debug:tags {--tag= : Filter by tag name}';
    protected $description = 'Debug tagged services in the container';

    public function handle()
    {
        $container = app();
        $fetcher = new TagFetcher($container);

        $filters = new FilterList();
        if ($tag = $this->option('tag')) {
            $filters->addFilter(new \Egulias\TagDebug\Tag\Filter\Tag($tag));
        }

        $tags = $fetcher->fetch($filters);
        $this->line(print_r($tags, true));
    }
}

Run it with:

php artisan debug:tags --tag=mailer

Implementation Patterns

Integrating with Laravel's Service Providers

Use the package to validate or inspect tagged services during bootstrapping:

public function register()
{
    $this->app->tag(
        [\App\Services\Mailer::class, \App\Services\Logger::class],
        'app.services'
    );
}

public function boot()
{
    $container = $this->app->getContainer();
    $fetcher = new TagFetcher($container);

    $filters = new FilterList();
    $filters->addFilter(new \Egulias\TagDebug\Tag\Filter\Tag('app.services'));

    $tags = $fetcher->fetch($filters);

    // Log or validate tagged services
    foreach ($tags['app.services'] as $service => $data) {
        $this->log("Tagged service: {$service}");
    }
}

Dynamic Filtering for Conditional Logic

Combine filters to narrow down results dynamically:

$filters = new FilterList();
$filters->addFilter(new \Egulias\TagDebug\Tag\Filter\Tag('mailer'));
$filters->addFilter(new \Egulias\TagDebug\Tag\Filter\Name('*MailerService')); // Wildcard support

$tags = $fetcher->fetch($filters);

Extending with Custom Filters

Implement a custom filter for Laravel-specific logic (e.g., filter by binding type):

use Egulias\TagDebug\Tag\Filter;

class BindingTypeFilter implements Filter
{
    private $bindingType;

    public function __construct($bindingType)
    {
        $this->bindingType = $bindingType;
    }

    public function matches($tag)
    {
        $definition = $tag->getDefinition();
        return $definition->getClass() === $this->bindingType;
    }
}

// Usage:
$filters->addFilter(new BindingTypeFilter(\App\Services\Mailer::class));

Debugging During Runtime

Attach the debugger to a route or middleware for runtime inspection:

Route::get('/debug/tags', function () {
    $container = app();
    $fetcher = new TagFetcher($container);

    $filters = new FilterList();
    $tags = $fetcher->fetch($filters);

    return response()->json($tags);
})->middleware('auth');

Gotchas and Tips

Laravel Container Quirks

• Container Access: Laravel's container is a proxy for Symfony's DIC. Use $this->app->getContainer() or app() to access the underlying ContainerBuilder.
• Tagging Syntax: Laravel uses app()->tag() or $this->app->tag() in providers. Ensure tags are registered before debugging.

Debugging Pitfalls

1. Outdated Data:

   • The package reflects the container's state at the time of fetching. Changes to the container (e.g., dynamic service binding) won't be reflected unless the container is rebuilt.
   • Fix: Re-fetch tags after modifying the container.

2. Circular References:

   • Complex service definitions with circular references may cause issues. The package is lightweight but relies on Symfony's DIC internals.
   • Fix: Simplify definitions or use a subset of services for debugging.

3. Filter Logic:

   • Filters use AND logic by default. Misconfigured filters may return empty results.
   • Tip: Test filters incrementally. Start with a single filter (e.g., Tag) before combining.

Performance Considerations

• Avoid in Production: The package is for debugging. Disable or remove it in production environments.
• Lazy Loading: Fetch tags only when needed (e.g., in development routes or Artisan commands).

Extension Points

1. Custom Output:

   • Override the default output format by extending the TagFetcher or processing the $tags array:

     $formatted = [];
     foreach ($tags as $tagName => $services) {
         $formatted[$tagName] = array_keys($services);
     }
     

2. Integration with Laravel Debugbar:

   • Add a custom collector to display tagged services in the Laravel Debugbar:

     use Barryvdh\Debugbar\DataCollector\DataCollector;
     
     class TagDebugCollector extends DataCollector
     {
         public function collect()
         {
             $fetcher = new TagFetcher(app());
             $this->data['tags'] = $fetcher->fetch(new FilterList());
         }
     }
     

3. Tag Validation:

   • Use the package to validate that required tags exist during application boot:

     $requiredTags = ['mailer', 'logger'];
     foreach ($requiredTags as $tag) {
         $filters = new FilterList();
         $filters->addFilter(new \Egulias\TagDebug\Tag\Filter\Tag($tag));
         if (empty($fetcher->fetch($filters)[$tag])) {
             throw new \RuntimeException("Missing required tag: {$tag}");
         }
     }
     

Configuration Tips

• Composer Autoloading: Ensure the package is autoloaded in composer.json:

  "autoload": {
      "psr-4": {
          "Egulias\\TagDebug\\": "vendor/egulias/tags-debug/src/"
      }
  }
  

• IDE Support: Add the package's namespace to your IDE's autoload paths for better code completion.

Legacy Note

• The package is Symfony 2-focused and lacks Laravel-specific features. Use it as a low-level tool rather than a high-level abstraction. For Laravel-specific debugging, consider laravel-debugbar or custom solutions.