Laravel Fileable Laravel Package

Technical Evaluation

Package: astrotomic/laravel-fileable — Laravel package providing a reusable trait for attaching files to Eloquent models via a polymorphic relationship.

Architecture fit: Fits the standard Laravel package pattern: a service provider, a publishable migration for a shared files table, a polymorphic fileable morph map, and a model concern applied to consuming Eloquent models. This is the idiomatic shape for a cross-cutting attachment capability and avoids per-model join tables. It is a good fit if the product needs generic file attachment across several entities (User avatar, Post hero image, Invoice PDF) and we want one storage contract rather than N bespoke implementations. It is a poor fit if only one model needs files — a direct HasMany plus a dedicated table is simpler to reason about and cheaper to own.

Integration feasibility: Low-to-moderate. Integration is composer require, publish + run the migration, then add the concern to each model. No external services, no queue workers, no config-heavy wiring. Estimated initial integration: 1–2 developer-days including a spike to validate storage disk configuration and authorization expectations. The main unknown is how much of our existing ad-hoc file handling must be backfilled into the new schema — that is the real cost driver, not the package itself.

Technical risk: The package is pre-1.0 (0.3.0), which is the dominant risk. 0.3.0 itself is a breaking change: the concern \Astrotomic\Fileable\Concerns\Fileable was renamed to \Astrotomic\Fileable\Concerns\HasFiles (PR #2). This is a rename of a public API symbol, so every use statement referencing the old trait on every model will fatal-error after upgrade. Mitigating factors: no database schema change, no data migration, and the fix is a mechanical find-and-replace across model classes. The rename is also directionally correct — HasFiles matches Laravel's own Has* relationship-trait convention (HasMedia, HasTags) and reduces collision risk with domain classes we might also want to name Fileable. Secondary risks: low release cadence and a small maintainer surface (Astrotomic), meaning we may need to vendor or fork for urgent fixes; and pre-1.0 fluidity means further renames/signature changes are plausible at 0.4/0.5.

Key questions:

1. Is the polymorphic shared-files table acceptable to our data model, or do we need per-entity constraints/FKs and typed attachment "collections"?
2. Does the package enforce any authorization on attach/detach, or is access control entirely our responsibility at the controller/policy layer?
3. What is the storage abstraction — does it delegate to Laravel's Storage facade and disks (S3, local), and does it handle deletion of the underlying object on model delete?
4. Are there soft-delete, orphan-cleanup, and cascade behaviours we need, and are they configurable?
5. What is our exit cost if we abandon the package — is the schema generic enough to retain and query directly?
6. Do we pin to an exact version (recommended pre-1.0) or float on ^0.3?

Integration Approach

Stack fit: Requires a Laravel version in the package's supported range and PHP 8.x-era conventions (namespaced concerns, service provider auto-discovery). No frontend or queue dependency. Fits cleanly alongside Laravel's filesystem abstraction and any existing media/image-manipulation packages, though overlap should be checked — if we already run Spatie Media Library or similar, laravel-fileable is redundant and we should not adopt both.

Migration path: For a greenfield integration, adopt 0.3.0 directly and use HasFiles from day one; the rename is a non-event. For an existing integration on 0.2.x, the upgrade is: (a) bump the constraint, (b) composer update astrotomic/laravel-fileable, (c) replace use Astrotomic\Fileable\Concerns\Fileable; with use Astrotomic\Fileable\Concerns\HasFiles; and update the use ...Fileable; statement inside each model class body, (d) grep the codebase for the FQCN in config, factories, seeders, tests, and any class-string references (Fileable::class) that static analysis and IDE refactors may miss. No migration, no data backfill, no storage changes. Effort: under half a day for a typical codebase, plus a regression pass on file upload/download paths.

Compatibility: The rename is not backward compatible — the package does not appear to ship an alias or deprecation shim, so a mixed-version fleet (some services on 0.2, some on 0.3) is fine but a partial in-repo upgrade is not. Any package or internal module that type-hints against the old trait name breaks. Because this is a 0.x release, semver permits the break; our composer constraint should reflect that we accept it, or pin 0.3.* explicitly.

Sequencing: (1) Validate fit with a one-model spike on a branch, including storage disk and authorization behaviour; (2) formalize the decision — adopt, defer, or build in-house — and record the pre-1.0 instability as accepted risk with a named owner; (3) pin the version in composer.json and add a Renovate/Dependabot rule that flags 0.x minor bumps as review-required rather than auto-merge; (4) roll out the concern model-by-model, starting with the lowest-traffic entity; (5) only after the pattern is proven, consider backfilling existing files — treat that as a separate, separately-estimated workstream.

Operational Impact

Maintenance: Ongoing cost is low in steady state (no daemons, no scheduled jobs, no external services) but the attention cost is non-trivial pre-1.0. Expect to review every minor release for renames like 0.3.0. Budget roughly 0.5–1 day per minor release for review plus codebase sweep. Ownership should sit with the team that owns the models using the trait; a platform/backend owner is appropriate given the cross-cutting nature.

Support: Community-supported open source with a small maintainer base. No vendor SLA. Our realistic support posture is "we can read the source and patch it ourselves" — the package is small enough that forking or vendoring is viable, and we should confirm licensing permits that (MIT or similar) before adoption. Escalation path is GitHub issues/PRs, which for a low-traffic repo may be slow; do not place a critical-path dependency here without accepting that we may carry a local patch.

Scaling: The trait itself is thin; scaling characteristics are inherited from the shared files table and the storage backend. Watch for: unbounded growth of a single polymorphic table (add indexes on fileable_type/fileable_id and monitor), N+1 queries when listing models with files (with('files') discipline in the codebase), and object-storage egress/cost as volume grows. No horizontal-scaling concerns — it is stateless request-path code.

Failure modes:

• Post-upgrade fatal error — stale use ...\Concerns\Fileable; on any model throws a class-not-found; caught by tests if model coverage exists, otherwise surfaces at runtime. Highest-likelihood failure of this release.
• Class-string misses — references via Fileable::class or in config/factories that a namespace-only grep doesn't catch.
• Silent 0.x drift — auto-merged minor bump introduces a second rename with no deprecation window.
• Orphaned storage objects — if file deletion isn't wired into model deletion, blobs accumulate and cost grows invisibly; verify and monitor.
• Authorization gap — if the package provides the attach path without policy checks, an IDOR-style exposure is possible; must be covered by our own policy layer and tested.
• Maintainer abandonment — low cadence means a security fix may not arrive; mitigated by the small surface area and fork viability.

Ramp-up: A Laravel-fluent developer picks this up in well under a day; the concept (polymorphic relation + trait) is standard. The non-obvious knowledge to document is: which models use the trait and under which name (post-rename, HasFiles), the storage disk mapping, the authorization contract, and the orphan-cleanup behaviour. Recommend a short internal note plus a code-owner entry so the next minor release has an obvious reviewer. New hires do not need package-specific onboarding beyond the trait's presence in the model layer.