Merge pull request #20 from ElegantEngineeringTech/v4

adjust children regeneration logic

Author: QuentinGab

README.md

@@ -40,6 +40,7 @@ I developed this package with the highest degree of flexibility possible and I h
     - [Delayed conversions](#delayed-conversions)
     - [`onAdded` MediaCollection Callback](#onadded-mediacollection-callback)
     - [`onCompleted` MediaConversionDefinition Callback](#oncompleted-mediaconversiondefinition-callback)
+    - [Regenerate children conversions on parent execution](#regenerate-children-conversions-when-parent-is-executed)
     - [Custom conversions](#custom-conversions)
     - [Manually generate conversions](#manually-generate-conversions)
     - [Format Media Url](#format-media-url)
@@ -505,10 +506,6 @@ new MediaCollection(
                 width: 360
             )
         ),
-        new MediaConversionImage(
-            name: '360',
-            width: 360,
-        )
     ]
 )
 ```
@@ -557,7 +554,7 @@ The `onCompleted` callback allows you to define custom logic that will be execut
 To use it, simply set the `onCompleted` parameter when defining a `MediaConversionDefinition`. For example:
 
 ```php
-new MediaConversionImage(
+new MediaConversionDefinition(
     name: '360',
     onCompleted: function ($conversion, $media, $parent) {
         // Example: Refresh your UI
@@ -571,6 +568,44 @@ This allows you to hook into the conversion process and execute additional logic
 > [!TIP]
 > The same behavior can be achieved by listening to `Elegantly\Media\Events\MediaConversionAddedEvent`.
 
+### Regenerating Child Conversions When a Parent Runs
+
+In some cases, you may want all **child conversions** of a given conversion to be **regenerated whenever the parent conversion is re-executed**.
+
+There are two ways to achieve this, depending on where you handle conversions:
+
+#### From the conversion definition
+
+You can hook into the `onCompleted` callback of a conversion definition and instruct Laravel to delete all child conversions when the parent finishes.
+
+```php
+new MediaConversionDefinition(
+    name: '360',
+    onCompleted: function (?MediaConversion $conversion, Media $media, ?MediaConversion $parent) {
+        if ($conversion) {
+            // Delete any children so they’ll be regenerated automatically
+            $media->deleteChildrenConversions($conversion->conversion_name);
+        }
+    }
+);
+```
+
+#### From `addConversion`
+
+When adding a new conversion programmatically, you can explicitly tell it to remove children and regenerate them automatically:
+
+```php
+$mediaConversion = $media->addConversion(
+    file: $file,
+    deleteChildren: true, // ensures child conversions are refreshed
+);
+
+// regenerate children conversion
+$this->media->generateConversions(
+    parent: $mediaConversion,
+);
+```
+
 ### Custom Conversions
 
 Conversions can be anything: a variant of a file, a transcription of a video, a completely new file, or even just a string.

src/Converters/MediaConverter.php

@@ -150,6 +150,10 @@ public function handle(): ?MediaConversion
             return $this->convert($this->media, $parent, $copy, $storage, $temporaryDirectory);
         });
 
+        if ($onCompleted = $definition->onCompleted) {
+            $onCompleted($mediaConversion, $this->media, $parent);
+        }
+
         if (
             $mediaConversion &&
             $mediaConversion->state === MediaConversionState::Succeeded &&

src/Models/Media.php

@@ -20,8 +20,6 @@
 use Elegantly\Media\Traits\HasUuid;
 use Elegantly\Media\UrlFormatters\AbstractUrlFormatter;
 use Exception;
-use Illuminate\Database\Eloquent\Casts\ArrayObject;
-use Illuminate\Database\Eloquent\Casts\AsArrayObject;
 use Illuminate\Database\Eloquent\Casts\Attribute;
 use Illuminate\Database\Eloquent\Collection as EloquentCollection;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
@@ -40,7 +38,7 @@
  * @property ?string $collection_group
  * @property ?string $average_color
  * @property ?int $order_column
- * @property ?ArrayObject<array-key, mixed> $metadata
+ * @property ?array<array-key, mixed> $metadata
  * @property ?InteractWithMedia<Media> $model
  * @property ?string $model_type
  * @property ?int $model_id
@@ -67,14 +65,17 @@ class Media extends Model
     protected $appends = ['url'];
 
     /**
-     * @var array<string, string>
+     * @return array<string, string>
      */
-    protected $casts = [
-        'type' => MediaType::class,
-        'metadata' => AsArrayObject::class,
-        'duration' => 'float',
-        'aspect_ratio' => 'float',
-    ];
+    public function casts(): array
+    {
+        return [
+            'type' => MediaType::class,
+            'metadata' => 'array',
+            'duration' => 'float',
+            'aspect_ratio' => 'float',
+        ];
+    }
 
     public static function booted()
     {
@@ -407,6 +408,8 @@ public function replaceConversion(MediaConversion $conversion): MediaConversion
      * Store a file as a conversion and dispatch children conversions
      *
      * @param  string|resource|UploadedFile|HttpFile  $file
+     * @param  array<array-key, mixed>  $metadata
+     * @param  array<array-key, mixed>  $attributes
      */
     public function addConversion(
         $file,
@@ -415,7 +418,9 @@ public function addConversion(
         ?string $name = null,
         ?string $destination = null,
         ?string $disk = null,
-        bool $regenerateChildren = true
+        ?array $metadata = null,
+        array $attributes = [],
+        bool $deleteChildren = false
     ): MediaConversion {
         /**
          * Prefix name with parent if not already done
@@ -441,8 +446,26 @@ public function addConversion(
 
         $conversion->conversion_name = $conversionName;
         $conversion->media_id = $this->id;
+
+        // reset values
+        $conversion->type = null;
+        $conversion->name = null;
+        $conversion->extension = null;
+        $conversion->file_name = null;
+        $conversion->mime_type = null;
+        $conversion->width = null;
+        $conversion->height = null;
+        $conversion->aspect_ratio = null;
+        $conversion->duration = null;
+        $conversion->average_color = null;
+        $conversion->size = null;
+        $conversion->contents = null;
+
         $conversion->state = MediaConversionState::Succeeded;
         $conversion->state_set_at = now();
+        $conversion->metadata = $metadata;
+        $conversion->created_at = now();
+        $conversion->fill($attributes);
 
         $conversion->storeFile(
             file: $file,
@@ -458,22 +481,12 @@ public function addConversion(
             ) {
                 $existingConversionReplicate->deleteFile();
             }
-
-            if ($regenerateChildren) {
-                /**
-                 * Because the conversion has been regenerated, its children are not up to date anymore
-                 */
-                $this->deleteChildrenConversions($conversionName);
-            }
-
         } else {
             $this->conversions->push($conversion);
         }
 
-        $definition = $this->getConversionDefinition($conversionName);
-
-        if ($onCompleted = $definition?->onCompleted) {
-            $onCompleted($conversion, $this, $parent);
+        if ($deleteChildren) {
+            $this->deleteChildrenConversions($conversionName);
         }
 
         event(new MediaConversionAddedEvent($conversion));

src/Models/MediaConversion.php

@@ -15,8 +15,6 @@
 use Elegantly\Media\TemporaryDirectory;
 use Elegantly\Media\Traits\HasUuid;
 use Exception;
-use Illuminate\Database\Eloquent\Casts\ArrayObject;
-use Illuminate\Database\Eloquent\Casts\AsArrayObject;
 use Illuminate\Database\Eloquent\Casts\Attribute;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
@@ -45,7 +43,7 @@
  * @property ?int $size
  * @property ?float $duration
  * @property ?string $contents Arbitrary stored value
- * @property ?ArrayObject<array-key, mixed> $metadata
+ * @property ?array<array-key, mixed> $metadata
  * @property int $media_id
  * @property Media $media
  * @property Carbon $created_at
@@ -71,7 +69,7 @@ public function casts()
     {
         return [
             'type' => MediaType::class,
-            'metadata' => AsArrayObject::class,
+            'metadata' => 'array',
             'duration' => 'float',
             'aspect_ratio' => 'float',
             'state' => MediaConversionState::class,

tests/Feature/MediaTest.php

@@ -293,6 +293,7 @@
         file: $file,
         conversionName: 'poster',
         name: 'new-poster',
+        deleteChildren: true
     );
 
     foreach ($children as $child) {