Event Bundle Laravel Package

Technical Evaluation

Summary of the change: Release 0.1.13 adds a scan capability that walks the project directory to discover entity classes, and — critically — resolves entities correctly when a project configures multiple entity managers, rather than relying on a single implicit mapping.

Architecture fit The package clearly occupies the class/entity discovery layer of a Laravel + Doctrine stack: it produces the list of entity classes that a Doctrine ORM integration (e.g. laravel-doctrine/orm) registers against entity managers. As a TPM this is a plumbing dependency — high leverage, low visible surface. It sits on the startup path (entity metadata must be known before the first query), so its correctness is a boot-time concern, not a feature-toggle concern. The multi-entity-manager support is the architecturally meaningful part: it signals the package is aimed at projects using per-connection or per-bounded-context EMs (multiple databases, or a read/write or module-separated model), which is exactly where hand-maintained entity path lists historically rot fastest.

Integration feasibility Low effort on paper: Composer install, optionally publish config, replace a manual entity-path list with a scan call. The real work is verification, not integration — confirming the scanner's notion of "an entity" matches the project's (annotations vs. attributes, inherited base classes, mapped superclasses, embeddables, non-entity repositories). Since there is no prior assessment and no data supplied for this review, treat integration effort as unvalidated: the only evidence available is a one-line changelog.

Technical risk

• Pre-1.0 API instability. A 0.1.x line means the maintainer reserves the right to change signatures in a patch or minor. Pin exact versions (0.1.13, not ^0.1) and treat upgrades as reviewed changes.
• Filesystem scanning is a boot/runtime cost. Directory walking plus reflection/parsing is materially more expensive than a static list. The dominant unknown is caching: whether results are cached (file/APCu/compiled class map) and whether the cache invalidates on new files. In dev this is fine; in production on cold start or with a large app//src/ tree it can become a measurable boot penalty.
• False positives and false negatives. Scanning is heuristic. Accidentally picking up abstract classes, DTOs, or test fixtures, or missing entities outside the scan roots (packages, vendor path repositories, modules excluded for speed), are both plausible. Multi-EM support reduces misrouting risk but does not remove it.
• Autoload coupling. The scanner almost certainly depends on Composer's autoloader (classmap-authoritative / optimize-autoloader in production can change what is discoverable). This is the single most likely production-only failure mode.

Key questions to put to the maintainer / spike

1. Does scan cache its result, and where? What invalidates it — file mtime, a manual cache:clear, a dedicated command?
2. What are the scan roots and exclusion defaults, and are they configurable?
3. How is an entity assigned to a specific entity manager when multiple EMs exist — by namespace prefix, by path, by attribute, or by explicit config map?
4. How does it behave under composer install --classmap-authoritative and inside a vendor/-installed path repository?
5. Which Laravel and PHP versions are supported, and is the scan tested against the Doctrine version we run?
6. Bus factor and release cadence: single maintainer? Is the scanning logic covered by tests in CI?

Integration Approach

Stack fit Fits any Laravel application already using Doctrine ORM, and is most valuable precisely in the multi-entity-manager case (multi-database, modular monolith, or read/write-split architecture). For a single-EM, single-app/Entities project the benefit is mild — it removes a config list you probably rarely edit — so the cost/benefit is weaker there. Prioritise adoption in the multi-EM service first; that is where the release note says the value is.

Migration path

1. Add the dependency pinned to 0.1.13 in a branch.
2. Publish config and enable scan alongside the existing explicit entity paths where the package allows it, then diff the discovered set against the known set. Any difference is a finding, not a nuisance.
3. Cut over: remove the manual list only after the discovered set matches exactly in dev, CI, and one production-like environment.
4. Keep the explicit list in version control history as the rollback path — reverting is a config change plus a redeploy, which is cheap.

Compatibility considerations Confirm PHP and Laravel constraints against the application matrix before anything else; a pre-1.0 package frequently lags new Laravel majors. Verify behaviour under the production autoloader flags, and check whether the app's CI runs composer install --no-dev -o, since that is the environment most likely to differ from dev.

Sequencing Discovery/spike (half a day, one engineer) → diff-verification in CI → enable in a non-critical service for one release cycle → enable in the multi-EM service → remove manual path lists. Do not bundle this with a framework or Doctrine upgrade; keep the blast radius single-cause. If a Doctrine or Laravel major upgrade is already queued, land this first, on the current pinned versions.

Operational Impact

Maintenance Ongoing cost is low but non-zero: exact-version pinning plus a deliberate review each time the version is bumped, which for a fast-moving 0.1.x line could mean a small review per month. Budget a recurring line item rather than a one-off. Ownership should sit with whoever owns the Doctrine/ORM configuration, not with application feature teams.

Support Unverified. The package appears to be early-stage with a narrow feature surface; expect community-only support and be prepared to read the source. Have a named internal owner who can patch config or revert without an escalation. Given the absence of any supplied project data for this assessment, treat supportability as the largest unquantified risk.

Scaling Two dimensions. First, repository size: scan cost grows with files walked, so a large monolith or a monorepo with many excluded-but-still-walked directories will feel it at boot; measure cold-start time with and without the scan before committing. Second, entity count and EM count: the multi-EM routing logic is the part most likely to have superlinear or subtly wrong behaviour at scale — exercise it with the real number of EMs, not one.

Failure modes to plan for

• Silent under-discovery — an entity not found means a runtime "class is not a valid entity" error deep in a request. Add a startup or CI assertion comparing discovered count/names against an expected manifest.
• Over-discovery — non-entity classes registered, producing metadata errors or unexpected schema diffs in migrations. A doctrine:schema:validate-style check in CI catches this.
• Production-only autoloader divergence — the classic failure. Always validate in an image built with the production install flags.
• Cache staleness after deploy — if scanning is cached, a deploy adding entities without a cache invalidation step yields missing entities. Wire cache clearing into the deploy pipeline explicitly rather than assuming.
• Version drift — an unpinned minor introducing a signature change. Prevented by exact pinning.

Ramp-up Low for a competent Laravel/PHP engineer: installation and configuration are familiar patterns. The learning is not in the API but in the boundaries — what the scanner considers an entity and how it assigns EMs. Write that down as a short internal note during the spike; it is the artefact that makes the second and third integration cheap, and it is what prevents the next engineer from silently reintroducing manual entity lists.