Model Laravel Package

Technical Evaluation

Architecture fit orchestra/model is the base model layer of the Orchestra Platform, not a standalone library. It extends Illuminate\Database\Eloquent\Model and layers on four concrete capabilities: Validable (validation bound to the saving event), Searchable (request-driven query scoping), Metable (model metadata), and Presenter (presentation bootstrapping), alongside base User/Role models, Orchestra-specific events, and contracts. Architecturally it is invasive by design: adoption means domain models extend Orchestra\Model\Model rather than Laravel's base model, placing the decision at the root of the domain layer — the hardest place in a Laravel codebase to reverse. Fit is effectively binary. For an existing Orchestra Platform application this is the correct base layer and the only question is version currency. For a conventional Laravel application, none of the four traits justifies a third-party base class, since each is reproducible in-house in tens to low hundreds of lines with full control retained.

Integration feasibility Mechanically the developer path is short: a composer require plus a base-class swap. The real gate is the compatibility matrix, not the install. Orchestra components track Laravel majors on separate release lines, and the only concrete currency signal available is the changelog entry showing v6.0.0 as "Update support to Laravel Framework v8." Before any design work, confirm a published release line exists for the target Laravel and PHP versions and when it last shipped. Testing adds a second dependency — orchestra/testbench and its own constraints — which must resolve alongside the existing harness. These conflicts typically surface late, after models are already ported, and break CI rather than production, so they must be validated in the same pass as the base install.

Technical risk

• Abandonment (high): single-maintainer, low-visibility package with zero dependents. Zero dependents means no community canary — we absorb all discovery cost and breakage reaches us first.
• Upgrade block (high): a base model cannot be casually patched around mid-upgrade. If the release line stalls at Laravel 8, it becomes a hard ceiling on the application's upgrade path and constrains the Laravel modernization roadmap directly.
• Lock-in (high): exit cost scales linearly with the number of models extending the base class. This is the primary cost driver and the one variable we control.
• Behavioral drift (medium): base classes that add magic (casting, mutators, save-time events) change semantics subtly across versions, and a package at this activity level will lack changelog discipline.
• Signal mismatch (counterpoint): a 0.3 package score against a 41.25 opportunity score points in opposite directions. Opportunity is a build-vs-adopt prompt, not adoption evidence; absent maintenance, the correct read is "reimplement the useful parts."

Key questions

1. Which release line supports our target Laravel and PHP, and what is its publish date?
2. Are we already on Orchestra Platform? If not, why is this in scope at all?
3. Which of the four traits do we actually need, and what is the internal cost to own them?
4. Is there a security disclosure process and a documented support window?
5. What is the license, and does it permit an internal fork if upstream stalls?
6. Who is the named internal owner if we adopt?

Integration Approach

Stack fit Adopt under exactly one of two conditions: (a) we are committing to Orchestra Platform broadly, or (b) a short spike proves the package saves materially more than reimplementation costs. If neither holds, the deliverable is "extract the two or three traits we need into App\Models\Concerns," not "add the dependency." That is the recommendation to take into architecture review. The default answer for a greenfield Laravel product is to use Illuminate\Database\Eloquent\Model directly.

Migration path If we proceed — most likely because a legacy Orchestra codebase already depends on it — containment is the design requirement. Never extend Orchestra\Model\Model directly in domain models. Introduce a single App\Models\BaseModel that extends it, so the dependency lives in one file and can later be swapped for Laravel's base model plus internal traits without touching the domain. If a fork becomes necessary, vendor it under our namespace with a documented patch policy rather than relying on floating dev- branch constraints. The migration path off the package should be written down at adoption time, not after the first upgrade crisis.

Compatibility Run composer why-not against the candidate version and the full Laravel/PHP matrix before committing, and validate on the oldest and newest supported PHP versions. Confirm orchestra/testbench resolves cleanly alongside existing test dependencies in the same pass; treat a resolution failure as a stop signal, not a workaround to engineer around. Audit the illuminate/* constraints explicitly rather than inferring support from the changelog line alone.

Sequencing

1. Spike (1–2 days): install on a throwaway branch, port three representative models, run the existing suite, and diff behavior against vanilla Eloquent.
2. Value test: enumerate the concrete capability gained. If the list is short or reproducible internally — which is the expected outcome — stop and reimplement the two or three traits actually needed.
3. Contained adoption: if proceeding, land App\Models\BaseModel, a pinned version constraint, a committed lockfile, a named owner, and a written exit plan before migrating more than a handful of models.
4. Review gate: reassess at each Laravel major. A missed release line triggers immediate fork-or-remove, decided in advance so it is not a crisis negotiation.

Operational Impact

Maintenance Budget as though we own it. Add a standing line item for dependency review every Laravel upgrade cycle, plus the realistic possibility of an internal fork. Every model added to the base class increases the cost of the eventual migration, so model count becomes a tracked product metric rather than an incidental implementation detail. Reassess at every Laravel major release and keep the fork-or-remove trigger visible in planning.

Support Community-only, best-effort, no SLA and no vendor to escalate to. Internal documentation of "what we rely on and why" is mandatory. Pin exact versions and commit the lockfile; floating constraints on a package at this activity level are an unforced error. Assume we are the canary, since no downstream dependents will catch upstream breakage before it reaches us. Confirm the license permits an internal fork and identify a security disclosure path before adoption, not after the first incident.

Scaling Runtime cost is negligible — it is a thin layer over Eloquent, and query performance is determined by schema, not this package. The scaling dimension that matters is codebase size and the migration liability it carries, which grows linearly with model count. Plan for that explicitly rather than discovering it during a framework upgrade.

Failure modes

• Upgrade block: no release for a new Laravel major, blocking the entire application upgrade.
• Silent semantic drift: casting, mutator, or save-event behavior changes between releases without a changelog entry.
• Trait collision: Validable and Searchable hooks colliding with application-level model behavior, producing bugs that surface only at save or query time.
• Test-harness breakage: orchestra/testbench constraint conflicts disabling CI mid-port.
• Bus-factor exposure: maintainer unavailability with no downstream dependents to fork or patch ahead of us.

Ramp-up Onboarding cost is understated. The API surface is familiar Eloquent, but the added magic is effectively undocumented, so engineers learn package-specific behavior by reading source and tests rather than documentation. Budget onboarding time for anyone touching the base model, and treat the single App\Models\BaseModel as the one file every engineer must understand before extending a domain model.