Storage Laravel Package

Getting Started

The package is a read-only subtree split of the Storage component bundled inside Superdesk Web Publisher (SWP). It is not a Laravel package — it is a Symfony-oriented PHP component. Treat it as a library of storage abstractions, not a full storage solution.

Minimal steps:

1. Install via Composer (composer require swp/storage). Because the split mirrors the monorepo, pin the version and commit the lockfile; the split sees few releases (last tagged 2018), so expect to track the upstream SuperdeskWebPublisher/storage repo for anything newer.
2. Look first at the src/ tree and locate the core contract (the StorageInterface/adapter abstraction) and the concrete adapters shipped alongside it (typically a local-filesystem adapter plus an object-store adapter such as S3, often wrapping Flysystem).
3. Identify the composer.json requirements to see which Symfony/PSR/Flysystem versions are expected. This immediately tells you whether it will slot into a modern Laravel app unmodified or need forking.
4. First use case: instantiate a local adapter pointed at a writable directory and exercise the basic read/write/exists/remove cycle. This is the smallest loop that proves the abstraction works in your environment before wiring it to a container or a remote bucket.

If you are on Laravel, budget time for the first step being evaluation rather than integration — the component predates and does not target the Laravel ecosystem.

Implementation Patterns

• Adapter-first design. The component's value is the storage contract: your application code depends on the interface, and you swap concrete adapters (local, S3, in-memory for tests) behind it. Keep your own thin wrapper/service around it so the rest of your app never imports SWP types directly.
• Path resolution as a separate concern. SWP separates "where does this asset go" from "how do I write bytes." Reuse that pattern: inject a path/URI resolver that produces deterministic keys (tenant/date/hash prefixes) instead of letting callers build strings ad hoc. This is the single most portable idea in the package.
• Container wiring via a service provider or config. The package is built for Symfony's DI. In Laravel, register the adapter as a singleton in a service provider, bind it to an interface, and resolve configuration (bucket, region, base path, credentials) from config/filesystems.php-style config rather than environment lookups scattered in code.
• Compose with Flysystem if present. If the adapter layers on Flysystem, you inherit its drivers and test doubles. Check the composer.json for Flysystem and align your app's version — this is the most likely integration friction point.
• Testing pattern. Because the abstraction is interface-driven, bind an in-memory or temp-directory adapter in tests and assert on the contract (write→exists→read→remove), not on file paths. Reserve a single integration test per real adapter.
• Streams over strings. Storage components of this era generally prefer PSR-7 streams or resource handles for large media. Keep the stream/handle semantics end-to-end rather than reading whole files into memory.

Gotchas and Tips

• License is AGPL-3.0. This is the biggest day-to-day risk. AGPL is copyleft with a network-use clause; embedding it in a hosted product can create source-disclosure obligations. Get legal sign-off or isolate/replace the component before shipping. For many teams this alone rules it out.
• It is a subtree split. Do not open PRs against the split; contribute to SuperdeskWebPublisher/storage upstream. The split can lag or diverge, and issue trackers on the split are typically dead.
• Staleness. Last release 2018 and 1 star / 0 dependents means: no security updates, no PHP 8.x / modern framework guarantees, and dependency constraints likely conflict with current Symfony/Flysystem versions. Vendor or fork it, and treat composer update as something you control manually.
• Symfony assumptions leak. Service definitions, event/kernel assumptions, and config conventions may assume Symfony's container and directory layout. Expect to write glue code (providers, config translation) in Laravel rather than getting a drop-in facade.
• Debugging paths. Most failures are configuration, not logic: wrong base directory, missing write permissions, credential/region mismatch for object stores, or a path resolver producing keys with leading slashes or double separators. Log the fully resolved key before the adapter call — that isolates resolver bugs from driver bugs.
• Extension points to use. Prefer subclassing/implementing the adapter interface over patching internals; wrap the storage contract in your own application-level repository so an upstream change or a future replacement (e.g., Laravel's native Flysystem integration) is a one-file swap.
• Don't rely on it for concurrency or metadata. Components of this vintage usually provide simple CRUD over blobs. Atomicity, deduplication, image processing, and metadata search belong elsewhere — keep those concerns out of the storage layer.

Bottom line: the reusable ideas are the interface-first adapter design and the decoupled path resolver. The package itself is stale, AGPL, single-maintainer, and not Laravel-native — so adopt the pattern, and only adopt the code if you are already inside the SWP ecosystem or willing to vendory/fork and accept the licensing and maintenance burden.