Sidekick Laravel Package

Technical Evaluation

What the asset actually is. orchestra/sidekick is not application infrastructure — it is a package-author utility layer maintained by the Orchestra Platform team (crynobone). Its surface is a set of namespaced helper functions (model_diff(), model_state(), model_from(), Env, package_path(), filename_from_classname(), package_version_compare(), after_resolving(), is_testbench_cli(), working_path(), filesystem helpers, php_normalize_version()), plus a HasPreviousAttributes trait/polyfill and a console ConfiguresPrompts trait. There is no service provider, no config file, no migrations, no publishable assets.

Architecture fit. Fit is conditional on one question: do we author and maintain Laravel packages, or only consume them? If we maintain packages, publish internal starter kits, or run Testbench-based suites, fit is high — these helpers replace exactly the glue code (diffing Eloquent state, resolving package paths, version comparison, prompt configuration) that teams otherwise copy-paste between repositories. If we only build product applications, fit is low: each utility is 5–30 lines of code and the "buy" case reduces to convenience while adding a third-party dependency to the review surface. Note the deliberate tension in the signals — an overall score of 9.9 reflects release discipline and ecosystem health, while an opportunity score of 55.25 reflects a narrow, intentional niche.

Integration feasibility. Effectively trivial mechanically: Composer-only, MIT-licensed, no registration step, usable immediately after require. Real effort is governance, not engineering. Two maintained lines (1.1.x and 1.2.x) receive parallel backports of the same PRs, so we must decide which line we standardize on and pin accordingly. The package also tracks pre-release upstream aggressively (Laravel 14.x-dev, PHPUnit 13.x-dev support landed in v1.1.24/v1.2.x-era releases), which is a leading indicator of maintenance quality but also of churn.

Technical risk.

• Stability contract. Orchestra\Sidekick\Eloquent\Watcher is explicitly marked @internal; other internals may follow. Any API not documented in the README should be treated as unstable.
• Behavioral drift in model_diff() / model_state(). The changelog shows repeated correctness fixes (create vs. update state, $appends exclusion, original-attribute handling). Consumers who build audit logs, change feeds, or snapshot assertions on these outputs are exposed to silent semantic changes across patch releases.
• Polyfill divergence. HasPreviousAttributes backfills framework behavior on older Laravel versions; upgrading Laravel means the polyfill path and the native path must agree, or subtly different results appear.
• Bus factor. Single maintainer, single-org stewardship. Zero-dependents metadata is a weak adoption signal and understates real usage (Testbench/Orchestra packages consume it transitively).
• Helper collisions. Global-scope function autoloading can collide with app-level or other package helpers of the same short name.

Key questions for the review.

1. How many of our repositories actually author packages versus consume them? That ratio decides the whole business case.
2. Which Laravel/PHP versions are in our support matrix, and therefore which of the 1.1.x / 1.2.x lines do we standardize on?
3. Are we willing to depend on @internal-marked classes, or do we restrict usage to README-documented helpers?
4. Does Testbench already pull this in transitively — i.e., are we formalizing an existing dependency rather than adding one?
5. Do we accept a single-maintainer dependency for tooling that sits inside our release pipeline?

Integration Approach

Stack fit. Native to the Laravel + Composer + PHPUnit/Pest stack. It slots in as a require-dev or require entry in package skeletons; nothing about it constrains application architecture because it is only reachable from code we write deliberately. The strongest structural fit is with Testbench-based package test suites, where is_testbench_cli(), working_path(), and package_path() remove per-repository hardcoding.

Migration path. Adoption is additive, not a cutover. Sequence:

1. Inventory existing internal helper duplication across package repos — count occurrences of hand-rolled model-diff, path-resolution, and version-compare utilities. This is the value baseline.
2. Pilot in one low-risk internal package: replace helpers, run the existing suite unchanged, confirm no behavioral delta in snapshot/diff assertions.
3. Standardize by adding the pinned dependency and a short usage note to the internal package skeleton, so new packages inherit it by default.
4. Retire the duplicated internal helpers behind a deprecation note; keep a single owner accountable for the mapping table.
5. Re-evaluate at the next Laravel major upgrade rather than on a fixed calendar.

Compatibility. Pin exact versions in package skeletons rather than floating ranges — the patch cadence is high and semantic fixes have shipped in patch releases. Treat the 1.1.x/1.2.x choice as a matrix decision documented alongside our Laravel support policy, and verify each line's actual PHP/Laravel constraints in composer.json rather than inferring from release notes. Avoid orchestra/testbench-core leaking into production dependency graphs — it belongs in require-dev only.

Sequencing. Do the inventory and pilot in the same quarter; the pilot is days of work, and the inventory is the artifact that justifies the rest. Defer org-wide standardization until at least one full Laravel upgrade cycle has been traversed with the package in place, so we observe its upgrade ergonomics before we commit everyone to it.

Operational Impact

Maintenance. Low steady-state cost: no runtime services, no persistence, negligible footprint. The maintenance burden shifts to version governance — someone must own the pin bump and read the changelog for semantic changes in model_diff()/model_state() before bumping. Budget a recurring but small allocation, not a project.

Support and ownership. Assign an internal owner (platform/tooling team) responsible for the pin, the sanctioned-API list, and the escalation path to the upstream maintainer. Because this is single-maintainer upstream, define a fallback posture up front: the helpers are small enough that forking or inlining the three or four functions we actually depend on is a credible contingency, and cheap to exercise if needed.

Scaling. Scales cleanly across many repositories precisely because it is dependency-free and stateless — the marginal cost of the 20th adopting repo is a line in a skeleton. The bottleneck is social, not technical: without a published list of sanctioned helpers, teams will adopt internals and create upgrade friction. A short internal style rule ("use these six helpers; do not touch @internal classes") is the highest-leverage operational control here.

Failure modes to plan for.

• Upstream abandonment or a stall on a Laravel major release → pin holds, upgrade blocks; mitigate with the inline/fork contingency.
• Silent change in diff/state semantics breaking snapshot tests or audit output → mitigate by asserting on our own domain-shaped fixtures, not on the helper's raw output shape, wherever feasible.
• Function-name collisions after a framework or package update → mitigate by scoping calls through an internal adapter where a collision is plausible.
• Polyfill divergence at Laravel upgrade → add an explicit upgrade-checklist item to re-run diff/state tests on both code paths.
• Dev-dependency creep from Testbench packages in CI → isolate to test jobs, keep the production graph clean.

Ramp-up. Hours for a Laravel-fluent engineer; the helpers are self-describing and the README plus changelog is sufficient onboarding material. The real ramp-up cost is organizational: the sanctioned-API list, the pinned-version policy, and the upgrade checklist must exist before broad adoption, or every repository reinvents its own interpretation of what is safe to call.