Bezpapirove Php Lib Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require bezpapirove/bezpapirove_php_lib
   

2. Basic File Storage (v2.x):

   use Bezpapirove\BezpapirovePhpLib\File\FileStorageFactory;
   use Bezpapirove\BezpapirovePhpLib\File\Uuid;
   
   $config = [
       'driver' => 'local', // or 's3'
       'path'   => storage_path('app/files'),
       // S3-specific config (if applicable):
       // 'bucket' => 'your-bucket',
       // 'key'    => 'your-key',
       // 'secret' => 'your-secret',
   ];
   
   $storage = FileStorageFactory::createFromConfig($config);
   

3. First Use Case: Upload a File

   $uuid = Uuid::generate(); // Generate UUID for the file
   $storage->save('/path/to/local/file.txt', $uuid);
   

Key Entry Points

• FileStorageFactory: Centralized way to create storage adapters (local/S3).
• Uuid class: Handles UUID generation/validation for file naming.
• FileStorageInterface: Core methods for CRUD operations on files.

Implementation Patterns

Core Workflows

1. File Upload/Retrieval

// Upload
$uuid = Uuid::generate();
$storage->save($localPath, $uuid);

// Retrieve
$fileContent = $storage->read($uuid);

2. Storage-Agnostic Logic

Leverage the FileStorageInterface to abstract storage backends:

public function processFile(FileStorageInterface $storage, Uuid $uuid) {
    if ($storage->exists($uuid)) {
        $content = $storage->read($uuid);
        // Process content...
        $storage->duplicate($uuid, Uuid::generate()); // Backup
    }
}

3. S3 Integration

Configure S3 in the factory:

$config = [
    'driver' => 's3',
    'bucket' => 'my-bucket',
    'key'    => env('AWS_KEY'),
    'secret' => env('AWS_SECRET'),
];
$storage = FileStorageFactory::createFromConfig($config);

4. Legacy Folder Structure (v1.x)

For projects using v1.x, use FolderStructure:

use Bezpapirove\BezpapirovePhpLib\File\FolderStructure;

$path = FolderStructure::getFolderStructureFromFileName(
    Uuid::fromString('123e4567-e89b-12d3-a456-426614174000'),
    2 // Depth
);
FolderStructure::createFolderStructure(storage_path('app'), $path);

Integration Tips

• Laravel Service Providers: Bind FileStorageInterface to a concrete implementation in AppServiceProvider:

  $this->app->bind(FileStorageInterface::class, function ($app) {
      return FileStorageFactory::createFromConfig(config('filesystem.storage'));
  });
  

• Validation: Use Uuid::isValid() to validate UUIDs before operations.
• Error Handling: Wrap storage operations in try-catch blocks (e.g., FileNotFoundException for missing files).

Gotchas and Tips

Pitfalls

1. Version Mismatch:

   • v1.x vs. v2.x: v2.0.x introduces FileStorageFactory and breaks backward compatibility. Avoid mixing versions in the same project.
   • Fix: Stick to one version per project; update dependencies atomically.

2. UUID Collisions:

   • The library uses UUIDs for filenames. Ensure your application handles collisions (e.g., by appending timestamps or hashes):

     $uuid = Uuid::generate();
     $safeUuid = $uuid->toString() . '-' . time();
     

3. S3 Configuration:

   • Missing AWS credentials or incorrect bucket names will throw RuntimeException. Validate configs early:

     try {
         $storage = FileStorageFactory::createFromConfig($config);
     } catch (\RuntimeException $e) {
         Log::error('S3 config invalid: ' . $e->getMessage());
     }
     

4. Local Storage Paths:

   • Hardcoded paths (e.g., /tmp) may fail in production. Always use Laravel’s storage_path() or config-driven paths.

Debugging

• File Not Found: Check if the UUID is valid (Uuid::isValid($uuid)) and if the storage backend is correctly configured.
• Permission Issues: Ensure the storage directory (e.g., storage/app/files) is writable:

  chmod -R 775 storage/app/files
  

• S3 Debugging: Enable AWS SDK debugging:

  \Aws\setLogger(new \Monolog\Logger('AWS'));
  

Extension Points

1. Custom Storage Drivers: Extend FileStorageInterface and register new drivers in FileStorageFactory:

   FileStorageFactory::registerDriver('custom', function ($config) {
       return new CustomStorage($config);
   });
   

2. UUID Generation: Override the default UUID generator (e.g., for shorter IDs):

   Uuid::setGenerator(function () {
       return Uuid::fromString(Str::uuid());
   });
   

3. Event Hooks: Listen for file operations (e.g., post-upload processing):

   $storage->save($path, $uuid);
   event(new FileUploaded($uuid, $path));
   

Configuration Quirks

• Default Config: The library expects a config/filesystem.storage array in Laravel. Example:

  'storage' => [
      'driver' => env('FILESYSTEM_DRIVER', 'local'),
      'path'   => storage_path('app/files'),
  ],
  

• S3 Credentials: Store AWS keys in .env and reference them in the config:

  AWS_ACCESS_KEY_ID=your-key
  AWS_SECRET_ACCESS_KEY=your-secret
  AWS_DEFAULT_REGION=us-east-1
  

Performance Tips

• Batch Operations: For bulk file handling, minimize factory calls by reusing storage instances.
• Streaming: Use read() with file_get_contents() for large files to avoid memory issues:

  $content = $storage->read($uuid);
  file_put_contents($localPath, $content);
  

• Caching: Cache exists() checks if files rarely change:

  $cacheKey = "file_exists_{$uuid}";
  if (!Cache::has($cacheKey) && !$storage->exists($uuid)) {
      Cache::put($cacheKey, false, now()->addHours(1));
  }