Laravel Model Schema Laravel Package

Product Decisions This Supports

• Build vs. buy (or rather: adopt vs. vendor vs. replicate). This is a thin convention layer, not a platform. The package collapses a model's $casts, $fillable, and $hidden into one $schema declaration. That is a few days of work to replicate internally and a near-zero-cost pin-and-fork to adopt. The decision it should trigger is "do we care enough about model-attribute explicitness to standardize it?" — not "which vendor do we sign with?"

• Developer experience / internal platform roadmap. Making model attributes explicit is a DX investment. It pays back through faster onboarding, cheaper code review, and fewer "why is this field leaking into the JSON response?" fire drills. This package is a cheap way to prototype whether the convention sticks before you commit engineering time to a first-party implementation.

• Security posture and data-exposure risk. Merging $hidden, $fillable, and $casts into one visible declaration makes the serialization surface of every model reviewable in one place. That directly supports roadmap items around PII handling, API response hygiene, and mass-assignment safety — the classes of bug where a single forgotten $hidden entry ships a field to a client.

• API contract clarity / documentation. If models are the de facto contract for JSON payloads, an explicit schema is the cheapest possible source of truth for API consumers, SDK generation, and frontend typing. Supports decisions about whether to invest in formal API specs or derive them.

• Codebase standardization and tech-debt prioritization. Adopting a convention like this is a forcing function: it makes inconsistency legible. The audit ("how many models declare attributes three different ways?") is itself a useful input to planning work, independent of whether you ship the package.

• Framework upgrade readiness. Laravel major-version upgrades routinely break $casts semantics and attribute handling. A centralized schema is a smaller, more auditable migration surface. Relevant to decisions about timing and cost of Laravel 10/11/12 upgrades.

• Hiring and knowledge-transfer risk. Explicit schemas reduce the "tribal knowledge" tax on models. Supports decisions about documentation standards and onboarding investment for a growing or high-turnover team.

• Feature-level use cases where this earns its keep: audit/event logging, admin panels and CRUD scaffolds, CSV/import-export pipelines, and webhook payload construction — anywhere a model's field inventory is consumed programmatically and drift is expensive.

When to Consider This Package

Consider it when:

• You have a large Laravel codebase — dozens or hundreds of Eloquent models — where $casts/$fillable/$hidden have drifted and reviewers routinely miss exposure bugs.
• You are in a regulated or sensitive domain (payments, health, PII) where an accidental serialized field is a reportable incident, not a bug ticket.
• You want to standardize conventions across multiple squads and need a concrete, low-ceremony artifact to point at rather than a style-guide document.
• You are prototyping a DX convention and want evidence of value before funding a first-party build.
• You can accept the operational cost of pinning and vendoring a small, low-traffic dependency.

Look elsewhere — or build in-house — when:

• Maintenance risk is disqualifying. 12 stars, a single maintainer, and a last release in September 2023. There is no SLA, no security-response process, and no guarantee of Laravel 11/12 compatibility. Treat this as source you adopt, not a dependency you trust.
• Your codebase is small. Under a few dozen models, the convention cost exceeds the drift cost. Native $casts with typed properties and a good linter gets you most of the way.
• You already have a stronger abstraction. spatie/laravel-data, typed DTOs, or PHP 8.1+ readonly/typed properties solve the same explicitness problem with active maintenance and broader community support. Prefer those if you are greenfield.
• You need static analysis, not runtime structure. Larastan/PHPStan plus laravel-ide-helper address IDE and type-checking pain without introducing a dependency.
• You need a supported vendor relationship (procurement, security review, indemnification). This package will not clear that bar.
• The team lacks Laravel depth. A non-standard convention layer increases cognitive load for engineers who expect idiomatic Eloquent. Adopt only with documented internal ownership.

Adoption gate: verify compatibility against your Laravel and PHP versions, vendor the source, assign a named internal owner, and set a review date. If those four things can't be committed, don't adopt.

How to Pitch It (Stakeholders)

For executives (one paragraph): We are evaluating a small open-source convention for our Laravel backend that makes each data model's fields, validation rules, and API visibility declared in one place instead of scattered across three separate lists. The business value is risk reduction: the most common cause of accidental data exposure — a customer record shipping a field it shouldn't — is a forgotten entry in one of those lists. Consolidating them makes the exposure surface reviewable at a glance. Cost is low and adoption is incremental, but the package itself is a small community project with a single maintainer and no recent release, so the recommendation is to vendor a pinned copy under internal ownership rather than depend on it as a supported library, and to treat it as a pilot that informs whether we build a first-party version. This is a small, reversible bet on developer productivity and data hygiene — not a platform commitment.

For engineering leadership: Adopt as a pinned, vendored convention with a named owner. Pilot on one service or bounded context, measure review-time and exposure-bug frequency before and after, and set a 90-day decision point on whether to fork permanently or reimplement natively. Do not let it spread repo-wide until the pilot clears. Sequence it behind — not instead of — static analysis and typed DTOs where those are already planned.

For engineering teams: The pitch is narrow and honest: one place per model to see what is cast, what is mass-assignable, and what is hidden. That makes code review faster and makes "did anyone notice this field is now in the API response?" a question you can answer by reading one array. The tradeoffs are a non-idiomatic pattern that new Laravel hires won't recognize, and a dependency you now own. If you can't commit to owning it, use native casts plus Larastan instead and revisit in six months.