Laravel Fileable Laravel Package

Getting Started

Install the package and verify the current trait name for 0.3.0+:

composer require astrotomic/laravel-fileable

Publish and run any package migrations/config provided by the service provider, then add the trait to the model that should own files:

use Astrotomic\Fileable\Concerns\HasFiles;

class Post extends Model
{
    use HasFiles;
}

Look first at:

• src/Concerns/HasFiles.php for the model-side API.
• The package File model and migration for the files table shape.
• The package config/README for disk, table, and publish tags.

A good first use case is a Post or User model with uploaded documents or images: validate the upload in a controller/FormRequest, store it on a configured Laravel disk, associate it with the model through the package’s file relationship, and render/download it later from $post->files.

Implementation Patterns

Use the trait as a polymorphic attachment layer. Add HasFiles to each model that needs files, rather than building separate attachment tables per model:

class Post extends Model
{
    use HasFiles;
}

class User extends Model
{
    use HasFiles;
}

Typical controller flow:

1. Validate the upload with a FormRequest.
2. Store the file on a dedicated disk, e.g. files or private.
3. Create/attach the package file record to the model.
4. Return or redirect without exposing raw storage paths.

Prefer the package relationship for reads:

$post = Post::with('files')->findOrFail($id);

foreach ($post->files as $file) {
    // render name, size, mime type, URL/download route
}

Eager load files anywhere you list multiple models to avoid N+1 queries. If a screen only needs metadata, select only the columns you need.

For multiple file types, keep the distinction in your application layer rather than duplicating trait logic: collections, categories, or custom metadata columns on the package file record. Use Laravel policies and signed/temporary URLs for private disks.

When replacing the old trait in an existing codebase, search for all references:

grep -R "Concerns\\\\Fileable" app config database routes resources tests

Update imports and use statements together. If this is a shared codebase, do the rename in one commit so model bootstrapping and relation definitions do not split across deployments.

Gotchas and Tips

• 0.3.0 is a breaking rename. \Astrotomic\Fileable\Concerns\Fileable is now \Astrotomic\Fileable\Concerns\HasFiles. Update every use import and trait usage. Run composer dump-autoload and clear cached config/route/bootstrap files after upgrading.

• HasFiles is a generic trait name. If your app or another package already defines HasFiles, alias it:

  use Astrotomic\Fileable\Concerns\HasFiles as FileableHasFiles;
  

• Check morph column types before adopting the package broadly. If your models use UUIDs/ULIDs, the package migration’s fileable_id type must match your primary keys.

• Deleting a model does not necessarily delete stored files. Add model events/observers or a scheduled cleanup to remove orphaned disk objects when file records are deleted.

• Do not expose private disks directly. Use temporary URLs or a controller download route with authorization.

• Validate uploads server-side: MIME type, extension, size, and image dimensions where relevant. Never trust the client filename; use generated storage names.

• If files appear attached to the wrong model, inspect the morph type/value in the files table and confirm the trait is on the expected model class.

• For debugging, inspect the SQL generated by the files relationship, confirm the configured disk exists in config/filesystems.php, and check storage/logs/laravel.log for storage exceptions.

• Publish config/migrations before production rollout and confirm the default disk is intentional. Local public disks are convenient for development but often wrong for private documents.

• The package relationship/query builder is the safest extension point. Avoid overriding the trait’s relation unless you have a clear migration path, because future package releases may change relation names or internals.