Php Minio Service Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require borwita-packages/php-minio-service
   

2. Publish Configuration

   php artisan vendor:publish --provider="Borwita\MinioService\MinioServiceProvider" --tag="config"
   

   • Edit config/minio-service.php with your MinIO endpoint, credentials, and bucket settings.

3. First Use Case: Upload a File

   use Borwita\MinioService\Facades\MinioService;
   
   $filePath = 'path/to/local/file.jpg';
   $objectName = 'uploaded/' . time() . '_file.jpg';
   
   MinioService::uploadFile($filePath, $objectName);
   

Key Configuration Fields

• endpoint: MinIO server URL (e.g., http://localhost:9000).
• access_key/secret_key: MinIO credentials.
• bucket: Default bucket name (or configure per-operation).
• use_ssl: Enable/disable SSL.

Implementation Patterns

Common Workflows

1. File Operations

• Upload:

  MinioService::uploadFile($localPath, $objectName, ['bucket' => 'custom-bucket']);
  

• Download:

  $fileContent = MinioService::downloadFile($objectName, ['bucket' => 'custom-bucket']);
  file_put_contents('local-path', $fileContent);
  

• Delete:

  MinioService::deleteFile($objectName);
  

2. Bucket Management

• Create/Check Bucket:

  MinioService::ensureBucketExists('new-bucket');
  

• List Objects:

  $objects = MinioService::listObjects('bucket-name');
  

3. Presigned URLs (Temporary Access)

$url = MinioService::getPresignedUrl(
    $objectName,
    'GET',
    '+1 hour', // Expiry time
    ['bucket' => 'private-bucket']
);

4. Integration with Laravel Filesystem

Configure filesystems.php to use the package:

'disks' => [
    'minio' => [
        'driver' => 'minio',
        'bucket' => env('MINIO_BUCKET'),
    ],
],

Then use Laravel’s Storage facade:

Storage::disk('minio')->put('file.jpg', file_get_contents('local.jpg'));

5. Customizing Client Options

Override default MinIO client settings per request:

MinioService::uploadFile($filePath, $objectName, [
    'bucket' => 'custom-bucket',
    'client_options' => [
        'region' => 'us-east-1',
        'endpoint' => 'https://custom-minio.example.com',
    ],
]);

Gotchas and Tips

Pitfalls

1. Bucket Existence

   • Always call ensureBucketExists() or handle BucketAlreadyExists/BucketNotFound exceptions.
   • Example:

     try {
         MinioService::ensureBucketExists('my-bucket');
     } catch (\Borwita\MinioService\Exceptions\BucketExists $e) {
         // Bucket already exists; proceed.
     }
     

2. Permissions

   • Ensure your MinIO credentials have the correct permissions (e.g., readwrite for buckets).
   • Test with mc admin policy list (MinIO CLI) if issues arise.

3. SSL/TLS

   • If using self-signed certificates, configure the CA bundle:

     MinioService::setClientOptions([
         'ssl' => [
             'verify_peer' => true,
             'cafile' => '/path/to/ca-cert.pem',
         ],
     ]);
     

4. Large Files

   • For files > 5GB, use multipart uploads:

     $uploadId = MinioService::startMultipartUpload($objectName);
     MinioService::uploadPart($uploadId, $filePath, 1);
     MinioService::completeMultipartUpload($uploadId, [$objectName]);
     

5. Caching Presigned URLs

   • Presigned URLs expire quickly. Cache them in Redis or regenerate as needed.

Debugging Tips

• Enable Debugging:

  MinioService::setDebug(true); // Logs MinIO client requests/responses.
  

• Check MinIO Server Logs:
  • Use mc admin service log show (MinIO CLI) to inspect server-side errors.

Extension Points

1. Custom Storage Adapter Extend \Borwita\MinioService\Contracts\MinioServiceContract to add custom logic (e.g., metadata handling).

2. Events Listen for file operations via Laravel events (e.g., minio.file.uploaded).

3. Middleware Add middleware to the MinIO client for logging/auditing:

   MinioService::setClientMiddleware(function ($request) {
       logger()->info('MinIO Request:', $request->getData());
   });
   

Performance

• Batch Operations: Use MinioService::batchOperations() for multiple file actions (e.g., delete).
• Parallel Uploads: For multiple files, use Laravel queues or parallel processing (e.g., spatie/async package).