Core Laravel Package

Getting Started

UniFileManager/core is early-stage (v0.1.x) — expect the API surface to move. Start by reading the README and the config/unifilemanager.php file rather than the source; the config exposes the storage driver selection, which is the first thing you'll touch.

Minimal setup:

1. composer require unifilemanager/core
2. Publish the config: php artisan vendor:publish --tag=unifilemanager-config
3. Add credentials to config/filesystems.php (or the package config, depending on driver) — as of v0.1.4, Kamalia object storage is now a supported listing backend, so you can point the package at a Kamalia bucket alongside the existing S3/local drivers.
4. First use case: listing and iterating stored objects. Use the package's manager facade (resolve via the container) rather than touching the driver directly, so you stay decoupled from whichever adapter you've configured.

If you're on v0.1.3 or earlier and using Kamalia, you were previously limited — v0.1.4 is the release that makes Kamalia object listing a first-class path.

Implementation Patterns

Resolve, don't instantiate. Bind the manager through the container or facade so swapping drivers per-environment stays a config change. This matters more here than in mature packages because adapter coverage is still growing (Kamalia just landed).

Listing objects:

• Use the listing abstraction, then paginate at the package layer rather than looping raw driver calls. Object stores return paginated/marker-based results, and the package is designed to normalize that.
• For large buckets, stream results and process incrementally — don't ->all() into memory.
• Pair listing with a local cache (e.g. Cache::remember with a short TTL) if you're rendering file pickers; object store list calls are the slow part of any UI.

Per-environment driver config:

// config/unifilemanager.php
'driver' => env('UNIFILE_DRIVER', 'local'),

Keep Kamalia credentials (endpoint, key, secret, bucket/container) in env() and mirror them in config/filesystems.php if the package delegates to Laravel's filesystem layer — that way Storage::disk('kamalia') and the package stay consistent.

Service-layer pattern. Wrap listing/copy/move operations in your own FileRepository so the day a v0.2 changes a method signature, you patch one class instead of 30 call sites. In a 0.1.x package this is not optional.

Queued jobs for bulk operations. Any copy/delete/migrate across buckets should go through a job with tries and backoff; object stores rate-limit and transiently 5xx.

Integration tip: version-pin with "unifilemanager/core": "~0.1.4" — tilde, not caret, until the package reaches 1.0. Test upgrades in staging against a real bucket.

Gotchas and Tips

• Version pinning is critical. 0.1.x releases carry no BC promise. v0.1.4 is a feature release (Kamalia listing) with no documented breaking changes, but the changelog is thin — read the diff on PR #1 before upgrading if you depend on the listing API.
• Kamalia is brand new. It arrived as a first contribution in v0.1.4. Treat listing semantics (ordering, pagination tokens, consistency) as unproven: verify whether listings are strongly or eventually consistent and whether delimiter/prefix filtering behaves like S3. Write an integration test against a real bucket before relying on it in production.
• Thin changelog / single-maintainer risk. Release notes are auto-generated PR titles; there is no upgrade guide. Read tags yourself, and watch for follow-up patches to the Kamalia adapter.
• Driver parity. Don't assume a method that works on local works on Kamalia or S3. Guard feature use behind a capability check or a try/catch around UnsupportedOperation-style exceptions.
• Debugging listing issues: dump the raw driver response before the package normalizes it. If results come back empty, the usual culprits are region/endpoint mismatch, bucket name vs. container name, path-style vs. virtual-hosted addressing, and missing list permissions (distinct from read permissions).
• Config cache: after changing driver or credentials, run php artisan config:clear — config:cache in production will happily serve stale credentials.
• Extension point: the driver registration/binding in the service provider is where you'd add your own adapter if you need a storage backend the package doesn't cover yet; that's cheaper than forking.
• Early-adopter framing: budget for churn. Keep the package behind your repository abstraction and cover your critical paths with tests so a 0.1.5 patch can't silently break uploads or listings.