Event Bundle Laravel Package

Getting Started

This package gives Laravel applications a way to discover Doctrine entity classes by scanning the project directory rather than relying on hand-maintained entity lists. The 0.1.13 release adds a scan method that finds entities even when the application uses multiple entity managers.

Minimal setup:

1. Install the package with Composer and let Laravel auto-discover the service provider.
2. Publish any package config if the package exposes one (php artisan vendor:publish --tag=...). This is the first place to look for scan paths, namespace filters, and entity-manager mappings.
3. Open the package service provider and the scanner class itself. The public scan method is the primary entry point introduced in 0.1.13.

First use case: call scan from a service provider, an Artisan command, or a test to obtain the list of entity classes under your application namespace. With multiple entity managers configured, the scanner should identify entities across the relevant directories so you can register or validate them per manager without duplicating path configuration.

A minimal invocation in a service provider might look like:

$entities = $scanner->scan();

Use the result to feed entity registration, schema tooling, or migration generation. Start by scanning only your application's entity directories; expand scope after confirming the output is correct.

Implementation Patterns

Scan once, cache the result. Directory scanning is not free. Run scan during deployment, in a cached config, or in a scheduled command and persist the class list. In day-to-day development, call it dynamically; in production, hydrate from cache.

Group by entity manager. The headline feature is support for multiple entity managers. Use the scan output alongside each manager's configured entity paths to ensure entities land with the correct manager. A typical pattern is to scan all candidate directories once, then partition the class list by namespace or configured path per manager.

Register entities in a service provider. A common integration is to run the scan at boot or in a dedicated registrar class and pass the discovered classes to the Doctrine configuration for each manager. Keep this in a single registrar to avoid boot-order surprises.

Expose an Artisan command. Wrap the scanner in php artisan entities:scan returning a table of discovered classes and inferred managers. This is the fastest way to debug configuration and a useful CI check that every expected entity is discoverable.

Use it in tests. Assert that scan() returns expected entity classes for each manager. This guards against a class being moved or renamed while doctrine configuration still points at the old location.

Pair with schema and migration tooling. The scan result is a reliable input for schema validation, diff generation, or migration commands that need the full entity set across managers.

Filter aggressively. If the scanner accepts paths, namespaces, or exclusion patterns, pass them explicitly. Restricting the scan to app/Entities and similar directories keeps results deterministic and fast.

Gotchas and Tips

• Scan scope grows silently. Scanning the project root can include vendor, storage, test fixtures, and generated code. Always constrain paths or exclusions; otherwise you will pick up unrelated classes or slow the scan dramatically.
• Multiple managers means ambiguous ownership. The scanner finds entities, but it does not necessarily decide which manager owns each one. If your managers use overlapping namespaces, partition explicitly or the same class may be registered twice.
• Autoloading matters. The scanner reflects on classes. New or moved files must be autoloadable (composer dump-autoload) before they appear. A stale autoloader is a common cause of "missing entity" reports after refactoring.
• Cache invalidation. If you cache scan results, clear them when deploying new code or changing entity paths. A cached list that references a deleted class will fail at hydration time.
• Entity detection heuristics. The package likely identifies entities by attributes/annotations, inheritance, or namespace conventions. Confirm how it decides; a plain class in an entity directory may or may not be included. Check the scanner's filter methods for the extension point.
• Boot-order and config caching. Running scan during application boot in production can be expensive. Prefer a command or deploy step, and make sure config:cache does not freeze a stale path list.
• Debug by dumping raw output. When an expected entity is absent, dump the scan result before it is filtered or grouped. This separates discovery problems from registration problems.
• Extension points. Look for overridable path filters, namespace resolvers, or entity-manager mapping hooks before forking behavior. These are the intended seams for custom scan rules.
• Version pinning. The scan method is new in 0.1.13. Pin at least this version if you depend on it, and review the scanner's public API before upgrading, since the package is still pre-1.0.