add path generator

Author: QuentinGab

README.md

@@ -91,68 +91,107 @@ This is the contents of the published config file:
 ```php
 use Elegantly\Media\Jobs\DeleteModelMediaJob;
 use Elegantly\Media\Models\Media;
+use Elegantly\Media\Models\MediaConversion;
+use Elegantly\Media\PathGenerators\UuidPathGenerator;
+use Elegantly\Media\UrlFormatters\DefaultUrlFormatter;
 
 return [
     /**
-     * The media model
-     * Define your own model here by extending \Elegantly\Media\Models\Media::class
+     * The media model.
+     * Define your own model here by extending \Elegantly\Media\Models\Media::class.
      */
     'model' => Media::class,
 
     /**
-     * The path used to store temporary file copy for conversions
-     * This will be used with storage_path() function
+     * The MediaConversion model.
+     * Define your own model here by extending \Elegantly\Media\Models\MediaConversion::class.
+     */
+    'media_conversion_model' => MediaConversion::class,
+
+    /**
+     * The path used to store temporary file copies for conversions.
+     * This will be used with the storage_path() function.
      */
     'temporary_storage_path' => 'app/tmp/media',
 
     /**
-     * The default disk used for storing files
+     * The default disk used for storing files.
      */
     'disk' => env('MEDIA_DISK', env('FILESYSTEM_DISK', 'local')),
 
     /**
      * Determine if media should be deleted with the model
-     * when using the HasMedia Trait
+     * when using the HasMedia Trait.
      */
     'delete_media_with_model' => true,
 
     /**
      * Determine if media should be deleted with the model
-     * when it is soft deleted
+     * when it is soft deleted.
      */
     'delete_media_with_trashed_model' => false,
 
     /**
-     * Deleting a large number of media attached to a model can be time-consuming
-     * or even fail (e.g., cloud API error, permissions, etc.)
-     * For performance and monitoring, when a model with the HasMedia trait is deleted,
-     * each media is individually deleted inside a job.
+     * Job class responsible for deleting media when the model is deleted.
+     * This helps with performance and monitoring by queuing media deletions.
      */
     'delete_media_with_model_job' => DeleteModelMediaJob::class,
 
     /**
-     * The default collection name
+     * The default collection name assigned media.
      */
     'default_collection_name' => 'default',
 
     /**
-     * Prefix for the generated path of files
-     * Set to null if you do not want any prefix
-     * To fully customize the generated default path, extend the Media model and override the generateBasePath method
+     * The default URL formatter class.
+     * Used when calling `$media->getUrl()`.
+     */
+    'default_url_formatter' => DefaultUrlFormatter::class,
+
+    /**
+     * The default path generator class.
+     * Used when storing new files.
+     */
+    'default_path_generator' => UuidPathGenerator::class,
+
+    /**
+     * Prefix for the generated file path.
+     * Set to null to disable the prefix.
+     * Override the generateBasePath method in the Media model for full customization.
      */
     'generated_path_prefix' => null,
 
     /**
-     * Customize the queue connection used when dispatching conversion jobs
+     * Queue connection name to use when dispatching media conversion jobs.
      */
     'queue_connection' => env('QUEUE_CONNECTION', 'sync'),
 
     /**
-     * Customize the queue used when dispatching conversion jobs
-     * null will fall back to the default Laravel queue
+     * Queue name to use for media conversion jobs.
+     * Set to null to use the default Laravel queue.
      */
     'queue' => null,
 
+    /**
+     * Configuration for FFmpeg processing.
+     */
+    'ffmpeg' => [
+        /**
+         * The binary path to the FFmpeg executable.
+         */
+        'ffmpeg_binaries' => env('FFMPEG_BINARIES', 'ffmpeg'),
+
+        /**
+         * The binary path to the FFprobe executable.
+         */
+        'ffprobe_binaries' => env('FFPROBE_BINARIES', 'ffprobe'),
+
+        /**
+         * Optional log channel for FFmpeg operations.
+         * Set to null to disable logging.
+         */
+        'log_channel' => null,
+    ],
 ];
 ```
 

config/media.php

@@ -5,6 +5,7 @@
 use Elegantly\Media\Jobs\DeleteModelMediaJob;
 use Elegantly\Media\Models\Media;
 use Elegantly\Media\Models\MediaConversion;
+use Elegantly\Media\PathGenerators\UuidPathGenerator;
 use Elegantly\Media\UrlFormatters\DefaultUrlFormatter;
 
 return [
@@ -60,6 +61,12 @@
      */
     'default_url_formatter' => DefaultUrlFormatter::class,
 
+    /**
+     * The default path generator class.
+     * Used when storing new files.
+     */
+    'default_path_generator' => UuidPathGenerator::class,
+
     /**
      * Prefix for the generated file path.
      * Set to null to disable the prefix.

src/FileDownloaders/HttpFileDownloader.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Elegantly\Media\HttpFileDownloaders;
+namespace Elegantly\Media\FileDownloaders;
 
 use Elegantly\Media\Helpers\File;
 use Illuminate\Support\Facades\Http;

src/Models/Media.php

@@ -13,9 +13,10 @@
 use Elegantly\Media\Enums\MediaType;
 use Elegantly\Media\Events\MediaConversionAddedEvent;
 use Elegantly\Media\Events\MediaFileStoredEvent;
+use Elegantly\Media\FileDownloaders\HttpFileDownloader;
 use Elegantly\Media\Helpers\File;
-use Elegantly\Media\HttpFileDownloaders\HttpFileDownloader;
 use Elegantly\Media\MediaConversionDefinition;
+use Elegantly\Media\PathGenerators\AbstractPathGenerator;
 use Elegantly\Media\TemporaryDirectory;
 use Elegantly\Media\Traits\HasUuid;
 use Elegantly\Media\UrlFormatters\AbstractUrlFormatter;
@@ -162,7 +163,10 @@ public function storeFileFromHttpFile(
         ?Closure $before = null,
     ): static {
 
-        $destination ??= $this->getDefaultPath();
+        /** @var class-string<AbstractPathGenerator> */
+        $pathGenerator = config('media.default_path_generator');
+
+        $destination ??= (new $pathGenerator)->media($this)->value();
         $name ??= File::name($file) ?? Str::random(6);
         $disk ??= config()->string('media.disk', config()->string('filesystems.default', 'local'));
 
@@ -417,6 +421,10 @@ public function addConversion(
         array $attributes = [],
         bool $deleteChildren = false
     ): MediaConversion {
+
+        /** @var class-string<AbstractPathGenerator> */
+        $pathGenerator = config('media.default_path_generator');
+
         /**
          * Prefix name with parent if not already done
          */
@@ -446,7 +454,7 @@ public function addConversion(
 
         $conversion->storeFile(
             file: $file,
-            destination: $destination ?? $this->getDefaultPath($conversionName),
+            destination: $destination ?? (new $pathGenerator)->conversion($this, $conversion)->value(),
             name: $name,
             disk: $disk ?? $this->disk
         );
@@ -558,45 +566,6 @@ public function deleteChildrenConversions(string $conversionName): static
 
     // \ Managing Conversions ----------------------------------------------------------
 
-    /** @deprecated use getDefaultPath */
-    public function makeFreshPath(
-        ?string $conversion = null,
-        ?string $fileName = null
-    ): string {
-        return $this->getDefaultPath($conversion, $fileName);
-    }
-
-    /**
-     * Default path where files will be put
-     * Ex: root files
-     * /{prefix}/uuid/{fileName}
-     * Ex: conversion files
-     * /{prefix}/uuid/conversions/{conversion}/{fileName}
-     */
-    public function getDefaultPath(
-        ?string $conversion = null,
-        ?string $fileName = null
-    ): string {
-        /** @var string $prefix */
-        $prefix = config('media.generated_path_prefix') ?? '';
-
-        $root = Str::of($prefix)
-            ->when($prefix, fn ($string) => $string->finish('/'))
-            ->append($this->uuid)
-            ->finish('/');
-
-        if ($conversion) {
-            return $root
-                ->append('conversions/')
-                ->append(str_replace('.', '/conversions/', $conversion))
-                ->finish('/')
-                ->append($fileName ?? '')
-                ->value();
-        }
-
-        return $root->append($fileName ?? '')->value();
-    }
-
     /**
      * @param  array<array-key, float|int|string>  $keys
      * @param  null|(Closure(null|int $previous): int)  $sequence

src/Models/MediaConversion.php

@@ -10,8 +10,8 @@
 use Elegantly\Media\Enums\MediaConversionState;
 use Elegantly\Media\Enums\MediaType;
 use Elegantly\Media\Events\MediaFileStoredEvent;
+use Elegantly\Media\FileDownloaders\HttpFileDownloader;
 use Elegantly\Media\Helpers\File;
-use Elegantly\Media\HttpFileDownloaders\HttpFileDownloader;
 use Elegantly\Media\TemporaryDirectory;
 use Elegantly\Media\Traits\HasUuid;
 use Exception;

src/PathGenerators/AbstractPathGenerator.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Elegantly\Media\PathGenerators;
+
+use Elegantly\Media\Models\Media;
+use Elegantly\Media\Models\MediaConversion;
+use Illuminate\Support\Stringable;
+
+abstract class AbstractPathGenerator
+{
+    public readonly ?string $prefix;
+
+    public function __construct(?string $prefix = null)
+    {
+        /** @var ?string */
+        $config = config('media.generated_path_prefix');
+
+        $this->prefix = $prefix ?? $config;
+    }
+
+    abstract public function media(Media $media): Stringable;
+
+    abstract public function conversion(Media $media, MediaConversion $mediaConversion): Stringable;
+
+    public function generate(
+        Media $media,
+        ?MediaConversion $mediaConversion,
+        string $fileName,
+    ): string {
+        if ($mediaConversion) {
+            return $this
+                ->conversion($media, $mediaConversion)
+                ->append($fileName)
+                ->value();
+        }
+
+        return $this
+            ->media($media)
+            ->append($fileName)
+            ->value();
+    }
+}

src/PathGenerators/UuidPathGenerator.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Elegantly\Media\PathGenerators;
+
+use Elegantly\Media\Models\Media;
+use Elegantly\Media\Models\MediaConversion;
+use Illuminate\Support\Stringable;
+
+class UuidPathGenerator extends AbstractPathGenerator
+{
+    /**
+     * Ex: {prefix}/{uuid}/
+     */
+    public function media(Media $media): Stringable
+    {
+        if ($this->prefix) {
+            return str($this->prefix)
+                ->finish('/')
+                ->append($media->uuid)
+                ->finish('/');
+        }
+
+        return str($media->uuid)->finish('/');
+    }
+
+    /**
+     * Adding the mediaConversion uuid ensure the cache is not used
+     *
+     * @example {prefix}/{uuid}/conversions/poster/{uuid}/
+     * @example {prefix}/{uuid}/conversions/poster/conversions/360/{uuid}
+     */
+    public function conversion(
+        Media $media,
+        MediaConversion $mediaConversion,
+    ): Stringable {
+
+        return $this->media($media)
+            ->append('conversions/')
+            ->append(str_replace('.', '/conversions/', $mediaConversion->conversion_name))
+            ->finish('/')
+            ->append($mediaConversion->uuid)
+            ->finish('/');
+    }
+}

tests/Feature/MediaTest.php

@@ -168,7 +168,7 @@
     expect($conversion->media_id)->toBe($media->id);
     expect($conversion->id)->not->toBe(null);
     expect($conversion->exists)->toBe(true);
-    expect($conversion->path)->toBe("{$media->uuid}/conversions/poster/poster.jpg");
+    expect($conversion->path)->toBe("{$media->uuid}/conversions/poster/{$conversion->uuid}/poster.jpg");
     expect($conversion->name)->toBe('poster');
     expect($conversion->extension)->toBe('jpg');
     expect($conversion->file_name)->toBe('poster.jpg');

tests/Unit/FileDownloaderTest.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-use Elegantly\Media\HttpFileDownloaders\HttpFileDownloader;
+use Elegantly\Media\FileDownloaders\HttpFileDownloader;
 use Spatie\TemporaryDirectory\TemporaryDirectory;
 
 it('download a file from an url as a temporary file', function () {