Feature: UUID support

database/factories/FileSystemItemFactory.php

@@ -88,7 +88,7 @@ public function inFolder(FileSystemItem $folder): static
         ]);
     }
 
-    public function withParent(?int $parentId): static
+    public function withParent(int|string|null $parentId): static
     {
         return $this->state(fn (array $attributes) => [
             'parent_id' => $parentId,

src/Adapters/DatabaseAdapter.php

@@ -9,6 +9,7 @@
 use MWGuerra\FileManager\Contracts\FileManagerAdapterInterface;
 use MWGuerra\FileManager\Contracts\FileManagerItemInterface;
 use MWGuerra\FileManager\Contracts\FileSystemItemInterface;
+use Ramsey\Uuid\Uuid;
 
 /**
  * Database adapter for file management.
@@ -54,23 +55,35 @@ protected function model(): string
     }
 
     /**
-     * Find a model by ID.
+     * Find a model by ID (supports both integer and UUID).
      */
-    protected function find(int $id): ?FileSystemItemInterface
+    protected function find(int|string $id): ?FileSystemItemInterface
     {
         return $this->model()::find($id);
     }
 
+    /**
+     * Check if a string looks like a valid UUID.
+     */
+    protected function isUuid(string $value): bool
+    {
+        return Uuid::isValid($value);
+    }
+
     /**
      * Convert identifier to model.
-     * In database mode, identifier is the model ID.
+     * In database mode, identifier is the model ID (int or UUID).
      */
     protected function getModelFromIdentifier(string $identifier): ?FileSystemItemInterface
     {
         if (is_numeric($identifier)) {
             return $this->find((int) $identifier);
         }
 
+        if ($this->isUuid($identifier)) {
+            return $this->find($identifier);
+        }
+
         return null;
     }
 
@@ -79,10 +92,10 @@ protected function getModelFromIdentifier(string $identifier): ?FileSystemItemIn
      * For database mode, we need to resolve the path to a folder ID.
      *
      * This method is optimized to avoid N+1 queries by:
-     * 1. Short-circuiting for numeric IDs
+     * 1. Short-circuiting for numeric IDs and UUIDs
      * 2. Using recursive path traversal when needed
      */
-    protected function pathToFolderId(?string $path): ?int
+    protected function pathToFolderId(?string $path): int|string|null
     {
         if ($path === null || $path === '' || $path === '/') {
             return null;
@@ -93,6 +106,11 @@ protected function pathToFolderId(?string $path): ?int
             return (int) $path;
         }
 
+        // Path might be a UUID
+        if ($this->isUuid($path)) {
+            return $path;
+        }
+
         // Normalize path
         $path = '/' . ltrim($path, '/');
 
@@ -107,7 +125,7 @@ protected function pathToFolderId(?string $path): ?int
      * 1. It only queries folders at each level of the path
      * 2. It stops as soon as a segment isn't found
      */
-    protected function resolvePathToId(string $path): ?int
+    protected function resolvePathToId(string $path): int|string|null
     {
         // Split path into segments
         $segments = array_filter(explode('/', $path), fn ($s) => $s !== '');

src/Console/Commands/RebuildFileSystemItemsCommand.php

@@ -132,7 +132,7 @@ public function handle(): int
     /**
      * Recursively scan a directory and create database records.
      */
-    protected function scanDirectory($storage, string $modelClass, string $path, ?int $parentId): void
+    protected function scanDirectory($storage, string $modelClass, string $path, int|string|null $parentId): void
     {
         // Get directories and files
         $directories = $storage->directories($path);

src/Console/Commands/UploadFolderCommand.php

@@ -188,7 +188,7 @@ protected function countLocalItems(string $path): array
     /**
      * Ensure target folder exists in storage and database.
      */
-    protected function ensureTargetFolder(string $modelClass, $storage, string $target): ?int
+    protected function ensureTargetFolder(string $modelClass, $storage, string $target): int|string|null
     {
         $parts = array_filter(explode('/', $target));
         $parentId = null;
@@ -237,7 +237,7 @@ protected function uploadDirectory(
         $storage,
         string $storagePath,
         ?string $modelClass,
-        ?int $parentId
+        int|string|null $parentId
     ): void {
         $items = File::files($localPath);
         $directories = File::directories($localPath);

src/Contracts/FileSystemItemInterface.php

@@ -90,17 +90,17 @@ public function getFormattedDuration(): string;
     /**
      * Get folder tree structure for sidebar.
      */
-    public static function getFolderTree(?int $parentId = null): array;
+    public static function getFolderTree(int|string|null $parentId = null): array;
 
     /**
      * Get items in a folder (by parent_id).
      */
-    public static function getItemsInFolder(?int $parentId = null): Collection;
+    public static function getItemsInFolder(int|string|null $parentId = null): Collection;
 
     /**
      * Count direct files in a folder (static version for null parent).
      */
-    public static function getDirectFileCountForFolder(?int $folderId): int;
+    public static function getDirectFileCountForFolder(int|string|null $folderId): int;
 
     /**
      * Determine file type from mime type.

src/Filament/Pages/FileManager.php

@@ -387,7 +387,7 @@ public function navigateTo(?string $path): void
     /**
      * Navigate to folder by ID (for database mode compatibility).
      */
-    public function navigateToId(?int $folderId): void
+    public function navigateToId(int|string|null $folderId): void
     {
         $this->currentPath = $folderId ? (string) $folderId : null;
         $this->selectedItems = [];

src/Models/FileSystemItem.php

@@ -288,7 +288,7 @@ public function getFileCountRecursive(): int
     /**
      * Count direct files in a folder (static version for null parent).
      */
-    public static function getDirectFileCountForFolder(?int $folderId): int
+    public static function getDirectFileCountForFolder(int|string|null $folderId): int
     {
         return static::where('parent_id', $folderId)
             ->where('type', '!=', FileSystemItemType::Folder->value)
@@ -298,7 +298,7 @@ public static function getDirectFileCountForFolder(?int $folderId): int
     /**
      * Count all files in a folder and its descendants (static version for null parent).
      */
-    public static function getFileCountForFolder(?int $folderId): int
+    public static function getFileCountForFolder(int|string|null $folderId): int
     {
         if ($folderId === null) {
             // Root: count all files in the system
@@ -312,7 +312,7 @@ public static function getFileCountForFolder(?int $folderId): int
     /**
      * Get folder tree structure for sidebar.
      */
-    public static function getFolderTree(?int $parentId = null): array
+    public static function getFolderTree(int|string|null $parentId = null): array
     {
         $folders = static::where('type', FileSystemItemType::Folder->value)
             ->where('parent_id', $parentId)
@@ -333,7 +333,7 @@ public static function getFolderTree(?int $parentId = null): array
     /**
      * Get items in a folder (by parent_id).
      */
-    public static function getItemsInFolder(?int $parentId = null): \Illuminate\Database\Eloquent\Collection
+    public static function getItemsInFolder(int|string|null $parentId = null): \Illuminate\Database\Eloquent\Collection
     {
         return static::where('parent_id', $parentId)
             ->orderByRaw("CASE WHEN type = '" . FileSystemItemType::Folder->value . "' THEN 0 ELSE 1 END")