PHPackages websolutionfalcon/laravel-simple-cold-storage - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [File & Storage](/categories/file-storage) 4. / 5. websolutionfalcon/laravel-simple-cold-storage ActiveLibrary[File & Storage](/categories/file-storage) websolutionfalcon/laravel-simple-cold-storage ============================================= A simple, extensible Laravel package for storing data using filesystem with type-safe StorageKey DTOs v2.0.0(2mo ago)5895↓35.8%MITPHPPHP ^8.1 Since Jan 22Pushed 2mo agoCompare [ Source](https://github.com/websolutionfalcon/laravel-simple-cold-storage)[ Packagist](https://packagist.org/packages/websolutionfalcon/laravel-simple-cold-storage)[ Docs](https://github.com/websolutionfalcon/laravel-simple-cold-storage)[ RSS](/packages/websolutionfalcon-laravel-simple-cold-storage/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (14)Versions (3)Used By (0) Laravel Simple Cold Storage =========================== [](#laravel-simple-cold-storage) [![Latest Version on Packagist](https://camo.githubusercontent.com/069258a2488ef1eb76e07cd53e228cc48bce940ddc2ad0c922982be8ed1129a5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f776562736f6c7574696f6e66616c636f6e2f6c61726176656c2d73696d706c652d636f6c642d73746f726167652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/websolutionfalcon/laravel-simple-cold-storage)[![Total Downloads](https://camo.githubusercontent.com/3aea865b6301fc4b2d0ba0fabcfc2f35f08b0a8a18b516a8ada415ea4f66c324/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f776562736f6c7574696f6e66616c636f6e2f6c61726176656c2d73696d706c652d636f6c642d73746f726167652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/websolutionfalcon/laravel-simple-cold-storage)[![GitHub Actions](https://github.com/websolutionfalcon/laravel-simple-cold-storage/actions/workflows/main.yml/badge.svg)](https://github.com/websolutionfalcon/laravel-simple-cold-storage/actions/workflows/main.yml/badge.svg) A simple, extensible Laravel package for storing data to the local filesystem using a clean, type-safe API with StorageKey DTOs. Features -------- [](#features) - **Dead simple**: One main class, minimal configuration - **Easily extensible**: Create custom encoders and storage implementations - **Type-safe API**: Modern PHP 8.2+ with readonly properties - **StorageKey DTO**: Powered by Spatie Laravel Data with validation attributes - **Laravel Storage**: Works with any Laravel filesystem disk (local, s3, ftp, etc.) - **Configurable prefix**: Customize storage paths - **JSON encoding**: Built-in JSON encoder, add your own encoders easily Installation ------------ [](#installation) ``` composer require websolutionfalcon/laravel-simple-cold-storage ``` Publish the configuration file (optional): ``` php artisan vendor:publish --provider="Websolutionfalcon\LaravelSimpleColdStorage\LaravelSimpleColdStorageServiceProvider" --tag="config" ``` Quick Start ----------- [](#quick-start) ``` use Websolutionfalcon\LaravelSimpleColdStorage\DTOs\StorageKey; use Websolutionfalcon\LaravelSimpleColdStorage\Facades\LaravelSimpleColdStorage; // Create a storage key $key = new StorageKey('orders', '12345', 'archived'); // Store data LaravelSimpleColdStorage::store(['order_id' => 12345, 'total' => 99.99], $key); // Retrieve data $data = LaravelSimpleColdStorage::retrieve($key); // Check existence if (LaravelSimpleColdStorage::exists($key)) { // Data exists } // Delete data LaravelSimpleColdStorage::delete($key); ``` Configuration ------------- [](#configuration) `config/laravel-simple-cold-storage.php`: ``` return [ // Storage implementation class 'storage' => \Websolutionfalcon\LaravelSimpleColdStorage\ColdStorage::class, // Settings passed to the storage implementation 'settings' => [ 'disk' => env('COLD_STORAGE_DISK', 'local'), 'prefix' => env('COLD_STORAGE_PREFIX', 'cold-storage'), ], // Encoder implementation class 'encoder' => \Websolutionfalcon\LaravelSimpleColdStorage\Encoders\JsonEncoder::class, ]; ``` The package uses Laravel's Storage facade, so you can use **any disk** configured in `config/filesystems.php`: - `local` - Local filesystem (default) - `s3` - Amazon S3 - `ftp` - FTP server - `sftp` - SFTP server - Or any custom disk you configure Files are stored at: `{disk}/{prefix}/{type}/{identifier}[.{variant}].json` Using Different Storage Disks ----------------------------- [](#using-different-storage-disks) Simply change the disk in your config or `.env`: ``` # Use S3 COLD_STORAGE_DISK=s3 # Use local (default) COLD_STORAGE_DISK=local # Use a custom disk COLD_STORAGE_DISK=my_custom_disk # Customize the path prefix COLD_STORAGE_PREFIX=archives ``` Files will be stored at: `{disk}/{prefix}/{type}/{identifier}[.{variant}].json` Example: - Disk: `s3`, Prefix: `archives` → `s3://bucket/archives/orders/12345.json` - Disk: `local`, Prefix: `cold-storage` → `storage/app/cold-storage/orders/12345.json` Extending with Custom Encoders ------------------------------ [](#extending-with-custom-encoders) ### 1. Create Your Encoder [](#1-create-your-encoder) Create a custom encoder in your Laravel application: ``` // app/ColdStorage/Encoders/MsgPackEncoder.php namespace App\ColdStorage\Encoders; use Websolutionfalcon\LaravelSimpleColdStorage\Contracts\EncoderInterface; use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\EncodingException; class MsgPackEncoder implements EncoderInterface { public function encode(mixed $data): string { try { return msgpack_pack($data); } catch (\Exception $e) { throw new EncodingException('Failed to encode: ' . $e->getMessage(), 0, $e); } } public function decode(string $data): mixed { try { return msgpack_unpack($data); } catch (\Exception $e) { throw new EncodingException('Failed to decode: ' . $e->getMessage(), 0, $e); } } public function getContentType(): string { return 'application/msgpack'; } public function getFileExtension(): string { return 'msgpack'; // Files will have .msgpack extension } } ``` ### 2. Configure Your Encoder [](#2-configure-your-encoder) Update your published config file: ``` // config/laravel-simple-cold-storage.php return [ 'encoder' => \App\ColdStorage\Encoders\MsgPackEncoder::class, // ... rest of config ]; ``` That's it! The package will now use your custom encoder. Extending with Custom Storage ----------------------------- [](#extending-with-custom-storage) ### Example: MySQL Storage [](#example-mysql-storage) Create a custom storage implementation for MySQL: ``` // app/ColdStorage/MySqlColdStorage.php namespace App\ColdStorage; use Illuminate\Support\Facades\DB; use Websolutionfalcon\LaravelSimpleColdStorage\Contracts\ColdStorageInterface; use Websolutionfalcon\LaravelSimpleColdStorage\Contracts\EncoderInterface; use Websolutionfalcon\LaravelSimpleColdStorage\DTOs\StorageKey; use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\StorageNotFoundException; class MySqlColdStorage implements ColdStorageInterface { public function __construct( protected EncoderInterface $encoder, protected string $table = 'cold_storage', protected ?string $connection = null ) {} public static function fromSettings(EncoderInterface $encoder, array $settings): static { return new static( encoder: $encoder, table: $settings['table'] ?? 'cold_storage', connection: $settings['connection'] ?? null ); } public function store(mixed $data, StorageKey $key): void { $encoded = $this->encoder->encode($data); DB::connection($this->connection)->table($this->table)->updateOrInsert( [ 'type' => $key->type, 'identifier' => $key->identifier, 'variant' => $key->variant, ], [ 'data' => $encoded, 'updated_at' => now(), 'created_at' => now(), ] ); } public function retrieve(StorageKey $key): mixed { $record = DB::connection($this->connection) ->table($this->table) ->where('type', $key->type) ->where('identifier', $key->identifier) ->where('variant', $key->variant) ->first(); if (!$record) { throw new StorageNotFoundException("Not found: {$key}"); } return $this->encoder->decode($record->data); } public function delete(StorageKey $key): bool { return DB::connection($this->connection) ->table($this->table) ->where('type', $key->type) ->where('identifier', $key->identifier) ->where('variant', $key->variant) ->delete() > 0; } public function exists(StorageKey $key): bool { return DB::connection($this->connection) ->table($this->table) ->where('type', $key->type) ->where('identifier', $key->identifier) ->where('variant', $key->variant) ->exists(); } } ``` ### Configure Your Custom Storage [](#configure-your-custom-storage) Just update the config: ``` // config/laravel-simple-cold-storage.php return [ 'storage' => \App\ColdStorage\MySqlColdStorage::class, 'settings' => [ 'table' => 'cold_storage', 'connection' => null, // Or 'mysql', 'pgsql', etc. ], 'encoder' => \Websolutionfalcon\LaravelSimpleColdStorage\Encoders\JsonEncoder::class, ]; ``` The `fromSettings()` method lets each storage implementation define its own configuration needs! Use Cases --------- [](#use-cases) ### Archive Old Data [](#archive-old-data) ``` $oldOrders = Order::where('created_at', 'encoder->encode($data); DB::connection($this->connection)->table($this->basePath)->updateOrInsert( [ 'type' => $key->type, 'identifier' => $key->identifier, 'variant' => $key->variant, ], [ 'data' => $encoded, 'updated_at' => now(), 'created_at' => now(), ] ); } public function retrieve(StorageKey $key): mixed { $record = DB::connection($this->connection) ->table($this->basePath) ->where('type', $key->type) ->where('identifier', $key->identifier) ->where('variant', $key->variant) ->first(); if (!$record) { throw new StorageNotFoundException("Not found: {$key}"); } return $this->encoder->decode($record->data); } public function delete(StorageKey $key): bool { return DB::connection($this->connection) ->table($this->basePath) ->where('type', $key->type) ->where('identifier', $key->identifier) ->where('variant', $key->variant) ->delete() > 0; } public function exists(StorageKey $key): bool { return DB::connection($this->connection) ->table($this->basePath) ->where('type', $key->type) ->where('identifier', $key->identifier) ->where('variant', $key->variant) ->exists(); } } ``` Then configure it: ``` // config/laravel-simple-cold-storage.php return [ 'base_path' => 'cold_storage', // table name 'storage' => \App\ColdStorage\Storages\MySqlColdStorage::class, ]; ``` Testing ------- [](#testing) Run the package tests: ``` composer test ``` Run with coverage: ``` composer test-coverage ``` Architecture ------------ [](#architecture) The package provides: - **Contracts**: `ColdStorageInterface`, `EncoderInterface` - **Default Storage**: `ColdStorage` (local filesystem) - **Default Encoder**: `JsonEncoder` - **DTO**: `StorageKey` for type-safe keys - **Exceptions**: Custom exceptions for error handling You extend by: 1. **Create** a class implementing `ColdStorageInterface` or `EncoderInterface` 2. **Configure** it in `config/laravel-simple-cold-storage.php` 3. **Done** - the package will use your implementation Error Handling -------------- [](#error-handling) ``` use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\StorageNotFoundException; use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\EncodingException; use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\InvalidStorageKeyException; try { $data = LaravelSimpleColdStorage::retrieve($key); } catch (StorageNotFoundException $e) { // Data not found } catch (EncodingException $e) { // Encoding/decoding failed } catch (InvalidStorageKeyException $e) { // Invalid key format } ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for recent changes. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security -------- [](#security) If you discover any security issues, please email . Credits ------- [](#credits) - [Slava Mehovich](https://github.com/websolutionfalcon) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 42 — FairBetter than 90% of packages Maintenance84 Actively maintained with recent releases Popularity24 Limited adoption so far Community6 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~35 days Total 2 Last Release 80d ago Major Versions v1.0.0 → v2.0.02026-02-27 ### Community Maintainers ![](https://www.gravatar.com/avatar/c589ca027a01e0e24e031071223eea48e523d51550c9de66c1a58496468bfb81?d=identicon)[websolutionfalcon](/maintainers/websolutionfalcon) --- Top Contributors [![websolutionfalcon](https://avatars.githubusercontent.com/u/17783011?v=4)](https://github.com/websolutionfalcon "websolutionfalcon (18 commits)") --- Tags filesystemlaravelarchivestoragedtocold-storagespatie-data ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/websolutionfalcon-laravel-simple-cold-storage/health.svg) ``` [![Health](https://phpackages.com/badges/websolutionfalcon-laravel-simple-cold-storage/health.svg)](https://phpackages.com/packages/websolutionfalcon-laravel-simple-cold-storage) ``` ### Alternatives [sausin/laravel-ovh OVH Object Storage driver for laravel 40153.5k](/packages/sausin-laravel-ovh)[gliterd/laravel-backblaze-b2 Backblaze B2 Cloud Storage for Laravel 5 5341.6k](/packages/gliterd-laravel-backblaze-b2)[zing/laravel-flysystem-obs Flysystem Adapter for OBS 1211.2k](/packages/zing-laravel-flysystem-obs)[innoge/laravel-rclone A sleek PHP wrapper around rclone with Laravel-style fluent API syntax 174.1k](/packages/innoge-laravel-rclone) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)