Laravel Simple Cold Storage

https://github.com/websolutionfalcon/laravel-simple-cold-storage
Admin
A simple, extensible Laravel package for storing data to the local filesystem or any...
Tokens:10,197
Snippets:56
Trust Score:3.7
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install Laravel Simple Cold Storage

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

Instructions for installing the package via Composer and optionally publishing the configuration file. This is the first step to using the package's features.

```bash
# Install the package
composer require websolutionfalcon/laravel-simple-cold-storage

# Publish configuration (optional)
php artisan vendor:publish --provider="Websolutionfalcon\LaravelSimpleColdStorage\LaravelSimpleColdStorageServiceProvider" --tag="config"
```

--------------------------------

### Install Laravel Simple Cold Storage

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

Installs the 'websolutionfalcon/laravel-simple-cold-storage' package using Composer. This is the first step to integrating the cold storage functionality into your Laravel project.

```bash
composer require websolutionfalcon/laravel-simple-cold-storage
```

--------------------------------

### Quick Start: Basic Cold Storage Operations in Laravel

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

Demonstrates the fundamental operations of the Laravel Simple Cold Storage package: creating a StorageKey, storing data, retrieving data, checking for existence, and deleting data. It utilizes the package's facade for easy access.

```php
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);
```

--------------------------------

### Implement Custom MsgPack Encoder for Cold Storage

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

Provides an example of creating a custom encoder, MsgPackEncoder, that implements the EncoderInterface for the 'websolutionfalcon/laravel-simple-cold-storage' package. This encoder handles MessagePack encoding and decoding.

```php
// 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
    }
}
```

--------------------------------

### Custom MySQL Storage Implementation for Cold Storage

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

Provides a complete example of a custom storage driver for Laravel Simple Cold Storage that uses a MySQL database. It implements the ColdStorageInterface for storing, retrieving, deleting, and checking the existence of data.

```php
// app/ColdStorage/Storages/MySqlColdStorage.php

namespace App\ColdStorage\Storages;

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 $basePath,  // Used as table name
        protected ?string $connection = null
    ) {}

    public function store(mixed $data, StorageKey $key): void
    {
        $encoded = $this->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();
    }
}
```

```php
// config/laravel-simple-cold-storage.php
return [
    'base_path' => 'cold_storage',  // table name
    'storage' => \App\ColdStorage\Storages\MySqlColdStorage::class,
];
```

--------------------------------

### StorageKey DTO for Type-Safe Data Identification

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

Demonstrates the creation and usage of the StorageKey DTO for uniquely identifying data. It includes examples of creating keys with and without variants, converting to/from string representations, and handling validation errors.

```php
use Websolutionfalcon\LaravelSimpleColdStorage\DTOs\StorageKey;
use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\InvalidStorageKeyException;

// Create a StorageKey with type, identifier, and optional variant
$key = new StorageKey('orders', '12345', 'archived');
// File path: cold-storage/orders/12345.archived.json

// Create a StorageKey without variant
$keySimple = new StorageKey('users', '789');
// File path: cold-storage/users/789.json

// Convert StorageKey to string representation
$stringKey = $key->toString();  // "orders:12345:archived"
echo (string) $key;              // "orders:12345:archived"

// Create StorageKey from string
$parsedKey = StorageKey::fromString('orders:12345:archived');
echo $parsedKey->type;       // "orders"
echo $parsedKey->identifier; // "12345"
echo $parsedKey->variant;    // "archived"

// Validation - only alphanumeric, underscores, and hyphens allowed
try {
    $invalidKey = new StorageKey('invalid/type', '123');
} catch (InvalidStorageKeyException $e) {
    echo $e->getMessage();
    // "Storage key type must contain only alphanumeric characters, underscores, and hyphens."
}
```

--------------------------------

### Store Session Data using Laravel Simple Cold Storage in PHP

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

This PHP example demonstrates storing shopping cart data associated with a user's session. It creates a StorageKey using the session ID and stores the cart items and total.

```php
$key = new StorageKey('sessions', session()->getId(), 'cart');

LaravelSimpleColdStorage::store([
    'items' => $cart->items,
    'total' => $cart->total,
], $key);

```

--------------------------------

### Running Package Tests

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

Instructions on how to execute the tests for the Laravel Simple Cold Storage package. Includes commands for running standard tests and tests with code coverage.

```bash
composer test
```

```bash
composer test-coverage
```

--------------------------------

### Configure Cold Storage Disk and Prefix in .env

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

Illustrates how to configure the storage disk and path prefix for the 'websolutionfalcon/laravel-simple-cold-storage' package using environment variables. This allows for flexible storage location and path customization.

```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
```

--------------------------------

### Configuration

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

Configure the storage disk, path prefix, storage implementation, and encoder through the config file or environment variables.

```APIDOC
## Configuration

### Description
Configure the storage disk, path prefix, storage implementation, and encoder through the config file or environment variables.

### Config File (`config/laravel-simple-cold-storage.php`)
```php
return [
    'storage' => \Websolutionfalcon\LaravelSimpleColdStorage\ColdStorage::class,
    'settings' => [
        'disk' => env('COLD_STORAGE_DISK', 'local'),
        'prefix' => env('COLD_STORAGE_PREFIX', 'cold-storage'),
    ],
    'encoder' => \Websolutionfalcon\LaravelSimpleColdStorage\Encoders\JsonEncoder::class,
];
```

### Environment Variables (`.env`)

**Example 1: Local Filesystem**
```bash
COLD_STORAGE_DISK=local
COLD_STORAGE_PREFIX=cold-storage
```

**Example 2: S3 Cloud Storage**
```bash
COLD_STORAGE_DISK=s3
COLD_STORAGE_PREFIX=cold-storage
```

**Example 3: Custom Disk**
```bash
COLD_STORAGE_DISK=my_archive_disk
COLD_STORAGE_PREFIX=archives
```
```

--------------------------------

### Publish Laravel Simple Cold Storage Configuration

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

Publishes the configuration file for the 'websolutionfalcon/laravel-simple-cold-storage' package. This allows for customization of storage and encoder settings.

```bash
php artisan vendor:publish --provider="Websolutionfalcon\LaravelSimpleColdStorage\LaravelSimpleColdStorageServiceProvider" --tag="config"
```

--------------------------------

### Default Configuration for Laravel Simple Cold Storage

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

Shows the default configuration settings for the 'websolutionfalcon/laravel-simple-cold-storage' package. It specifies the storage implementation, disk, prefix, and encoder to be used.

```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,
];
```

--------------------------------

### Handle Cold Storage Exceptions in PHP

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

Demonstrates how to use a try-catch block to handle potential exceptions thrown by the Laravel Simple Cold Storage package. It covers `InvalidStorageKeyException`, `StorageNotFoundException`, and `EncodingException`, logging errors and returning appropriate JSON responses.

```php
use Websolutionfalcon\LaravelSimpleColdStorage\DTOs\StorageKey;
use Websolutionfalcon\LaravelSimpleColdStorage\Facades\LaravelSimpleColdStorage;
use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\StorageNotFoundException;
use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\EncodingException;
use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\InvalidStorageKeyException;

// Handle all possible exceptions
try {
    $key = StorageKey::fromString($userInput); // May throw InvalidStorageKeyException
    $data = LaravelSimpleColdStorage::retrieve($key); // May throw StorageNotFoundException

    // Process data...
    LaravelSimpleColdStorage::store($processedData, $key); // May throw EncodingException

} catch (InvalidStorageKeyException $e) {
    // Invalid key format: "type:identifier" or "type:identifier:variant" expected
    Log::warning('Invalid storage key provided', ['input' => $userInput, 'error' => $e->getMessage()]);
    return response()->json(['error' => 'Invalid storage key format'], 400);

} catch (StorageNotFoundException $e) {
    // Data doesn't exist at the specified key
    Log::info('Storage not found', ['key' => $key->toString()]);
    return response()->json(['error' => 'Data not found'], 404);

} catch (EncodingException $e) {
    // JSON encoding/decoding failed (e.g., invalid UTF-8, circular references)
    Log::error('Encoding failed', ['key' => $key->toString(), 'error' => $e->getMessage()]);
    return response()->json(['error' => 'Data encoding failed'], 500);
}
```

--------------------------------

### Dependency Injection for Cold Storage in Laravel

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

Demonstrates how to inject the ColdStorageInterface into a service class using Laravel's dependency injection. This allows for easy swapping of storage implementations.

```php
use Websolutionfalcon\LaravelSimpleColdStorage\Contracts\ColdStorageInterface;
use Websolutionfalcon\LaravelSimpleColdStorage\DTOs\StorageKey;

class OrderService
{
    public function __construct(
        protected ColdStorageInterface $coldStorage
    ) {}

    public function archiveOrder(Order $order): void
    {
        $key = new StorageKey('orders', (string) $order->id, 'archived');
        $this->coldStorage->store($order->toArray(), $key);
    }
}
```

--------------------------------

### Configure Custom Encoder in Laravel Simple Cold Storage

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

Shows how to configure the 'websolutionfalcon/laravel-simple-cold-storage' package to use a custom encoder by updating the configuration file. This allows for alternative data serialization formats.

```php
// config/laravel-simple-cold-storage.php

return [
    'encoder' => \App\ColdStorage\Encoders\MsgPackEncoder::class,
    // ... rest of config
];
```

--------------------------------

### Configure Laravel Simple Cold Storage

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

Configuration for the Laravel Simple Cold Storage package can be managed via the `config/laravel-simple-cold-storage.php` file or by using environment variables. Key settings include the storage disk, a path prefix for cold storage files, and the encoder implementation.

```php
// config/laravel-simple-cold-storage.php
return [
    // Storage implementation class (must implement ColdStorageInterface)
    'storage' => \Websolutionfalcon\LaravelSimpleColdStorage\ColdStorage::class,

    // Settings passed to the storage implementation
    'settings' => [
        'disk' => env('COLD_STORAGE_DISK', 'local'),    // Any Laravel filesystem disk
        'prefix' => env('COLD_STORAGE_PREFIX', 'cold-storage'), // Path prefix
    ],

    // Encoder implementation class (must implement EncoderInterface)
    'encoder' => \Websolutionfalcon\LaravelSimpleColdStorage\Encoders\JsonEncoder::class,
];
```

```bash
# .env - Configure storage disk and prefix
COLD_STORAGE_DISK=local          # Use local filesystem
COLD_STORAGE_PREFIX=cold-storage # Path prefix

# Use S3 for cloud storage
COLD_STORAGE_DISK=s3
# Files stored at: s3://bucket/cold-storage/orders/12345.json

# Use custom disk defined in config/filesystems.php
COLD_STORAGE_DISK=my_archive_disk
COLD_STORAGE_PREFIX=archives
```

--------------------------------

### Error Handling with Laravel Simple Cold Storage Exceptions

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

Demonstrates how to catch specific exceptions thrown by the Laravel Simple Cold Storage package during data retrieval. This includes handling cases where data is not found, encoding/decoding fails, or the storage key is invalid.

```php
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
}
```

--------------------------------

### Dependency Injection

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

Use the `ColdStorageInterface` for dependency injection in services and controllers, enabling better testability and decoupling.

```APIDOC
## Dependency Injection

### Description
Use the `ColdStorageInterface` for dependency injection in services and controllers, enabling better testability and decoupling.

### Example Service (`OrderArchiveService`)
```php
use Websolutionfalcon\LaravelSimpleColdStorage\Contracts\ColdStorageInterface;
use Websolutionfalcon\LaravelSimpleColdStorage\DTOs\StorageKey;
use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\StorageNotFoundException;

class OrderArchiveService
{
    public function __construct(
        protected ColdStorageInterface $coldStorage
    ) {}

    public function archiveOrder(Order $order): StorageKey
    {
        $key = new StorageKey('orders', (string) $order->id, 'archived');

        $this->coldStorage->store([
            'order_data' => $order->toArray(),
            'items' => $order->items->toArray(),
            'archived_at' => now()->toIso8601String(),
        ], $key);

        return $key;
    }

    public function retrieveArchivedOrder(int $orderId): ?array
    {
        $key = new StorageKey('orders', (string) $orderId, 'archived');

        try {
            return $this->coldStorage->retrieve($key);
        } catch (StorageNotFoundException) {
            return null;
        }
    }

    public function deleteArchivedOrder(int $orderId): bool
    {
        $key = new StorageKey('orders', (string) $orderId, 'archived');
        return $this->coldStorage->delete($key);
    }
}
```

### Example Controller Usage
```php
use App\Http\Controllers\Controller;
use App\Models\Order;
use OrderArchiveService; // Assuming OrderArchiveService is registered

class OrderController extends Controller
{
    public function __construct(
        protected OrderArchiveService $archiveService
    ) {}

    public function archive(Order $order)
    {
        $key = $this->archiveService->archiveOrder($order);
        $order->update(['archived_key' => $key->toString()]);
        $order->delete();

        return response()->json(['archived_key' => $key->toString()]);
    }
}
```
```

--------------------------------

### Manage StorageKey DTO in PHP

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

This PHP code illustrates the usage of the StorageKey DTO for identifying stored data. It shows how to create StorageKeys with and without variants, how to create them from a string representation, and how to convert them back to a string.

```php
// With variant
$key = new StorageKey('users', '123', 'profile');

// Without variant
$key = new StorageKey('orders', '456');

// From string
$key = StorageKey::fromString('users:123:profile');

// To string
$str = $key->toString(); // "users:123:profile"
$str = (string) $key;     // "users:123:profile"

```

--------------------------------

### Implement Custom MySQL Storage Backend in PHP

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

This PHP code illustrates a custom storage backend for MySQL by implementing `ColdStorageInterface`. It handles storing, retrieving, deleting, and checking the existence of data in a specified MySQL table, using an injected encoder for data serialization. Configuration details for this storage are also provided.

```php
// 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): ColdStorageInterface
    {
        return new self(
            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();
    }
}

// config/laravel-simple-cold-storage.php
return [
    'storage' => \App\ColdStorage\MySqlColdStorage::class,
    'settings' => [
        'table' => 'cold_storage',
        'connection' => null, // Uses default database connection
    ],
    'encoder' => \Websolutionfalcon\LaravelSimpleColdStorage\Encoders\JsonEncoder::class,
];
```

--------------------------------

### Configure Laravel Simple Cold Storage in PHP

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

This PHP configuration file sets up the Laravel Simple Cold Storage. It specifies the custom storage class to use, its associated settings (like table name and database connection), and the encoder to be used for data serialization.

```php
// 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,
];

```

--------------------------------

### Implement Custom MessagePack Encoder in PHP

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

This snippet demonstrates how to create a custom encoder for MessagePack format by implementing the `EncoderInterface`. It includes methods for encoding, decoding, and defining content type and file extension. Configuration for using this encoder is also shown.

```php
// 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 saved as .msgpack
    }
}

// config/laravel-simple-cold-storage.php
return [
    'encoder' => \App\ColdStorage\Encoders\MsgPackEncoder::class,
    // ... rest of config
];
```

--------------------------------

### Retrieve Data using LaravelSimpleColdStorage::retrieve()

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

Illustrates how to retrieve stored data using its StorageKey. The method decodes the data from its stored format. It also shows how to handle `StorageNotFoundException` if the data does not exist.

```php
use Websolutionfalcon\LaravelSimpleColdStorage\DTOs\StorageKey;
use Websolutionfalcon\LaravelSimpleColdStorage\Facades\LaravelSimpleColdStorage;
use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\StorageNotFoundException;

$key = new StorageKey('orders', '12345', 'archived');

try {
    $data = LaravelSimpleColdStorage::retrieve($key);

    // Access the retrieved data
    echo $data['order_id'];    // 12345
    echo $data['customer'];    // "John Doe"
    echo $data['total'];       // 109.97

    foreach ($data['items'] as $item) {
        echo "{$item['product']}: {$item['qty']} x ${$item['price']}\n";
    }
    // Output:
    // Widget: 2 x $29.99
    // Gadget: 1 x $49.99

} catch (StorageNotFoundException $e) {
    echo "Order not found: " . $e->getMessage();
    // "Storage not found for key: orders:12345:archived"
}
```

--------------------------------

### Create Versioned Backups using Laravel Simple Cold Storage in PHP

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

This PHP snippet shows how to create versioned backups of data. It generates a unique key based on the current timestamp and stores a database dump along with the creation time into cold storage.

```php
$version = now()->format('Y-m-d-His');
$key = new StorageKey('backups', 'database', $version);

LaravelSimpleColdStorage::store([
    'tables' => $databaseDump,
    'created_at' => now(),
], $key);

```

--------------------------------

### Store Data using LaravelSimpleColdStorage::store()

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

Shows how to store various types of data (arrays, objects, primitives) using the `store()` method. Data is encoded (JSON by default) and saved to a path determined by the provided StorageKey.

```php
use Websolutionfalcon\LaravelSimpleColdStorage\DTOs\StorageKey;
use Websolutionfalcon\LaravelSimpleColdStorage\Facades\LaravelSimpleColdStorage;

// Store an array
$orderData = [
    'order_id' => 12345,
    'customer' => 'John Doe',
    'items' => [
        ['product' => 'Widget', 'qty' => 2, 'price' => 29.99],
        ['product' => 'Gadget', 'qty' => 1, 'price' => 49.99],
    ],
    'total' => 109.97,
    'created_at' => '2025-01-22T10:30:00Z',
];

$key = new StorageKey('orders', '12345', 'archived');
LaravelSimpleColdStorage::store($orderData, $key);
// Saved to: storage/app/cold-storage/orders/12345.archived.json

// Store user profile data
$userProfile = [
    'user_id' => 789,
    'preferences' => ['theme' => 'dark', 'notifications' => true],
    'metadata' => ['last_login' => now()->toIso8601String()],
];

$userKey = new StorageKey('users', '789', 'profile');
LaravelSimpleColdStorage::store($userProfile, $userKey);
// Saved to: storage/app/cold-storage/users/789.profile.json
```

--------------------------------

### Dependency Injection with ColdStorageInterface

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

The `ColdStorageInterface` can be used for dependency injection in Laravel services and controllers. This promotes better testability and decoupling by allowing you to easily swap out storage implementations or mock the interface during testing.

```php
use Websolutionfalcon\LaravelSimpleColdStorage\Contracts\ColdStorageInterface;
use Websolutionfalcon\LaravelSimpleColdStorage\DTOs\StorageKey;
use Websolutionfalcon\LaravelSimpleColdStorage\Exceptions\StorageNotFoundException;

class OrderArchiveService
{
    public function __construct(
        protected ColdStorageInterface $coldStorage
    ) {}

    public function archiveOrder(Order $order): StorageKey
    {
        $key = new StorageKey('orders', (string) $order->id, 'archived');

        $this->coldStorage->store([
            'order_data' => $order->toArray(),
            'items' => $order->items->toArray(),
            'archived_at' => now()->toIso8601String(),
        ], $key);

        return $key;
    }

    public function retrieveArchivedOrder(int $orderId): ?array
    {
        $key = new StorageKey('orders', (string) $orderId, 'archived');

        try {
            return $this->coldStorage->retrieve($key);
        } catch (StorageNotFoundException) {
            return null;
        }
    }

    public function deleteArchivedOrder(int $orderId): bool
    {
        $key = new StorageKey('orders', (string) $orderId, 'archived');
        return $this->coldStorage->delete($key);
    }
}

// Usage in controller
class OrderController extends Controller
{
    public function __construct(
        protected OrderArchiveService $archiveService
    ) {}

    public function archive(Order $order)
    {
        $key = $this->archiveService->archiveOrder($order);
        $order->update(['archived_key' => $key->toString()]);
        $order->delete();

        return response()->json(['archived_key' => $key->toString()]);
    }
}
```

--------------------------------

### Archive Old Data using Laravel Simple Cold Storage in PHP

Source: https://github.com/websolutionfalcon/laravel-simple-cold-storage/blob/master/README.md

This PHP code demonstrates archiving old order data. It retrieves orders older than two years, stores their data and associated items in cold storage using a unique StorageKey, updates the order record with the key, and then deletes the original order.

```php
$oldOrders = Order::where('created_at', '<', now()->subYears(2))->get();

foreach ($oldOrders as $order) {
    $key = new StorageKey('orders', (string) $order->id, 'archived');

    LaravelSimpleColdStorage::store([
        'order_data' => $order->toArray(),
        'items' => $order->items->toArray(),
    ], $key);

    $order->update(['archived_key' => $key->toString()]);
    $order->delete();
}

```

--------------------------------

### LaravelSimpleColdStorage::exists()

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

Checks if data exists for a given StorageKey without retrieving it. Returns a boolean indicating existence.

```APIDOC
## POST /websolutionfalcon/laravel-simple-cold-storage/exists

### Description
Checks if data exists for a given StorageKey without retrieving it. Returns a boolean indicating existence.

### Method
POST

### Endpoint
/websolutionfalcon/laravel-simple-cold-storage/exists

### Parameters
#### Request Body
- **key** (StorageKey) - Required - The StorageKey object representing the data to check.

### Request Example
```json
{
  "key": {
    "namespace": "orders",
    "id": "12345",
    "suffix": "archived"
  }
}
```

### Response
#### Success Response (200)
- **exists** (boolean) - True if the data exists, false otherwise.

#### Response Example
```json
{
  "exists": true
}
```
```

--------------------------------

### Check Data Existence with LaravelSimpleColdStorage::exists()

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

The `exists()` method checks if data associated with a given `StorageKey` is present in cold storage without retrieving the data itself. It returns a boolean value: `true` if the data exists, and `false` otherwise. This is useful for conditional operations before attempting to store or retrieve data.

```php
use Websolutionfalcon\LaravelSimpleColdStorage\DTOs\StorageKey;
use Websolutionfalcon\LaravelSimpleColdStorage\Facades\LaravelSimpleColdStorage;

$key = new StorageKey('orders', '12345', 'archived');

if (LaravelSimpleColdStorage::exists($key)) {
    echo "Archived order exists, retrieving...";
    $data = LaravelSimpleColdStorage::retrieve($key);
} else {
    echo "No archived order found for ID 12345";
}

// Useful for conditional storage operations
$backupKey = new StorageKey('backups', 'database', now()->format('Y-m-d'));

if (!LaravelSimpleColdStorage::exists($backupKey)) {
    $databaseDump = getDatabaseDump(); // Your backup logic
    LaravelSimpleColdStorage::store($databaseDump, $backupKey);
    echo "Backup created for " . now()->format('Y-m-d');
} else {
    echo "Backup already exists for today";
}
```

--------------------------------

### LaravelSimpleColdStorage::delete()

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

Deletes stored data by its StorageKey. Returns `true` if the data was deleted, `false` if it didn't exist.

```APIDOC
## POST /websolutionfalcon/laravel-simple-cold-storage/delete

### Description
Deletes stored data by its StorageKey. Returns `true` if the data was deleted, `false` if it didn't exist.

### Method
POST

### Endpoint
/websolutionfalcon/laravel-simple-cold-storage/delete

### Parameters
#### Request Body
- **key** (StorageKey) - Required - The StorageKey object representing the data to delete.

### Request Example
```json
{
  "key": {
    "namespace": "orders",
    "id": "12345",
    "suffix": "archived"
  }
}
```

### Response
#### Success Response (200)
- **deleted** (boolean) - True if the data was deleted, false otherwise.

#### Response Example
```json
{
  "deleted": true
}
```
```

--------------------------------

### Delete Data with LaravelSimpleColdStorage::delete()

Source: https://context7.com/websolutionfalcon/laravel-simple-cold-storage/llms.txt

The `delete()` method removes data from cold storage based on its `StorageKey`. It returns `true` if the data was successfully deleted, and `false` if the data did not exist at the specified key. This is useful for cleaning up old or unnecessary stored information.

```php
use Websolutionfalcon\LaravelSimpleColdStorage\DTOs\StorageKey;
use Websolutionfalcon\LaravelSimpleColdStorage\Facades\LaravelSimpleColdStorage;

$key = new StorageKey('orders', '12345', 'archived');

$deleted = LaravelSimpleColdStorage::delete($key);

if ($deleted) {
    echo "Archived order successfully deleted";
} else {
    echo "No archived order found to delete";
}

// Clean up old session data
$sessionKey = new StorageKey('sessions', session()->getId(), 'cart');
if (LaravelSimpleColdStorage::exists($sessionKey)) {
    LaravelSimpleColdStorage::delete($sessionKey);
}
```
Tokens:
Raw