Lincable Laravel Package

Getting Started

Start by mapping the package's four entry points before writing any application code:

1. Service provider and facade/helpers — check config/app.php auto-discovery and the package's src/ for the public API surface (upload, link, URL resolution).
2. Published config and migrations — run php artisan vendor:publish --tag=... for the config, then php artisan migrate. Confirm which tables store file metadata versus the polymorphic link between a file and its owning model.
3. The model trait or relationship — add it to the Eloquent models that can own files, then verify the inverse relation from the file record back to its owner.
4. Storage wiring — ensure php artisan storage:link has run and the configured disk matches your app's filesystems.php (local for private, S3/public for served assets).

First use case: upload a file through a controller, link it to a model, and render its URL in a Blade view. This exercises storage, the database link, and URL resolution in one pass — the three things most likely to be misconfigured.

Look first at the upgrade from v1.0.2 if you re-link files between models. That release fixed a bug where linking a file to a new model overwrote the old model's URL. If your code stores or caches URLs on the model, re-test that flow after upgrading.

Implementation Patterns

Attach on create, link on update. Upload the file first (getting a file record), then link it to the model in the same request. Keep the upload and the link as separate steps so you can retry linking without re-uploading, and so orphaned uploads are visible in the files table.

Treat the link as the source of truth, not the URL. Resolve URLs at render time from the file record plus the configured disk, rather than persisting absolute URLs in your own columns. This keeps you compatible with disk changes, CDN swaps, and signed/temporary URL strategies.

Re-linking is a first-class workflow. Moving a file from a draft model to a published one, reassigning an attachment to the correct record, or sharing a single file across models should all go through the package's link method. After v1.0.2, verify both sides: the new owner resolves the URL correctly, and the previous owner still resolves the URL it had before the re-link.

Use polymorphic ownership deliberately. When a file can belong to several model types, constrain queries by fileable_type in addition to ID, and eager-load the relation (with('files')) on index pages to avoid N+1 queries on URL generation.

Wrap multi-step operations in transactions. Upload → link → update model state should be atomic where the database is concerned; if the link fails, the file record should be cleaned up or left clearly orphaned for a pruning command.

Schedule cleanup. Add a scheduled command or job that removes file records with no owner and no recent activity, and deletes the corresponding storage objects. Pair it with a soft-delete strategy if downstream records reference the files.

Gotchas and Tips

The v1.0.2 bug is a signal about shared file records. The fix preserves the old model's URL when a file is linked to another model. If you maintain your own URL column alongside the package, audit any code that writes to it on link — you may be reintroducing the same clobbering behavior outside the package.

URLs are context-dependent. If your accessor derives the URL from the owning model (tenant subdomain, locale prefix, signed route), caching a single URL on the file record will be wrong for the second owner. Cache per owner, or don't cache.

Config and cache. After publishing or editing the package config, run php artisan config:clear. In production, remember config:cache freezes config at deploy time — a disk or URL change needs a redeploy, not just a file edit.

Storage link and disk mismatch. A resolved URL that 404s is almost always a missing storage:link, a disk whose url config doesn't match APP_URL, or a private disk being served as public. Check the disk definition before debugging the package.

Temporary and signed URLs expire. If you hand URLs to a frontend SPA or mobile client, generate them close to use and avoid persisting them in caches with long TTLs.

Mass assignment and guarded attributes. Don't expose the link/URL attributes to $request->all() fills. Link explicitly through the package API so validation and authorization hooks run.

Debugging checklist for link failures: confirm the trait is on the model, the migration ran, the morph map (if used) includes the model's alias, the file record isn't already exclusively attached, and the storage disk is writable. Log the file ID and both model IDs around the link call — the failure mode in v1.0.1 was silent overwriting, so assert on the old owner's URL in a regression test.

Extension points. Prefer the package's events (if any) or a model observer over forking the link logic; the v1.0.2 fix touched internal behavior that an override would have missed. If you need custom URL generation, bind your own resolver in a service provider rather than patching the vendor tree.