Starter Kit Laravel Package

Getting Started

This is a starter kit, not a drop-in library — the normal path is scaffolding a fresh app from it rather than composer require-ing it into an existing codebase. Start there, then read the image-handling path before anything else, since that is what v0.2.4 changes.

1. Scaffold and boot

   composer create-project larasell-dev/starter-kit my-app
   cd my-app && cp .env.example .env && php artisan key:generate
   php artisan migrate --seed
   npm install && npm run dev
   

2. Look first at: config/filesystems.php (the available disks), then wherever LARASELL_IMAGES_DISK is read — typically config/larasell.php or an inline env() in a service provider. That single config value is the seam the whole image feature pivots on.
3. Confirm the default: out of the box the kit points at the public disk, so product images land in storage/app/public behind php artisan storage:link.
4. First use case: create a product with an image in the admin UI, verify it renders locally, then flip LARASELL_IMAGES_DISK to an S3 disk and repeat. That round trip exercises the only meaningful configuration surface this release touches.

Implementation Patterns

Disk indirection, not hardcoded disks. The value of LARASELL_IMAGES_DISK is that application code never names a disk directly. Follow that convention in your own additions:

$disk = Storage::disk(config('larasell.images_disk'));

$path = $request->file('image')->store('products', $disk->getName());

Store paths, resolve URLs at render time. Persist the relative path (products/abc.jpg) and call $disk->url($path) or $disk->temporaryUrl($path, now()->addHour()) in the view. This is what makes the local→S3 switch a config change instead of a data migration.

Environment matrix. Keep local and production deliberately different, and let the env var carry the difference:

# local
LARASELL_IMAGES_DISK=public

# production
LARASELL_IMAGES_DISK=s3
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=eu-west-1
AWS_BUCKET=my-app-images
AWS_URL=https://cdn.example.com   # optional, for CDN-fronted buckets

Laravel Cloud deployments. v0.2.4 bundles league/flysystem-aws-s3-v3, which Laravel Cloud requires the moment a bucket is attached to the environment. Before this release you had to add that adapter yourself; on a fresh scaffold it is now present. The workflow is: attach the bucket in the Cloud dashboard, set LARASELL_IMAGES_DISK to the disk that bucket maps to, and let Cloud inject the credentials.

Tests. Never let the suite touch a real bucket:

Storage::fake('s3');

Fake whichever disk name config('larasell.images_disk') resolves to in your phpunit.xml environment — set that env var to s3 in the test config so tests and production exercise the same code path.

Multi-disk / per-tenant setups. Because the disk is resolved through config, you can swap it at runtime for tenant-specific buckets by rebinding the config value in a middleware or service provider before the request hits the controller. Nothing in the image pipeline needs to change.

Gotchas and Tips

• The env var takes a disk name, not a driver. LARASELL_IMAGES_DISK=s3 only works because a disk literally named s3 exists in config/filesystems.php. If your Cloud bucket is wired to a disk called bucket or images, use that name. Setting it to a driver string that has no matching disk entry is the most common failure here, and it surfaces as a InvalidArgumentException: Disk [...] does not have a configured driver deep in the upload path.
• config:cache will bite you. If you change LARASELL_IMAGES_DISK on a server running cached config, nothing happens until php artisan config:clear / config:cache. Local .env edits are invisible for the same reason.
• Public vs private visibility. S3 buckets are private by default, so Storage::url() returns an unsigned URL that 403s. Either set the disk's visibility to public in config/filesystems.php, or switch the views to temporaryUrl() — the latter is the safer default and worth doing before you migrate production images.
• Existing images do not migrate themselves. Flipping the env var points new uploads at the new disk but leaves old rows pointing at paths that only exist on the old one. Copy the products/ prefix across (aws s3 sync storage/app/public/products s3://bucket/products) before cutting over.
• Bucket policy and CORS. Browser-direct uploads (if you use them) need a CORS rule on the bucket; server-side uploads through the kit do not. Symptom of a missing CORS rule is a preflight failure in the console, not a Laravel exception — check the network tab before diving into the PHP.
• Upgrading an existing scaffold. Since this is a starter kit, composer update alone will not bring in the new release cleanly if you have diverged. Diff composer.json and config/filesystems.php against the tag, and confirm league/flysystem-aws-s3-v3 is in require — that is the only hard dependency change in v0.2.4.
• Extension point: everything disk-related funnels through the one config key. If you need per-model or per-collection disks later, introduce a small resolver class reading config('larasell.images_disk') as its default rather than scattering env() calls — keeps the future swap cheap.