Ontheio Bundle Laravel Package

Getting Started

Minimal Steps

1. Verify API Availability: Confirm i.onthe.io is still operational for your use case (despite the 2017 deprecation note). If unavailable, evaluate alternatives like AWS S3, Imgix, or Cloudinary.
2. Installation:

   composer require devmachine/ontheio-bundle:~1.0
   

3. Kernel Registration: Add the bundle to app/AppKernel.php under registerBundles():

   new Devmachine\Bundle\OntheioBundle\DevmachineOntheioBundle(),
   new Sensio\Bundle\BuzzBundle\SensioBuzzBundle(), // Required dependency
   

4. Configuration: Set API credentials in config.yml:

   devmachine_ontheio:
       image:
           key: "%ontheio_api_key%"
           secret: "%ontheio_api_secret%"
   

5. First Use Case: Upload a remote image URL:

   use Devmachine\Bundle\OntheioBundle\Service\OntheioService;
   
   $service = $this->get('devmachine_ontheio.service');
   $url = 'https://example.com/image.jpg';
   $response = $service->uploadUrl($url);
   

Implementation Patterns

Core Workflows

1. URL Uploads: Use uploadUrl() to convert remote URLs to cloud-hosted assets:

   $service->uploadUrl('https://example.com/photo.png', ['width' => 800]);
   

   • Supports optional parameters like width, height, format, and quality.

2. Direct File Uploads: Stream local files via uploadFile():

   $filePath = storage_path('app/image.jpg');
   $service->uploadFile($filePath, ['crop' => 'fill']);
   

3. Image Processing: Chain transformations (e.g., resize + watermark):

   $service->uploadUrl($url, [
       'resize' => 'fit',
       'width'  => 600,
       'watermark' => 'http://example.com/watermark.png'
   ]);
   

4. Service Integration:

   • Symfony Events: Trigger post-upload logic via kernel.request listeners.
   • Form Handling: Use with VichUploaderBundle for file uploads:

     $form->add('image', FileType::class, [
         'mapped' => false,
         'constraints' => new File\FileType(['mimeTypes' => ['image/jpeg']]),
     ]);
     

Advanced Patterns

• Caching Responses: Store API responses in Redis/Memcached to avoid redundant calls.
• Fallback Logic: Implement a decorator pattern to switch providers dynamically:

  class FallbackOntheioService implements OntheioServiceInterface {
      public function uploadUrl($url, array $options = []) {
          try {
              return $this->ontheioService->uploadUrl($url, $options);
          } catch (Exception $e) {
              return $this->alternativeService->upload($url, $options);
          }
      }
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated API:

   • The bundle assumes i.onthe.io is active. Test thoroughly or replace the service URL in the bundle’s OntheioService class.
   • Override the service to mock responses during development:

     # config/services.yml
     devmachine_ontheio.service:
         class: AppBundle\Service\MockOntheioService
     

2. SensioBuzz Dependency:

   • The bundle relies on Sensio\Bundle\BuzzBundle for HTTP requests. Ensure it’s registered and configured for retries/timeouts:

     sensio_framework_extra:
         buzz:
             client:
                 timeout: 30
                 retries: 3
     

3. Configuration Sensitivity:

   • API keys/secrets are exposed in config.yml. Use environment variables:

     devmachine_ontheio:
         image:
             key: "%env(Ontheio_API_KEY)%"
             secret: "%env(Ontheio_API_SECRET)%"
     

4. Error Handling:

   • The bundle throws generic RuntimeExceptions. Extend the service to catch specific errors (e.g., Ontheio\Exception\ApiException):

     try {
         $service->uploadUrl($url);
     } catch (Exception $e) {
         if ($e->getCode() === 403) {
             // Handle forbidden access
         }
     }
     

Debugging Tips

• Enable Buzz Logging: Add to config.yml to log API requests:

  sensio_framework_extra:
      buzz:
          client:
              plugins:
                  - Sensio\Bundle\FrameworkExtraBundle\Buzz\Client\LoggerPlugin
  

• Inspect Responses: Dump raw API responses for debugging:

  $response = $service->uploadUrl($url);
  file_put_contents(storage_path('debug/ontheio_response.json'), $response->getContent());
  

Extension Points

1. Custom Endpoints: Override the base URL in the service:

   class CustomOntheioService extends OntheioService {
       protected $baseUrl = 'https://your-custom-endpoint.com';
   }
   

2. New Transformations: Extend the OntheioService to support additional parameters:

   public function uploadUrl($url, array $options = []) {
       $options['custom_param'] = 'value';
       return parent::uploadUrl($url, $options);
   }
   

3. Event Dispatching: Trigger events after uploads (e.g., for analytics):

   use Symfony\Component\EventDispatcher\EventDispatcherInterface;
   
   class EventfulOntheioService extends OntheioService {
       public function __construct(EventDispatcherInterface $dispatcher) {
           $this->dispatcher = $dispatcher;
       }
   
       public function uploadUrl($url, array $options = []) {
           $response = parent::uploadUrl($url, $options);
           $this->dispatcher->dispatch(new ImageUploadEvent($response));
           return $response;
       }
   }