Flysystem Gitlab Storage Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require royvoetman/flysystem-gitlab-storage
   

2. Basic Usage

   use League\Flysystem\Filesystem;
   use Royvoetman\Flysystem\GitlabStorage\GitlabStorageAdapter;
   
   $adapter = new GitlabStorageAdapter(
       'https://gitlab.example.com',
       'your_access_token',
       'project_id_or_path'
   );
   
   $filesystem = new Filesystem($adapter);
   

3. First Use Case: Uploading a File

   $filesystem->write('path/to/file.txt', 'file content');
   

4. Where to Look First

   • Package Documentation (if available)
   • Flysystem Documentation (for core concepts)
   • GitLab API Docs (for API specifics)

Implementation Patterns

Common Workflows

1. File Operations

• Uploading Files

  $filesystem->write('remote/path/file.txt', file_get_contents('local/file.txt'));
  

• Downloading Files

  $content = $filesystem->read('remote/path/file.txt');
  file_put_contents('local/file.txt', $content);
  

• Deleting Files

  $filesystem->delete('remote/path/file.txt');
  

2. Directory Operations

• Creating Directories

  $filesystem->createDirectory('remote/path/dir');
  

• Listing Files

  $files = $filesystem->listContents('remote/path');
  

3. Integration with Laravel

• Using with Laravel Filesystem

  // config/filesystems.php
  'disks' => [
      'gitlab' => [
          'driver' => 'gitlab',
          'url' => env('GITLAB_URL'),
          'token' => env('GITLAB_TOKEN'),
          'project' => env('GITLAB_PROJECT'),
      ],
  ],
  

• In a Controller

  use Illuminate\Support\Facades\Storage;
  
  Storage::disk('gitlab')->put('file.txt', 'content');
  

4. Handling Special Characters in Paths

• Spaces in Paths GitLab now rejects paths containing spaces replaced by +. Ensure paths are URL-encoded properly:

  $filesystem->write('remote/path/with spaces/file.txt', 'content');
  

  The adapter now uses rawurlencode() internally for proper handling.

5. Error Handling

• Wrap operations in try-catch blocks:

  try {
      $filesystem->write('file.txt', 'content');
  } catch (\League\Flysystem\FilesystemException $e) {
      Log::error('GitLab upload failed: ' . $e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. Authentication Issues

   • Ensure the access token has the correct permissions (read_repository, write_repository).
   • Tokens expire; monitor and rotate them.

2. Project Path vs. ID

   • Confusion between project_id and project_path (e.g., group/project).
   • Use project_path for nested projects/groups.

3. Rate Limiting

   • GitLab API has rate limits. Handle 429 Too Many Requests gracefully:

     try {
         $filesystem->read('file.txt');
     } catch (\League\Flysystem\FilesystemException $e) {
         if ($e->getCode() === 429) {
             sleep(1); // Retry after delay
         }
     }
     

4. File Size Limits

   • GitLab has a file size limit (10MB for non-LFS files by default).
   • Use Git LFS for larger files.

5. URL Encoding in Paths

   • Breaking Change in v3.1.1: GitLab now rejects paths with spaces replaced by +. The package now uses rawurlencode() instead of urlencode() for proper encoding.
   • Avoid manually encoding paths; let the adapter handle it:

     // Avoid this (manual encoding may cause issues):
     $filesystem->write(rawurlencode('path/with spaces'), 'content');
     
     // Let the adapter handle it:
     $filesystem->write('path/with spaces', 'content');
     

6. Case Sensitivity

   • GitLab paths are case-sensitive on some systems. Ensure consistency:

     $filesystem->write('File.txt', 'content'); // May fail if 'file.txt' exists.
     

Debugging Tips

1. Enable Debugging

   • Use Guzzle’s debug middleware to inspect API requests:

     $client = new \GuzzleHttp\Client([
         'debug' => fopen('guzzle.log', 'w'),
     ]);
     $adapter = new GitlabStorageAdapter($client, ...);
     

2. Check API Responses

   • Log raw responses for errors:

     $adapter->getClient()->getConfig('debug', true);
     

3. Validate Tokens

   • Test token validity via API:

     curl --header "PRIVATE-TOKEN: <your_token>" https://gitlab.example.com/api/v4/user
     

Extension Points

1. Custom Headers

   • Add headers (e.g., for private projects):

     $adapter = new GitlabStorageAdapter(
         'https://gitlab.example.com',
         'token',
         'project',
         ['headers' => ['X-Custom-Header' => 'value']]
     );
     

2. Proxy Support

   • Configure proxy settings in Guzzle:

     $client = new \GuzzleHttp\Client([
         'proxy' => 'http://proxy.example.com:8080',
     ]);
     

3. Event Listeners

   • Extend the adapter for custom logic (e.g., logging):

     $adapter->setEventDispatcher(new CustomEventDispatcher());
     

4. Flysystem Events

   • Listen to Flysystem events (e.g., preWrite, postRead):

     $filesystem->addListener('preWrite', function ($event) {
         Log::info('Writing file: ' . $event->getPath());
     });
     

Configuration Quirks

1. SSL Verification

   • Disable SSL verification (not recommended for production):

     $client = new \GuzzleHttp\Client(['verify' => false]);
     

2. Timeouts

   • Adjust timeout settings for slow connections:

     $client = new \GuzzleHttp\Client(['timeout' => 30]);
     

3. Environment Variables

   • Use Laravel’s .env for sensitive data:

     GITLAB_URL=https://gitlab.example.com
     GITLAB_TOKEN=your_token_here
     GITLAB_PROJECT=group/project