## Getting Started
1. **Installation**: Require the package via Composer:
   ```bash
   composer require becklyn/ddd-file-store:^5.0

Prerequisites: Ensure your project uses Symfony 7 (or higher) and becklyn/ddd-symfony-bridge 5 (or higher). Drop support for becklyn/ddd-symfony-bridge 3 in this version.

First Use Case: Integrate the file store into a DDD (Domain-Driven Design) entity or aggregate root. Example:

use Becklyn\DddFileStore\FileStore;
use Becklyn\DddFileStore\FileMetadata;

$fileStore = app(FileStore::class);
$metadata = new FileMetadata('user-uploads', 'document.pdf');
$fileStore->store($metadata, fopen('path/to/local/file', 'r'));

Implementation Patterns

Symfony 7 Integration

Leverage Symfony 7’s improved dependency injection and configuration system for tighter integration. Use the package’s configuration via config/packages/becklyn_ddd_file_store.yaml:
```
becklyn_ddd_file_store:
    storage: 'local' # or 's3', 'gcs', etc.
    local:
        directory: '%kernel.project_dir%/public/uploads'
```

Event Dispatching: The package now aligns with Symfony 7’s event system. Listen for events like FileStoredEvent or FileDeletedEvent:

use Becklyn\DddFileStore\Event\FileStoredEvent;

// In a Symfony service or controller
$this->eventDispatcher->dispatch(new FileStoredEvent($metadata, $filePath));

DDD-Symfony-Bridge 5 Workflow

Aggregate Roots: Use the file store within aggregate roots to manage domain invariants. Example:

use Becklyn\Ddd\SymfonyBridge\Aggregate\AggregateRoot;

class DocumentAggregate extends AggregateRoot
{
    public function attachFile(FileMetadata $metadata, $fileContent): void
    {
        $this->fileStore->store($metadata, $fileContent);
        $this->recordThat(new FileAttached($metadata->getFileName()));
    }
}

Repositories: Inject FileStore into repositories to handle file persistence alongside domain entities:

use Becklyn\Ddd\SymfonyBridge\Repository\Repository;

class DocumentRepository extends Repository
{
    public function __construct(private FileStore $fileStore) {}

    public function saveWithFile(Document $document, $fileContent): void
    {
        $this->fileStore->store($document->getFileMetadata(), $fileContent);
        $this->save($document);
    }
}

Multi-Storage Support

Configure multiple storage backends (e.g., local, S3, GCS) in the Symfony config:

becklyn_ddd_file_store:
    storage: 's3'
    s3:
        bucket: 'my-bucket'
        region: 'eu-west-1'
        credentials:
            key: '%env(S3_KEY)%'
            secret: '%env(S3_SECRET)%'

Switch storage dynamically in runtime:

$fileStore->setStorage('gcs'); // If configured

Gotchas and Tips

Breaking Changes

DDD-Symfony-Bridge 3 Drop: Projects using becklyn/ddd-symfony-bridge:^3 must upgrade to ^5. Update dependencies and check for API changes in the bridge (e.g., event names, service IDs).
Symfony 6 Compatibility: While this package now supports Symfony 7, ensure your other dependencies (e.g., Symfony components, Doctrine) are also compatible.

Debugging

File Metadata Validation: The package validates FileMetadata objects strictly. Ensure:

$metadata = new FileMetadata(
    'valid-storage-key', // Must match configured storage
    'document.pdf',      // Must include extension
    'application/pdf'    // MIME type recommended
);

Errors like InvalidStorageKeyException or InvalidFileExtensionException may appear if metadata is malformed.

Storage Backend Issues: For S3/GCS, verify IAM roles/credentials and network connectivity. Use Symfony’s monolog to log storage operations:

# config/packages/monolog.yaml
monolog:
    handlers:
        file_store:
            type: stream
            path: "%kernel.logs_dir%/file_store.log"
            level: debug
            channels: ["file_store"]

Extension Points

Custom Storage Adapters: Extend the package by implementing Becklyn\DddFileStore\Storage\StorageInterface:

use Becklyn\DddFileStore\Storage\StorageInterface;

class CustomStorage implements StorageInterface
{
    public function store(FileMetadata $metadata, $content): string
    {
        // Custom logic (e.g., Azure Blob Storage)
        return $this->uploadToAzure($metadata, $content);
    }
}

services:
    Becklyn\DddFileStore\Storage\StorageInterface: '@custom_storage'

Event Subscribers: Create subscribers for file events to trigger side effects (e.g., notifications, analytics):

use Becklyn\DddFileStore\Event\FileStoredEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class FileStoredSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            FileStoredEvent::class => 'onFileStored',
        ];
    }

    public function onFileStored(FileStoredEvent $event): void
    {
        // Send email, log analytics, etc.
    }
}

Performance Tips

Streaming Large Files: Use PHP streams to avoid memory issues:
```
$fileStore->store($metadata, fopen('large_file.zip', 'r'));
```
Caching Metadata: Cache FileMetadata objects if frequently reused (e.g., in a Symfony cache pool):
```
$metadata = $this->cache->get('file_metadata_' . $id, fn() => $this->loadMetadata());
```

Ddd File Store Laravel Package