Dadatata Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require asoc/dadatata
   

   Publish the config (if needed) with:

   php artisan vendor:publish --provider="AStateOfCode\Dadatata\DadatataServiceProvider"
   

2. First Use Case: Metadata Extraction Extract metadata from a file (e.g., example.mp3):

   use AStateOfCode\Dadatata\File;
   use AStateOfCode\Dadatata\Extractors\MetadataExtractor;
   
   $file = new File('path/to/example.mp3');
   $metadata = (new MetadataExtractor())->extract($file);
   
   // Output metadata (e.g., duration, bitrate, etc.)
   dd($metadata);
   

3. Key Classes to Know

   • File: Represents a file with path, MIME type, and metadata.
   • Extractor: Base class for metadata/MIME extraction (e.g., MetadataExtractor, MimeTypeExtractor).
   • Filter: Base class for transformations (e.g., ImageResizeFilter, PdfConvertFilter).
   • Pipeline: Chains filters for sequential processing.

Implementation Patterns

Workflow: Processing a File Pipeline

1. Define a Pipeline Chain filters for a multi-step transformation (e.g., ODT → PDF → Thumbnail):

   use AStateOfCode\Dadatata\Pipeline;
   use AStateOfCode\Dadatata\Filters\PdfConvertFilter;
   use AStateOfCode\Dadatata\Filters\ImageThumbnailFilter;
   
   $pipeline = new Pipeline();
   $pipeline->add(new PdfConvertFilter()) // ODT → PDF
            ->add(new ImageThumbnailFilter()); // PDF → Thumbnail
   
   $result = $pipeline->process($file);
   

2. Conditional Filtering Use file categories (e.g., Image, Document) to dynamically apply filters:

   $mimeExtractor = new MimeTypeExtractor();
   $category = $mimeExtractor->getCategory($file);
   
   if ($category === 'Image') {
       $pipeline->add(new ImageResizeFilter(800, 600));
   }
   

3. CLI Tool Integration Leverage built-in wrappers (e.g., FFmpeg, Unoconv) for heavy lifting:

   use AStateOfCode\Dadatata\Tools\FFmpeg;
   
   $ffmpeg = new FFmpeg();
   $duration = $ffmpeg->getDuration($file);
   

4. Laravel Integration

   • Artisan Commands: Extend DadatataCommand for CLI tasks.
   • Jobs: Queue file processing with Laravel Queues:

     use AStateOfCode\Dadatata\Jobs\ProcessFilePipeline;
     
     ProcessFilePipeline::dispatch($file)->onQueue('media');
     

5. Custom Extractors/Filters Extend base classes to support new tools or formats:

   class CustomExtractor extends Extractor {
       public function extract(File $file) {
           // Custom logic (e.g., call external tool)
       }
   }
   

Gotchas and Tips

Pitfalls

1. Tool Dependencies

   • FFmpeg/Unoconv: Ensure system tools are installed and in $PATH. Configure paths in config/dadatata.php:

     'tools' => [
         'ffmpeg' => '/usr/local/bin/ffmpeg',
         'unoconv' => '/usr/bin/unoconv',
     ],
     

   • Debugging: Use Tool::isAvailable() to check if a tool is installed.

2. File Handling

   • Temporary Files: Filters may create temp files. Clean up with File::delete() or Laravel’s Storage facade.
   • Permissions: Ensure PHP has write permissions for output directories.

3. Pipeline Failures

   • Graceful Degradation: Wrap pipeline processing in a try-catch to handle tool failures:

     try {
         $result = $pipeline->process($file);
     } catch (ToolException $e) {
         Log::error("Pipeline failed: " . $e->getMessage());
         return back()->withError('Processing failed');
     }
     

4. Metadata Inconsistencies

   • Fallbacks: Combine multiple extractors (e.g., MetadataExtractor + MimeTypeExtractor) for robustness:

     $metadata = (new MetadataExtractor())->extract($file);
     $mime = (new MimeTypeExtractor())->getMimeType($file);
     

Tips

1. Performance

   • Cache Metadata: Store extracted metadata in Laravel’s cache or database to avoid repeated calls:

     $cacheKey = "metadata_{$file->getPath()}";
     $metadata = Cache::remember($cacheKey, now()->addHours(1), function() use ($file) {
         return (new MetadataExtractor())->extract($file);
     });
     

2. Testing

   • Mock Tools: Use Laravel’s Mockery to test filters without calling system tools:

     $mockFFmpeg = Mockery::mock('AStateOfCode\Dadatata\Tools\FFmpeg');
     $this->app->instance('AStateOfCode\Dadatata\Tools\FFmpeg', $mockFFmpeg);
     

3. Extending the Package

   • New Filters: Create a filter for unsupported formats (e.g., WebPResizeFilter) by extending Filter.
   • Contributing: Submit PRs for missing tools/formats. Check the GitHub issues.

4. Debugging

   • Verbose Output: Enable debug mode in config to log tool commands:

     'debug' => env('DADATATA_DEBUG', false),
     

   • Log Commands: Wrap tool calls in Log::debug() for troubleshooting.

5. Laravel Storage

   • Disk Integration: Use Laravel’s Storage facade to read/write files:

     $filePath = Storage::disk('public')->path('uploads/example.mp3');
     $file = new File($filePath);