Pydio Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require "a5sys/pydio-bundle"
   

   Add to config/bundles.php (Laravel 5.4+):

   A5sys\PydioBundle\PydioBundle::class => ['dev' => true],
   

   (For Symfony, register in AppKernel.php under dev environment.)

2. Configuration Define parameters in config/parameters.yml:

   pydio_base_url: 'https://your-pydio-instance.com'
   pydio_api_url: '/pydio/api/v2'
   pydio_login: 'your_username'
   pydio_password: 'your_password'
   

   Reference them in config/packages/pydio.yaml (or config.yml for Symfony):

   pydio:
       base_api_url: '%pydio_base_url%'
       api_url: '%pydio_api_url%'
       login: '%pydio_login%'
       password: '%pydio_password%'
   

3. First Use Case Inject pydio.directory_service into a controller/service and list directories:

   use A5sys\PydioBundle\Service\DirectoryService;
   
   class MyController extends Controller
   {
       public function __construct(private DirectoryService $directoryService) {}
   
       public function listDirectories()
       {
           $directories = $this->directoryService->listDirectories('workspace_id');
           return response()->json($directories);
       }
   }
   

Implementation Patterns

Core Workflows

1. Directory Operations

   • List directories in a workspace/folder:

     $this->directoryService->listDirectories('workspace_id', 'parent_folder_id');
     

   • Create a directory:

     $this->directoryService->createDirectory('workspace_id', 'parent_folder_id', 'new_folder_name');
     

   • Delete a directory:

     $this->directoryService->removeDirectory('workspace_id', 'folder_id');
     

2. File Operations

   • Upload a file (via pydio.file_service):

     $this->fileService->createFile(
         'workspace_id',
         'parent_folder_id',
         'filename.txt',
         $fileContent,
         'text/plain'
     );
     

   • Download file content:

     $content = $this->fileService->getFileContent('workspace_id', 'file_id');
     

3. Search Functionality

   • Search files/directories in a workspace:

     $results = $this->searchService->search('workspace_id', 'query', 'file');
     

Integration Tips

• Authentication: Use environment variables or Laravel’s .env for credentials (avoid hardcoding).
• Error Handling: Wrap service calls in try-catch blocks to handle Pydio API errors (e.g., 404 Not Found):

  try {
      $this->directoryService->listDirectories('invalid_id');
  } catch (\Exception $e) {
      Log::error('Pydio API Error: ' . $e->getMessage());
      return response()->json(['error' => 'Workspace not found'], 404);
  }
  

• API Versioning: The bundle uses v2 of Pydio’s API. Verify compatibility with your Pydio instance.
• Rate Limiting: Implement retries for transient failures (e.g., using GuzzleHttp\RetryMiddleware).

Laravel-Specific Patterns

• Service Providers: Bind the bundle’s services to Laravel’s container in AppServiceProvider:

  public function register()
  {
      $this->app->bind(
          \A5sys\PydioBundle\Service\DirectoryService::class,
          function ($app) {
              return $app->make('pydio.directory_service');
          }
      );
  }
  

• Artisan Commands: Extend the bundle for CLI tasks (e.g., sync local files with Pydio):

  class SyncPydioCommand extends Command
  {
      protected $fileService;
  
      public function __construct(FileService $fileService)
      {
          parent::__construct();
          $this->fileService = $fileService;
      }
  
      public function handle()
      {
          // Sync logic here
      }
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle

   • Last release: 2019. Test thoroughly with your Pydio version (API changes may break functionality).
   • Mitigation: Fork the repository and update dependencies (e.g., guzzlehttp/guzzle for modern HTTP clients).

2. Authentication Failures

   • Hardcoded credentials in config.yml are insecure. Use Laravel’s .env:

     PYDIO_LOGIN=your_login
     PYDIO_PASSWORD=your_password
     

   • Debugging: Enable Guzzle logging to inspect API requests:

     $client = new \GuzzleHttp\Client([
         'handler' => \GuzzleHttp\HandlerStack::create([
             new \GuzzleHttp\Middleware::tap(function ($request) {
                 Log::debug('Pydio Request:', ['url' => (string) $request->getUri()]);
             }),
         ]),
     ]);
     

3. API URL Mismatches

   • Ensure base_api_url (e.g., https://pydio.example.com) and api_url (e.g., /pydio/api/v2) form a valid endpoint.
   • Validation: Add a health check route:

     Route::get('/pydio/health', function () {
         $client = new \GuzzleHttp\Client();
         try {
             $response = $client->get(config('pydio.base_api_url') . config('pydio.api_url'));
             return 'Pydio API reachable: ' . $response->getStatusCode();
         } catch (\Exception $e) {
             return 'Pydio API unreachable: ' . $e->getMessage();
         }
     });
     

4. Workspace/Folder IDs

   • IDs are strings, not integers. Passing an integer may cause silent failures.
   • Tip: Log returned IDs to verify format:

     $directories = $this->directoryService->listDirectories('workspace_id');
     Log::debug('Pydio Directory IDs:', array_keys($directories));
     

Debugging

• Enable Guzzle Debugging:

  $client = new \GuzzleHttp\Client([
      'debug' => true,
      'handler' => \GuzzleHttp\HandlerStack::create([
          new \GuzzleHttp\Middleware::tap(function ($request, $options) {
              Log::debug('Request:', [
                  'url' => (string) $request->getUri(),
                  'method' => $request->getMethod(),
                  'headers' => $request->getHeaders(),
              ]);
          }),
          new \GuzzleHttp\Middleware::tap(function ($response) {
              Log::debug('Response:', [
                  'status' => $response->getStatusCode(),
                  'body' => (string) $response->getBody(),
              ]);
          }),
      ]),
  ]);
  

• Test with Postman/cURL: Replicate API calls manually to isolate issues:

  curl -X GET "http://myPydioInstance/pydio/api/v2/workspace/workspace_id/directory" \
       -u "pydioLogin:pydioPassword"
  

Extension Points

1. Custom Services Extend existing services (e.g., add shareService for Pydio’s sharing API):

   namespace App\Service;
   
   use A5sys\PydioBundle\Service\AbstractService;
   
   class ShareService extends AbstractService
   {
       protected $endpoint = 'share';
   
       public function createShare($workspaceId, $fileId, $options)
       {
           return $this->post($workspaceId, $fileId, $options);
       }
   }
   

   Register in config/services.yaml:

   services:
       App\Service\ShareService:
           arguments:
               $client: '@pydio.http_client'
               $baseUrl: '%pydio.base_api_url%'
               $apiUrl: '%pydio.api_url%'
   

2. Event Listeners Listen for Pydio API events (e.g., file uploads) using Symfony’s event dispatcher:

   namespace App\EventListener;
   
   use A5sys\PydioBundle\Event\FileUploadedEvent;
   
   class PydioEventListener
   {
       public function onFileUploaded(FileUploadedEvent $event)
       {
           Log::info('File uploaded to Pydio:', [
               'file_id' => $event->getFileId(),
               'workspace' => $event->getWorkspaceId(),
           ]);
       }
   }
   

   Bind in config/services.yaml:

   services:
       App\Event