Fireworks Laravel Package

Technical Evaluation

Architecture fit

• The package is a single Eloquent trait that taps Laravel's native model event lifecycle (saved/updated/created) and adds "property-wise" hooks — i.e., reacting to which attribute changed rather than just that the model saved. Conceptually this is a thin convention layer over getChanges(), wasChanged(), and getOriginal().
• It fits cleanly into a standard Laravel domain model: no migrations, no service provider bootstrapping complexity, no schema coupling. Composable in the sense that a trait can be added per-model.
• Architectural concern: it embeds change-reaction logic inside the model, competing with the patterns most mature Laravel codebases standardize on (Observers, domain events, listeners). Two mechanisms reacting to the same save is a classic source of ordering bugs and double-dispatch.

Integration feasibility

• Very high on paper: composer require, use Fireworks; on a model, done. No infrastructure, no credentials, no external services.
• Real feasibility depends on unpublished details: the exact convention (method naming vs. event class dispatch), supported Laravel/PHP versions in composer.json, and whether it hooks boot{Trait} correctly alongside other traits.
• Because the surface area is tiny, a proof-of-concept on one model is a few hours of work, not a sprint.

Technical risk

• Abandonment risk (high): last release April 2022, 16 stars, 0 dependents, low health score. Effectively a single-author utility with no downstream validation and no upgrade cadence. Laravel 10/11 compatibility is unverified and likely to break on typed-property/return-type deprecations and event signature changes.
• Correctness risk (medium): property-wise hooks depend on dirty-attribute semantics, casts, and JSON columns — edge cases (multi-attribute saves, saveQuietly, withoutEvents, mass update(), forceDelete) are where these packages typically diverge from expectations. Mass updates bypass model events entirely, so "property changed" reactions silently don't fire.
• Conflict risk (medium): trait boot methods and observer ordering can produce double-firing, recursion (listener saves the model → hook fires again), or silent non-registration on naming collisions.
• Security/supply chain (low): MIT, no runtime deps beyond the framework, small code footprint — easy to audit and vendor.

Key questions

• What exactly is dispatched — a named event class, a generic PropertyChanged event with payload, or a convention-based method call? Is it queueable?
• Does it fire on created as well as updated, and how does it distinguish dirty vs. persisted state?
• How does it behave with casts, accessors, encrypted/JSON attributes, and multi-attribute updates?
• Is it compatible with our target Laravel and PHP versions, and does it compose with our existing Observers without double-dispatch?
• Does a throwing listener roll back the surrounding transaction, and is dispatch synchronous?
• What is the actual code volume and test coverage? (Forkability depends on this.)

Integration Approach

Stack fit

• Fits any Laravel application using Eloquent with standard model events; no assumption about queue driver, DB, or hosting.
• Poor fit if the codebase has standardized on Observers/domain events for model side effects — introducing a second, model-embedded mechanism fragments the convention. Fit improves if scoped to a niche (e.g., audit/derived-field hooks) with a documented rule for when to use it.

Migration path

• No data migration required; additive and reversible (use statement removed → behavior gone).
• Recommended path: (1) vendor the trait into app/Support/ rather than depending on the abandoned upstream, or (2) reimplement the ~50–150 lines in-house against our own Observer base class. Given 0 dependents and a low score, "build/vendor" dominates "buy" — the concept is trivial to reproduce and the dependency adds only upgrade risk.
• If adopting as-is: pin the version, add composer.json platform constraints, and treat it as internal code under our maintenance, not third-party.

Compatibility

• Verify illuminate/support and PHP version constraints against our matrix before anything else. Expect to patch return types and event signatures for Laravel 10+.
• Check trait boot-method naming collisions with existing traits and booted() hooks; check interaction with soft deletes and observers.
• Confirm behavior under DB::transaction, queued listeners, and Model::withoutEvents().

Sequencing

1. Source audit: read the entire trait, confirm dispatch mechanism and event names; record findings in an ADR.
2. Sandbox: install, write characterization tests covering create/update/multi-attribute/mass-update/soft-delete/saveQuietly.
3. Decide build-vs-vendor; if vendor, establish internal ownership and a patch branch.
4. Wrap behind a minimal internal abstraction (our own trait or Observer base) so call sites are insulated from the package.
5. Pilot on one low-risk model in staging with event logging enabled.
6. Progressive rollout model-by-model; add a lint/review rule for when the trait is permitted.

Operational Impact

Maintenance

• Upstream is dormant; assume zero external fixes. Budget for owning the code: a fork/vendored copy with an assigned maintainer, tests in our suite, and a documented patch process.
• Low absolute maintenance cost because the code is small and dependency-free — this is a "cheap to own, expensive to trust blindly" trade-off.

Support

• No vendor support channel; community-only (issues/PRs on a 16-star repo). Escalation path must be internal.
• Institutionalize knowledge: an ADR, a short internal doc on dispatch semantics and edge cases, and owned tests. Do not rely on the README, which is likely thin.

Scaling

• Per-save overhead is negligible (a dirty-attribute diff plus a dispatch). The scaling risk is downstream: property hooks that do I/O synchronously add latency to every write path and can amplify under load. Require listeners to be queued and idempotent.
• Cardinality risk: hooks attached broadly across models multiply the number of listeners/side effects per request; centralize and audit the dispatch log.
• Consistency risk at scale: bulk/batch updates bypass model events, so properties "changed" via query builder produce no hooks — a divergence between the hook's worldview and actual data.

Failure modes

• Silent no-fire: mass updates, saveQuietly, withoutEvents, or trait boot collision → downstream state drifts with no error.
• Double-fire: coexisting Observer + trait hook → duplicate jobs, duplicate audit rows.
• Recursion: hook mutates/saves the model → loop or stack exhaustion.
• Exception propagation: throwing listener in a synchronous dispatch rolls back the save (or leaves partial external side effects); queued listeners fail silently without failed-job monitoring.
• Upgrade breakage: Laravel major upgrade removes/alters trait boot behavior or event signatures → hooks stop firing, again silently.
• Mitigation for all of the above: assert hook firing in feature tests (event fakes), monitor dispatched-event volume, and add a periodic reconciliation check for derived state.

Ramp-up

• Developer ramp-up is very low: one trait, one use line, familiar Eloquent concepts — under an hour for a Laravel-fluent engineer.
• Hidden cost is behavioral ramp-up: understanding dirty-attribute semantics and exactly when hooks fire requires reading the source, not the docs. Budget a half-day for the first engineer to build the edge-case test matrix, which then serves as the team's onboarding artifact.
• Operational ramp-up: SRE/on-call needs the failure-mode list above and a dashboard for dispatch volume and failed listener jobs.

Bottom line: Low technical risk per line of code, high ownership risk per dependency. The TPM recommendation is to vendor or reimplement the ~100-line concept internally rather than take a dormant, unvalidated dependency into a core write path; adopt the pattern, not the package.