Lurkerlite Laravel Package

Technical Evaluation

Architecture fit. LurkerLite (totten/lurkerlite) is a small, dependency-free PHP library that implements in-memory resource change tracking. It gives you a lightweight API to register resources, set fields, and query which fields are changed, clean, or dirty — decoupled from any persistence layer. In a Laravel codebase, the first question a TPM must ask is why. Eloquent already ships isDirty(), getDirty(), getOriginal(), observers, and model events. LurkerLite only becomes architecturally interesting when: (a) you have a non-Eloquent domain model (legacy PHP, DTOs, value objects, third-party SDK entities) that still needs change detection; (b) you want to isolate change tracking from persistence so the domain layer does not depend on Eloquent; or (c) you are porting a legacy CiviCRM-style codebase where this pattern is already established. Absent one of those drivers, this is a solution looking for a problem.

Integration feasibility. Composer-installable, MIT-licensed, single maintainer (Tim Otten, a well-known CiviCRM developer). The API is small and the code footprint is tiny, so a proof-of-concept is cheap. The real friction is informational, not technical: 2 stars, 0 dependents, thin/no public documentation, and no evidence of a test suite or CI. Feasibility is therefore high to install, low to trust.

Technical risk.

• Maintenance risk (high): near-zero community footprint; abandonment is the default assumption.
• Compatibility risk (medium): must verify composer.json PHP constraint against your runtime (PHP 8.1–8.3) and against Laravel 10/11's autoloading and helper expectations.
• Correctness risk (medium): change-tracking bugs are silent — a missed set() or a mis-scoped reset() can cause stale writes or no-ops downstream.
• Documentation risk (high): onboarding will require reading source, not docs.
• Licensing risk (low): MIT is permissive and compatible.

Key questions.

1. Which concrete Laravel component or legacy module needs change tracking that Eloquent cannot provide?
2. Does the library support our PHP/Laravel version matrix, and is there a CI badge or test suite to prove it?
3. Who owns the fork if the upstream goes quiet?
4. What is the exact semantics of isChanged() / getChanged() on nested or array-valued fields — are we confident enough to rely on it for write decisions?
5. Is the maintenance budget for vendoring, patching, and testing this library cheaper than writing a 200-line internal tracker?

Integration Approach

Stack fit. Treat LurkerLite as a utility, not a framework. It fits cleanly at the edges of a Laravel app — inside a service class, a domain object, or an adapter around a legacy resource — and should never become the canonical mechanism for Eloquent model state. If the team's mental model is "models are Eloquent," introducing a parallel tracking abstraction creates two sources of truth and invites drift. Fit is acceptable only when the tracked resource is genuinely outside Eloquent's reach.

Migration path. This is a greenfield utility, not a migration target. Recommended path:

1. Isolate a single bounded context (e.g., a legacy import service or a third-party entity wrapper) where change tracking is currently hand-rolled with boolean flags.
2. Wrap LurkerLite behind a small internal interface (TrackedResource, ChangeSet) so the rest of the app never imports the vendor namespace.
3. Prove it with a spike against real payloads before committing.

Compatibility. Verify composer.json require.php and require-dev against the target runtime; run composer why-not and composer outdated. Confirm no global helpers or ext-* dependencies collide with Laravel's. Because there are no dependents, there is no ecosystem signal that it works on modern PHP — that is a check you must perform yourself, ideally by running the upstream tests (if any) under phpunit on PHP 8.2/8.3.

Sequencing.

1. Week 1 — Evaluation spike: clone, run tests if present, exercise the API against 2–3 real change-tracking scenarios.
2. Week 1 — Compatibility gate: PHP 8.x + Laravel 11 install and smoke test.
3. Week 2 — Internal adapter: write the thin wrapper and unit tests that codify expected isChanged/getChanged semantics.
4. Week 3 — Contained rollout: one non-critical service; instrument with logging.
5. Week 4+ — Decision point: promote, vendor, fork, or replace with an internal 150–300 LOC implementation.

Operational Impact

Maintenance. The dominant cost. With 2 stars, 0 dependents, and no visible release cadence, plan for the upstream to be effectively frozen. Two viable postures: (a) vendor + patch — commit the source into the repo or a private fork with our PHP/Laravel constraints and tests; (b) internalize — reimplement the ~200 lines of tracking logic we actually use, removing the third-party surface entirely. For a library this small, option (b) is often cheaper over a 24-month horizon.

Support. No commercial support, no SLAs, no community forum. Internal ownership must be explicit — name a team and an engineer. Ticket triage for this library should be treated as internal development, not vendor escalation.

Scaling. Per-object memory overhead is trivial (a few arrays per tracked resource), so it scales fine for request-scoped use. It does not address distributed tracking, event sourcing, or audit logging — if the underlying requirement is "audit every field change to the database," LurkerLite gives you the detection primitive but not the persistence or transport. Clarify the requirement before scoping.

Failure modes.

• Silent no-op writes: if change detection returns false when a field did change, downstream persistence skips the write — data loss without an exception.
• False positives: unnecessary writes and noisy events, wasting DB round-trips.
• State leakage across requests: long-lived workers (Octane, queue workers) reusing tracked objects can carry stale dirty flags — ensure lifecycle resets.
• Semantic drift on arrays/objects: reference semantics may mean "changed" is never detected for nested structures; codify with tests.
• Upstream abandonment: a future PHP major version breaks the library with no patch path.

Ramp-up. Developer ramp-up is low — the API is small enough to learn in under an hour from source. Organizational ramp-up is the real cost: because documentation is absent, the adapter wrapper and its unit tests become the documentation. Budget roughly 1–2 engineer-days for the spike plus adapter and tests, and treat the "vendor vs. rebuild" decision as a mandatory checkpoint before any second consumer adopts the library. Given the adoption score (0.04) and the fact that Laravel natively covers most of the same ground, the default recommendation is do not adopt broadly; permit it only as a scoped, wrapped, internally-owned utility with a documented exit plan.