Has Source Model Laravel Package

Technical Evaluation

Architecture fit brokeyourbike/has-source-model-laravel is a single-purpose Eloquent concern: a HasSourceModel trait (plus supporting contract/config and a published migration) that attaches provenance — a model records which other model it was derived from. Architecturally this is a good fit for Laravel: it composes via trait on existing models, follows standard package conventions (auto-discovered service provider, publishable config and migration), and does not impose a repository layer, base class, or container bindings. It slots in alongside our existing models rather than restructuring them. The v3.0.0 reference feature appears additive to that core concept, but the release notes do not say whether it introduces a new column, a new relation type, or a new resolution strategy — that distinction determines whether this is a config change or a schema change for us.

Integration feasibility Low-to-moderate effort in principle: composer require, publish the migration/config, add the trait and interface to the target models, backfill existing rows. The blocker is not effort but information: v3.0.0 is a major bump whose only breaking-change description is the word "braking." There is no migration guide, no deprecation notice, no indication of renamed methods, changed column names, changed polymorphic type resolution, or a raised PHP/Laravel floor. We cannot estimate blast radius from the notes; we must read the diff at commit cb25541 and compare composer.json between v2 and v3.

Technical risk

• Unknown breaking surface (high). A major version with an unlabeled break means our upgrade estimate is unbounded until the diff is reviewed. Polymorphic key or column renames would imply a data migration on live tables.
• Maintainer/bus factor (medium-high). Single-maintainer package with a narrow audience. Low issue volume is not the same as stability.
• Release discipline (medium). Auto-generated notes with typos, an empty feature description, and a bugfix titled "braking" suggest semantic-release automation without human curation. Expect noisy changelogs and thin upgrade documentation going forward.
• Schema coupling (medium). If reference added a column, every consuming model's table needs a migration; on large tables that is a locking operation to schedule.

Key questions

1. What exactly changed between v2 and v3 — method signatures, column names, relation names, or the polymorphic type map?
2. Is there a supported v2 → v3 data migration, or does it require a backfill we write ourselves?
3. What are the new php and illuminate/* constraints? Which Laravel and PHP versions are dropped?
4. Does the reference feature require a new column or migration, and is it opt-in?
5. Is v2 still receiving security fixes, and for how long?
6. Does the package define cascade/delete behavior for source models, and is that behavior stable across the break?

Integration Approach

Stack fit Standard Laravel/Composer integration — compatible with our Eloquent-based services assuming our Laravel and PHP versions satisfy v3's constraints (unverified; see key question 3). No framework-level conflict expected; the package does not patch core behavior or override query builders. Confirm it does not collide with any existing trait or global scope named source/reference on the same models.

Migration path

1. Do not bump blindly. Pin ^2.0 in composer.json until the diff is reviewed. Audit for any * or unconstrained requirements that could pull v3 in transitively.
2. Diff review. Compare v2…v3 for composer.json, trait method names, migration stubs, and config keys. Produce a one-page impact note.
3. Branch upgrade. Bump to ^3.0 on a branch, run the full test suite, and specifically exercise any model using the trait — including soft deletes, polymorphic sources, and eager loading.
4. Data backfill (conditional). If columns or type keys changed, write a reversible, batched backfill and dry-run it against a production-shaped copy.
5. Rollout. Ship behind the existing feature flag if the trait is not yet in production; otherwise stage by service, not by table.

Compatibility Verify explicitly against each Laravel version we run; if we are mid-upgrade on the framework, sequence the framework bump first so we do not debug two majors at once. Check the package's PHP floor against our oldest runtime — this is the most common cause of a "breaking" minor-looking major in small Laravel packages.

Sequencing Framework upgrade → package diff review → POC on one low-risk model → full test pass → backfill (if needed) → wider adoption. If reference is genuinely new capability we want, treat it as a separate, later ticket so the v3 upgrade itself stays a pure compatibility change with a clean rollback point.

Operational Impact

Maintenance Assume we own the upgrade risk. Recommend locking to an exact minor (3.0.*) rather than a floating constraint, vendoring or forking if the package becomes load-bearing, and adding a calendar reminder to re-review upstream before our next Laravel major. Given the changelog quality, treat upstream release notes as unreliable and read commits instead.

Support Community-only: GitHub issues, no SLA, no commercial backing. Acceptable for a thin trait; not acceptable if provenance becomes a compliance or audit dependency. In that case, budget for an internal fork with a named owner.

Scaling The trait is relation-based, so the operational cost is query shape, not throughput. Watch for N+1 when hydrating collections with source models — enforce eager loading (with('source')) and consider a global scope or lint rule. Ensure the source foreign key and polymorphic type columns are indexed; a provenance column without an index turns a detail page into a table scan at volume.

Failure modes

• Silent auto-upgrade via a permissive constraint pulling v3 into a deploy — the primary risk here.
• Orphaned references if source models are hard-deleted without cascade or nullify handling; confirm the package's behavior rather than assuming.
• Polymorphic type drift if we rename model classes or move namespaces; stored morph types become stale and resolution returns null silently.
• Migration locking on large tables if reference added a column via a non-ALGORITHM=INSTANT path.
• Null source during backfill windows — consuming code must tolerate a missing source rather than assuming non-null.

Ramp-up Low. One trait, one config file, one migration — a mid-level Laravel developer is productive in half a day. The cost is concentrated in the v3 upgrade investigation, not in learning the API. Document the trait's semantics (when to set a source, what null means, deletion behavior) in the team's model conventions, because "where did this record come from" is a question future engineers will ask and the package's own docs are thin.