Feat: Creating Migration Models And Adapters for file Service

src/File/Services/FileService.php

@@ -0,0 +1,119 @@
+<?php
+
+namespace Modules\Core\File\Services;
+
+use Illuminate\Contracts\Container\Container;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
+use Modules\Core\File\Contracts\FileAdapterInterface;
+use Modules\Core\File\Models\File;
+use Symfony\Component\HttpFoundation\StreamedResponse;
+
+/**
+ * Orchestrates the `files` table (ownership, purpose, cleanup — see that
+ * migration's own docblock) on top of whichever FileAdapterInterface a
+ * disk resolves to (see Providers\FileServiceProvider's contextual
+ * binding) — never touches a disk or a raw path itself. Knows nothing
+ * about custom fields, carts, or orders specifically; every caller
+ * (3dealer's custom-field upload flow today, some other future
+ * file-upload need tomorrow) supplies its own `purpose` string and owner
+ * model, and scopes its own queries by them.
+ */
+class FileService
+{
+    public function __construct(
+        private readonly Container $container,
+    ) {}
+
+    public function store(UploadedFile $file, string $purpose, string $directory, string $disk = 'local'): File
+    {
+        $path = $this->adapter($disk)->store($file, $directory);
+
+        return File::create([
+            'disk' => $disk,
+            'path' => $path,
+            'original_name' => $file->getClientOriginalName(),
+            'mime' => $file->getMimeType(),
+            'size' => $file->getSize(),
+            'purpose' => $purpose,
+        ]);
+    }
+
+    /**
+     * Re-points an existing File at its owner — called once an owner
+     * actually exists (e.g. a shopper's picked-but-not-yet-added photo
+     * gets a CartLine the moment it's added to the cart). Never creates a
+     * second row for the same physical file.
+     */
+    public function attachOwner(File $file, Model $owner): File
+    {
+        $file->update([
+            'owner_type' => $owner->getMorphClass(),
+            'owner_id' => $owner->getKey(),
+        ]);
+
+        return $file;
+    }
+
+    public function retrieve(File $file): StreamedResponse
+    {
+        return $this->adapter($file->disk)->retrieve($file->path, $file->original_name);
+    }
+
+    public function exists(File $file): bool
+    {
+        return $this->adapter($file->disk)->exists($file->path);
+    }
+
+    public function delete(File $file): void
+    {
+        $this->adapter($file->disk)->delete($file->path);
+
+        $file->delete();
+    }
+
+    /**
+     * @return Collection<int, File>
+     */
+    public function list(string $purpose, ?Model $owner = null): Collection
+    {
+        return File::query()
+            ->where('purpose', $purpose)
+            ->when($owner, fn ($query) => $query
+                ->where('owner_type', $owner->getMorphClass())
+                ->where('owner_id', $owner->getKey()))
+            ->get();
+    }
+
+    /**
+     * Deletes every File of the given purpose that has no owner yet and
+     * is older than $olderThan — the grace period covers a shopper still
+     * on the page with a picked-but-not-yet-added file. An owned File
+     * (whatever the owner type) is never touched here; callers that want
+     * owned files gone too should delete() them explicitly wherever that
+     * ownership itself ends (e.g. a CartLine being removed).
+     *
+     * @return int number of files deleted
+     */
+    public function pruneUnowned(string $purpose, Carbon $olderThan): int
+    {
+        $files = File::query()
+            ->where('purpose', $purpose)
+            ->whereNull('owner_type')
+            ->where('created_at', '<', $olderThan)
+            ->get();
+
+        foreach ($files as $file) {
+            $this->delete($file);
+        }
+
+        return $files->count();
+    }
+
+    private function adapter(string $disk): FileAdapterInterface
+    {
+        return $this->container->make(FileAdapterInterface::class, ['disk' => $disk]);
+    }
+}