Starter Kit Laravel Package

Product Decisions This Supports

• "Ship on Laravel Cloud now vs. build our own storage layer" — v0.2.4 removes the single biggest infrastructure blocker for a listing/marketplace MVP: product images no longer have to live on one app server's local disk. That is the difference between a demo and something that survives a restart, a second instance, or an autoscale event.
• Build vs. buy on the media path — the package now hands you a pluggable disk (LARASELL_IMAGES_DISK) and the S3 adapter (league/flysystem-aws-s3-v3). Buy the plumbing, build the product-differentiating parts: image variants/thumbnails, moderation, CDN policy, per-tenant buckets, retention.
• Roadmap unblocks — horizontal scaling, CDN offload for image-heavy listing pages, and dev/prod parity (local disk in dev, bucket in staging/prod) move from "custom work" to "configuration." Sequence them right after this release rather than before.
• Cheap validation option — because this is a config-level change, a bucket-backed image spike is a one-day experiment, not a sprint. Use it to pressure-test the kit as our foundation before committing.
• Scope items this release does not cover, which we still own — resize/transform pipeline, signed vs. public URL policy, GDPR/right-to-erasure image deletion, orphaned-object cleanup, per-tenant isolation. Budget these explicitly; do not let "S3 is supported" read as "media is done."
• Version/dependency governance — a feature landing in a 0.2.4 patch on a pre-1.0 package is a signal about change velocity. Decide now whether we pin exact versions and upgrade deliberately, and who owns that.

When to Consider This Package

Adopt when:

• You're building a Laravel product-listing/marketplace app and want a head start on scaffolding instead of greenfield.
• You deploy to Laravel Cloud, containers, or any autoscaled/ephemeral-filesystem environment where local disk will not persist.
• You want an S3-compatible bucket (AWS S3, R2, Spaces, MinIO) — but validate your specific provider in a spike; the AWS SDK path works with most S3-compatible endpoints, not all.
• Your team is Laravel-fluent and willing to treat a pre-1.0 starter kit as readable source to fork or steer, not a black box with a vendor SLA.

Look elsewhere when:

• You need a mature, versioned commerce platform with support commitments — this is a starter kit at 0.2.x.
• You need a media pipeline out of the box (resizing, responsive variants, on-the-fly transforms, CDN invalidation). This release gives you a disk, not a pipeline.
• You need multiple buckets, multiple regions, or per-tenant buckets: a single LARASELL_IMAGES_DISK env var is a deliberate simplification you will outgrow quickly.
• You can't absorb pre-1.0 breaking changes, or you're not on Laravel/Laravel Cloud.
• You have documented compliance/certification requirements (data residency, audit trails) that this package doesn't speak to.

How to Pitch It (Stakeholders)

Executives (30 seconds): The starter kit we're evaluating just cleared its main production blocker — seller product images can now be stored in managed object storage instead of a single server's disk. That's what makes a cloud, multi-instance deployment viable without custom engineering. The cost is a configuration change and a bucket, not weeks of work. The caveat is maturity: this is a pre-1.0 package, so we pin versions and keep the exit path cheap.

Engineering (actionable):

• v0.2.4 adds league/flysystem-aws-s3-v3; Laravel Cloud requires it once a bucket is attached. Set LARASELL_IMAGES_DISK to the bucket's disk per environment.
• Provision the bucket with least-privilege IAM (Put/Get/Delete scoped to a prefix), add the env var to local/staging/prod config and CI secrets, and smoke-test from a fresh ephemeral instance — not just locally.
• Confirm URL strategy (public objects vs. signed URLs) before listings go live; verify image deletion and orphan cleanup, which the package does not handle.
• Treat the image pipeline (resize/variants) as separate work; this release does not provide it.
• Pin the version, and re-evaluate on each 0.x release for breaking changes to the images disk contract.