Cdn Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require docdigital/cdn-bundle:dev-master
   

   (Note: Use dev-master as the package lacks stable releases.)

2. Enable the Bundle Add to AppKernel.php:

   new DocDigital\Bundle\CdnBundle\DdCdnBundle(),
   

3. Configure Upload Directory In app/config/parameters.yml:

   parameters:
       dd_cdn.upload.dir: "%kernel.root_dir%/../media/"
   

   Ensure the directory exists and has write permissions for your web server user (e.g., www-data or apache).

4. First Use Case: File Upload Inject the CdnManager service in a controller/service:

   use DocDigital\Bundle\CdnBundle\Manager\CdnManager;
   
   class UploadController extends Controller
   {
       public function uploadAction(Request $request, CdnManager $cdnManager)
       {
           $file = $request->files->get('file');
           $path = $cdnManager->upload($file, 'user_uploads'); // 'user_uploads' = subdirectory
           return new Response("File saved at: $path");
       }
   }
   

Implementation Patterns

Core Workflows

1. File Uploads

   • Use CdnManager::upload() to store files in media/{subdir}/.
   • Example:

     $cdnManager->upload($file, 'avatars', 'unique_filename.png');
     

     (Omit filename to auto-generate.)

2. File Downloads

   • Use CdnManager::getUrl() to generate public URLs:

     $url = $cdnManager->getUrl('avatars/unique_filename.png');
     

   • Symlink files to a public directory (e.g., web/media) for direct access:

     $cdnManager->symlink('avatars/unique_filename.png', 'public_media');
     

3. Subdirectories

   • Organize files by category (e.g., users/, products/):

     $cdnManager->upload($file, 'products/123');
     

4. Deletion

   • Remove files via:

     $cdnManager->delete('avatars/old_file.png');
     

Integration Tips

• Symlinks for Public Access Configure a cron job or event listener to periodically symlink files to web/media/ for direct HTTP access:

  $cdnManager->symlinkAll('media/', 'web/media');
  

• Validation Validate file types/sizes before upload:

  if ($file->getClientOriginalExtension() !== 'png') {
      throw new \InvalidArgumentException('Only PNG allowed.');
  }
  

• Event Listeners Trigger actions post-upload (e.g., image resizing):

  $cdnManager->upload($file, 'thumbnails')->then(function($path) {
      // Resize logic here
  });
  

Gotchas and Tips

Pitfalls

1. Permissions

   • Issue: Uploads fail silently if media/ lacks write permissions for the web server user.
   • Fix: Run chown -R www-data:www-data media/ (Linux) or adjust parameters.yml to a writable directory.

2. Symlink Conflicts

   • Issue: Symlinking to web/media may cause conflicts if files are manually added to web/.
   • Fix: Use a subdirectory (e.g., web/cdn_media) or validate symlinks before creation.

3. No CDN Integration

   • Issue: The bundle manages local storage only; no built-in CDN (e.g., AWS S3) support.
   • Workaround: Extend the CdnManager or use a separate service for CDN uploads.

4. Filename Collisions

   • Issue: Auto-generated filenames may collide if not unique.
   • Fix: Use uniqid() or UUIDs:

     $cdnManager->upload($file, 'uploads', uniqid().'.'.$file->getClientOriginalExtension());
     

5. No File Overwrite Protection

   • Issue: upload() overwrites files by default.
   • Fix: Append timestamps or use File::exists() checks.

Debugging

• Log Upload Paths Enable debug mode to log paths:

  $this->get('logger')->debug('Uploaded to:', [$path]);
  

• Check File Existence Verify files exist post-upload:

  if (!file_exists($cdnManager->getPath('avatars/test.png'))) {
      throw new \RuntimeException('File not saved.');
  }
  

Extension Points

1. Custom Storage Override CdnManager to support S3 or other storage:

   class CustomCdnManager extends CdnManager {
       public function upload($file, $subdir = null, $filename = null) {
           // Custom logic (e.g., S3 upload)
       }
   }
   

2. Events Dispatch events for uploads/deletions:

   $event = new FileUploadEvent($file, $path);
   $this->get('event_dispatcher')->dispatch('cdn.upload', $event);
   

3. Configuration Dynamically set upload dirs via dependency injection:

   services:
       cdn.manager:
           arguments:
               - "%dd_cdn.upload.dir%"