Storage Laravel Package

Getting Started

• Check fit before installing. This package is archived, last released 2018-09-29, and targets Laravel 5. Treat it as inherited-code maintenance, not a new dependency. Confirm composer.json constraints against your PHP/Laravel version before running composer require alt-three/storage.
• Register the provider. Add AltThree\Storage\StorageServiceProvider::class to config/app.php (Laravel 5 style). If the package ships a config file, publish it with php artisan vendor:publish --provider="AltThree\Storage\StorageServiceProvider".
• Set prerequisites. Ensure APP_KEY is set and stable, the configured filesystem disk is writable, and the configured cache store is reachable. The package’s “secure” guarantee depends entirely on Laravel’s encrypter and your key.
• Read these first: src/StorageServiceProvider.php (bindings/config), the storage contract/implementation under src/, and any config/storage.php. The public surface is small, so inspect the source rather than assuming modern Laravel Storage semantics.
• First use case: store a small secret (API token, OAuth credential, per-tenant config blob) through the package, read it back, then verify the raw file on disk is ciphertext. This validates the disk, key, and cache path in one pass.

Implementation Patterns

• Inject the contract, not the facade. Type-hint the package’s storage interface in constructors. This keeps your services testable and makes it possible to swap the implementation later without touching call sites.
• Wrap it in your own repository. Expose domain methods like storeProviderToken() / getProviderToken() around the package’s get/put/forget surface. When you eventually replace the archived package with native Crypt + Storage + Cache, only the wrapper changes.
• Use read-through caching deliberately. The package pairs encrypted storage with a cache layer. On writes, update or invalidate the cached plaintext; on deletes, clear both cache and disk. Do not rely on cache TTL alone for correctness.
• Namespace every key. Prefix keys with environment, tenant, and purpose (prod:tenant:42:stripe_token) so cache entries and files cannot collide across contexts. The package likely does not enforce a key schema for you.
• Keep payloads small. This is suited to credentials and config blobs, not uploads or large documents. Encryption/decryption and cache serialization are memory-bound, and there is no streaming path.
• Configure per environment. Local: local disk + array/file cache. Production: durable disk + shared cache (Redis/Memcached). Queue workers and web nodes must share the same cache store, or reads will diverge.
• Test with fakes. Point the package at a temporary disk and an in-memory cache in tests. Assert that the persisted bytes differ from plaintext and that a cache clear still allows a decrypt-and-read from disk.
• Bind swaps in a service provider. If you need a different disk or cache store for a subset of secrets, bind a configured instance or decorate the contract rather than editing vendor config at runtime.

Gotchas and Tips

• Archived and Laravel-5-only. There is no Laravel 6+ support, no dependents, and no maintenance. Expect friction with newer framework versions, deferred provider changes, and encryption format assumptions. Do not build new features on it.
• APP_KEY rotation breaks reads. Old ciphertext becomes undecryptable. Plan a re-encryption migration before rotating keys; the package almost certainly provides no re-encryption tooling.
• The cache holds plaintext. “Cached secure storage” means decrypted values may sit in Redis/Memcached/file cache. Secure the cache store (auth, network isolation, TTLs) as seriously as the filesystem.
• Cache and disk can drift. If someone clears the cache, reads should fall back to disk; if someone deletes a file directly, the cache may still serve stale plaintext. Always mutate through the package’s API.
• Per-node cache stores cause inconsistency. File cache on multiple app servers means one node may not see another’s write. Use a shared cache store in any multi-node deployment.
• Handle DecryptException explicitly. Corrupt files, wrong keys, or manually edited files will throw. Catch at the repository boundary and return a domain-level “credential unavailable” result rather than a 500.
• Check disk paths and permissions. A writable-looking storage/app can still fail under different users (web vs. queue worker). Verify with the same OS user that runs the app.
• Race conditions are yours to solve. Concurrent read-miss/write can cause cache stampedes or last-writer-wins. Use atomic cache operations or a lock around writes if correctness matters.
• Debugging checklist: confirm the provider is registered, confirm the resolved disk/cache from the container, run php artisan cache:clear, inspect the raw file on disk, and log the key prefix. Most failures are config/key mismatches, not package bugs.
• Extension point: decorate the storage contract with your own class that adds metrics, key validation, or fallback reads. This is the cleanest way to add behavior without forking an archived package.
• Modern replacement is straightforward: Laravel’s Crypt::encryptString() / decryptString() plus Storage::put() and Cache::remember() reproduces the same pattern with maintained framework code. Migrate when touching this area.