Contracts Laravel Package

Technical Evaluation

Architecture fit. MoonShine is a Laravel admin panel / CRUD scaffolding ecosystem, and moonshine-software/contracts is the interface layer that the rest of the monorepo (core, fields, decorators) depends on. For a team already standardized on Laravel, this is a well-aligned fit: it plugs into the existing service-provider/config/policy conventions rather than introducing a parallel framework. For teams not on Laravel, it is effectively a non-starter. The package itself is low-level — it defines contracts, not behavior — so its architectural weight is small, but its blast radius is high because core packages compile against it.

Integration feasibility. Technically straightforward: Composer install, publish config, register the service provider. The real integration cost sits in the surrounding MoonShine stack (auth, resources, fields), not in contracts itself. Version 4.18.1 is a patch-level release with no documented API surface changes, so a like-for-like swap should be low-risk for a team already on the 4.14+ line.

Technical risk. The release notes are effectively a pointer to the monorepo changelog and a compare link — there is no human-readable changelog in the artifact we received. That is the primary risk: we cannot confirm from the release note alone that the contract diff between 4.14.0 and 4.18.1 is non-breaking. Given the minor/patch versioning (4.14 → 4.18), SemVer would suggest backward compatibility, but the package is a contracts package, where an added method to an interface is technically a breaking change for downstream implementers even in a patch release. Risk is low but unverified.

Key questions.

1. Does the 4.14.0 → 4.18.1 diff add methods to any existing interface, or only add new interfaces? (Additions to existing interfaces are breaking for anyone implementing them.)
2. Is contracts version-locked by the core MoonShine package, or can it drift independently? If locked, the upgrade is atomic with core.
3. What is the supported Laravel/PHP version matrix for 4.18.x? The release note omits it.
4. Are the linked changelogs the canonical source of truth, or is there a maintained CHANGELOG.md in the package?
5. Is there a documented deprecation policy for contracts across majors (4.x → 5.x)?

Integration Approach

Stack fit. Requires Laravel (and by implication PHP 8.x). No front-end integration surface beyond what MoonShine core already manages. It is a library dependency, not an application-layer choice, so the "decision" is really about adopting MoonShine core; contracts follows transitively.

Migration path. Because there is no prior assessment and no evidence this package is currently in the stack, treat this as a greenfield evaluation rather than a migration. If already on MoonShine 4.14.x, the path is: bump contracts alongside core in the same PR, run the full test suite, and verify any custom resource/field classes that implements MoonShine interfaces still satisfy the contract.

Compatibility. Confirm PHP and Laravel constraints in composer.json before bumping — the release note does not state them. Check that moonshine/moonshine and moonshine-software/contracts resolve to a mutually compatible set; do not bump contracts in isolation if core pins it.

Sequencing.

1. Read the monorepo changelog and the 4.14.0…4.18.1 compare diff (the release note's only real content).
2. Grep the codebase for implements against MoonShine contracts to inventory custom implementations.
3. Bump in a branch, run CI, and smoke-test admin CRUD flows.
4. Ship; no data migration expected for a contracts-only change.

Operational Impact

Maintenance. Low ongoing burden — it is a dependency, not infrastructure. The maintenance cost is tied to tracking the MoonShine monorepo release cadence, which appears frequent (4.14 → 4.18 within the observed window). Budget for routine dependency bumps each sprint.

Support. Upstream is a commercially-backed open-source project with documentation and a community channel; there is no vendor SLA unless a support plan is purchased. Internal support burden is limited to knowing who owns MoonShine customization in the codebase.

Scaling. Negligible runtime impact — interfaces impose no overhead. Scaling concerns live in MoonShine core and the underlying database, not here.

Failure modes.

• Silent contract break: an added interface method breaks custom implementations at runtime/deploy rather than at composer install — mitigate with static analysis (PHPStan/Larastan) and full test coverage on custom resources.
• Version skew: bumping contracts without core (or vice versa) yields hard-to-diagnose type errors — mitigate by pinning the pair and upgrading atomically.
• Unreadable changelog: the release note is a link, not a summary, so automated dependency bots will surface this as "unknown change" — require manual review before auto-merge.

Ramp-up. Minimal for a Laravel-fluent engineer (hours to read the contracts and conventions). The real ramp-up is MoonShine core concepts (resources, fields, policies), measured in days, not weeks.