Autoconfigure Bundle Laravel Package

Getting Started

Install the package via Composer (composer require vendor/package), then register its service provider (if not auto‑discovered). Publish any configuration file with php artisan vendor:publish and review the services scan paths.

The first place to look is the attribute classes: #[Service], #[Tag], and the new #[MethodCall]. A minimal use case:

#[Service]
#[Tag('reports')]
#[MethodCall('setLogger', args: [Logger::class])]
class SalesReport { ... }

Then inject all tagged services using Laravel’s tagged binding or the package’s own injection attribute:

public function __construct(#[Tagged('reports')] iterable $reports) { ... }

After defining your first service, run php artisan optimize:clear to ensure annotations are re‑scanned. The package fits naturally into Laravel’s container – start by converting one existing singleton or bind to an annotated service to see the registration and tagging in action.

Implementation Patterns

• Tag‑based collections – Use #[Tag('name')] to group related services (e.g., payment.gateway, formatter). Inject them as iterable or resolve via app()->tagged('name'). This is ideal for strategy patterns, event listeners, or plugin systems.
• Post‑instantiation configuration – The new #[MethodCall] annotation lets you call setters or configuration methods on the service right after it is built. Example: #[MethodCall('setConfig', args: ['key' => 'value'])]. Method calls execute in the order they are declared, so you can chain dependencies.
• Workflow: scan‑and‑register – Place annotated services in a dedicated directory (e.g., app/Services). The package scans that path and registers each class automatically. Combine with interfaces: tag implementations of an interface, then inject the tagged collection.
• Integration with Laravel features – Tags are resolved through the container, so you can use them in service providers, middleware, or controllers. For example, register a tagged collection as a singleton and inject it wherever needed.
• Testing – Because services are registered via annotations, use the package’s test helpers (if provided) or manually refresh the container in tests. Mock tagged services by binding a fake implementation with the same tag.

Gotchas and Tips

• Cache clearing – Annotations are scanned at boot; after adding or changing a #[Tag] or #[MethodCall], clear the container/annotation cache (php artisan optimize:clear). In production, ensure the scan cache is warmed during deployment.
• Order of method calls – #[MethodCall] annotations execute in the order they appear on the class. If a method depends on another, declare them sequentially. You cannot reference the result of a previous call directly – use a single method that orchestrates the logic instead.
• Tags are not inherited – If you tag a parent class, child classes do not automatically receive the tag. Apply #[Tag] explicitly to each concrete class you want in the collection.
• Debugging tags – Use php artisan tinker and app()->tagged('your-tag') to inspect resolved instances. If a service is missing, check that its class is within the configured scan paths and that the #[Service] attribute is present.
• Config quirks – The package may require you to enable annotation scanning in config/services.php (or similar). Ensure the service provider is registered before other providers that depend on tagged services.
• Extension points – The service definition builder may be extendable via custom attributes or by listening to a ServiceDefinition event. Check the package’s source for ServiceDefinition or Attribute classes to add your own logic. For method calls, the args array accepts both positional and named arguments – use named arguments for clarity when a method has many optional parameters.