Php Opencloud Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require rackspace/php-opencloud

Ensure your project uses PHP 5.6+ (last maintained version). Note: PHP version checks are now handled by Composer.

2. Basic Configuration Create a service container instance with your OpenStack credentials:

   use OpenCloud\OpenStack;
   use OpenCloud\Common\ServiceBuilder;
   
   $config = [
       'username' => 'your-username',
       'password' => 'your-password',
       'tenantName' => 'your-tenant',
       'authUrl' => 'https://your-openstack-auth-url:5000/v3',
   ];
   
   $serviceBuilder = new ServiceBuilder();
   $serviceBuilder->addService('ObjectStore', 'rackspace', [
       'region' => 'your-region',
       'endpointType' => 'publicURL',
   ]);
   
   $openStack = new OpenStack($config, $serviceBuilder);
   

3. First Use Case: List Containers

   $objectStore = $openStack->objectStoreService('rackspace');
   $containers = $objectStore->listContainers();
   foreach ($containers as $container) {
       echo $container->name . "\n";
   }
   

Key Resources

• Official Documentation (Archive)
• OpenStack API Docs (for endpoint reference)
• src/OpenCloud/ directory (core classes and services)

Implementation Patterns

Common Workflows

1. Object Storage (Swift)

• Upload/Download Files

  $container = $objectStore->getContainer('my-container');
  $object = $container->uploadObject('file.txt', fopen('local-file.txt', 'r'));
  $content = $container->downloadObject('file.txt');
  

• Streaming Large Files

  $object = $container->uploadObject('large-file.zip', fopen('large-file.zip', 'r'), [
      'Content-Type' => 'application/zip',
  ], true); // Stream large files
  

• Delete Objects via Container

  $container = $objectStore->getContainer('my-container');
  $container->deleteObject('file.txt'); // New in v1.16.0
  

• Temporary URLs

  $tempUrl = $object->getTemporaryUrl('GET', '+1 hour'); // Fixed in v1.16.0
  

• Metadata Handling

  $object->setMetadata(['custom-key' => 'value']);
  $metadata = $object->getMetadata();
  

2. Compute (Nova)

• List Servers

  $compute = $openStack->computeService();
  $servers = $compute->listServers();
  foreach ($servers as $server) {
      echo $server->name . ' (Status: ' . $server->status . ')' . "\n";
  }
  

• Create Server with Ports/Security Groups

  $server = $compute->createServer([
      'name' => 'my-server',
      'imageRef' => 'image-id',
      'flavorRef' => 'flavor-id',
      'networks' => [['port' => 'port-id']], // New in v1.16.0
      'security_groups' => ['sg-id'], // New in v1.16.0
  ]);
  

• Server Metadata

  $server->setMetadata(['key' => 'value']); // Fixed in v1.16.0
  

3. Load Balancers (Octavia)

• Add Nodes Efficiently

  $loadBalancer = $openStack->loadBalancerService();
  $loadBalancer->addMember('lb-id', ['member' => ['address' => '1.2.3.4']]); // Refactored in v1.16.0
  

4. Identity (Keystone)

• List Users/Tenants

  $identity = $openStack->identityService();
  $users = $identity->listUsers();
  $tenants = $identity->listTenants();
  

Integration Tips

• Dependency Injection: Register the OpenStack instance in Laravel’s service container:

  $this->app->singleton('openstack', function ($app) {
      return new OpenStack(config('openstack.credentials'), $app['openstack.service_builder']);
  });
  

• Configuration: Store credentials in .env:

  OPENSTACK_USERNAME=your-username
  OPENSTACK_PASSWORD=your-password
  OPENSTACK_TENANT=your-tenant
  OPENSTACK_AUTH_URL=https://auth.example.com:5000/v3
  

• Error Handling: Wrap calls in try-catch for OpenCloud\Common\ServiceException:

  try {
      $objectStore->deleteContainer('my-container');
  } catch (\OpenCloud\Common\ServiceException $e) {
      Log::error('OpenStack Error: ' . $e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated API Versions

   • The package primarily supports OpenStack Grizzly (2013). Newer APIs (e.g., Pike, Queens) may require manual adjustments.
   • Fix: Check the OpenStack API versions and adjust endpoints/headers if needed.

2. Region/Endpoint Mismatch

   • Hardcoding endpoints (e.g., authUrl) can break across environments.
   • Fix: Use endpointType (publicURL, internalURL, adminURL) and validate regions:

     $serviceBuilder->addService('ObjectStore', 'rackspace', [
         'region' => 'DFW', // Rackspace region
         'endpointType' => 'publicURL',
     ]);
     

3. Token Expiry

   • Keystone tokens expire (~1 hour). Repeated requests may fail with 401 Unauthorized.
   • Fix: Implement token refresh logic or use long-lived credentials:

     if ($identity->getToken()->isExpired()) {
         $openStack->reauthenticate();
     }
     

4. Large File Handling

   • Uploading/downloading files >100MB may timeout or fail silently.
   • Fix: Use streaming ($object->uploadObject(..., true)) and increase PHP timeouts:

     ini_set('default_socket_timeout', 300); // 5 minutes
     

5. Case Sensitivity

   • Container/object names are case-sensitive in Swift. Debugging "not found" issues often requires checking casing.
   • Fix: Validate container names before operations:

     $containerName = strtolower(trim($containerName)); // Normalize
     

6. Server Creation Edge Cases

   • Port/Security Group Validation: Ensure ports and security groups exist before creating servers.
   • Metadata Limitations: Some OpenStack versions have metadata size limits (~2KB).

Debugging Tips

• Enable Debugging

  $serviceBuilder->setDebug(true); // Logs raw HTTP requests/responses
  

• Inspect Headers Add custom headers for troubleshooting:

  $object->setMetadata(['X-Object-Meta-Debug' => 'true']);
  

• Check Response Codes Always inspect $e->getResponse()->getStatusCode() in exceptions.
• Load Balancer Debugging Verify node additions with:

  $members = $loadBalancer->listMembers('lb-id');
  

Extension Points

1. Custom Services Extend OpenCloud\Common\Service to add support for unsupported services (e.g., Block Storage, Networking):

   class CustomService extends \OpenCloud\Common\Service {
       public function customMethod() { ... }
   }
   $serviceBuilder->addService('Custom', 'rackspace', ['class' => 'CustomService']);
   

2. Middleware Add request/response middleware for logging, retries, or auth:

   $serviceBuilder->addMiddleware(new class implements \OpenCloud\Common\Middleware {
       public function handle($request, \Closure $next) {
           // Pre-request logic
           $response = $next($request);
           // Post-response logic
           return $response;
       }
   });
   

3. Event Listeners Listen for service events (e.g., object uploads) via OpenCloud\Common\Event\Events:

   $serviceBuilder->addListener('object.upload', function ($event) {
       Log::info('Uploaded: ' . $event->getObject()->name);
   });
   

4. Temporary URL Generation Le