Files Laravel Package

Getting Started

This release (0.1.29) is a small but practical one: xlsx and zip are now accepted file types. If you were previously working around the package by base64-ing spreadsheets or storing archives outside the file table, that workaround can go away.

Minimal setup:

1. composer require escolalms/files
2. Publish and run the package assets:

   php artisan vendor:publish --provider="EscolaLMS\Files\Providers\FilesServiceProvider"
   php artisan migrate
   

3. Inspect config/files.php (or the package's config file name after publishing) for the allowed MIME/extension list, max upload size, and the storage disk. Confirm xlsx and zip are present after upgrading — if you have a published config from an older version, the config file is not re-published automatically, so you must merge the new entries yourself.
4. php artisan route:list --path=files to see the registered upload/download endpoints and their middleware.

Where to look first, in order: the config file (whitelist + disk), the File model and its relationships, the upload controller/request (to see how validation is actually applied), then the routes file.

First use case: upload a spreadsheet through the package endpoint, receive the file record/ID, and attach it to your domain model (e.g. an import job or a course resource) rather than handling UploadedFile yourself. That keeps disk configuration, naming, and cleanup consistent across the app.

Implementation Patterns

Upload-then-attach. Use the package endpoint to persist the file, then store the returned file identifier on your own model. This keeps you from re-implementing disk logic and means the package's cleanup/authorization rules apply uniformly. Wrap it in a FormRequest of your own so validation messages match the rest of your API.

Layered validation for the new types.

• xlsx: validate with mimes:xlsx and mimetypes:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet where possible. An xlsx is a ZIP container internally, so sniffing can legitimately report application/zip.
• zip: validate extension plus a size cap; there is no reliable content check beyond "is a valid archive".

Processing belongs in a job. For zip archives, do not extract inline in the request. Dispatch a queued job with ZipArchive, cap the number of entries and total uncompressed size, and write to a temp directory you clean up. For xlsx, queue the read (Laravel Excel / PhpSpreadsheet) and report results back through your normal notification channel.

Disk strategy. Keep one canonical disk for uploaded files and derive URLs from it. If you serve zip downloads, prefer streamed responses over loading into memory, and use temporary/signed URLs rather than exposing the storage path.

Testing. Use Storage::fake() and UploadedFile::fake()->create('import.xlsx', 100, 'application/vnd...sheet'). Fake files with a real MIME type are the only way to catch the xlsx/zip sniffing ambiguity in CI rather than in production.

Gotchas and Tips

• Published configs don't update. The most likely failure after 0.1.29 is a 422 on a perfectly valid .xlsx because your published whitelist predates the release. Diff the package config against yours on every upgrade.
• xlsx vs zip MIME collision. Because both types are supported in the same release, an overly broad mimetypes rule can let one through as the other. Decide explicitly whether you accept application/zip and, if so, only where archives are genuinely expected (e.g. a separate imports endpoint), not on avatar uploads.
• PHP limits, not package limits. upload_max_filesize and post_max_size silently truncate or reject before your validation runs. A zip that fails with an empty request body is almost always this, not the package.
• Zip bombs and path traversal. Never trust entry names; reject absolute paths and .., and enforce an uncompressed-size ceiling.
• Storage symlink. If the default disk is public, php artisan storage:link is a prerequisite that is easy to forget in fresh environments.
• Authorization is yours. The package handles storage, not tenancy. Check that a user may read a given file before handing out a URL — a predictable ID is not an access control mechanism.
• Extension points: model swapping and disk selection are typically done via config; if you need custom naming or post-upload hooks, prefer decorating the service/controller over forking. For behavior that config doesn't expose, open an issue — this package moves in small increments and 0.1.x means minor versions can still shift.
• Version pinning. Pin to ^0.1.29 and read the diff between patch releases; at 0.1.x, "support for xlsx and zip" arriving in a patch is normal, so treat each bump as potentially behavior-changing for validation.