add documentation

Author: imahmood

docs/events.md

@@ -0,0 +1,8 @@
+## Events
+
+The system currently supports the following events:
+
+| Name | Passed params | Description |
+|------|---------------|-------------|
+| AfterMediaSaved | Media | Triggered after a media entity has been successfully saved. |
+| AfterMediaUploaded | Media | Triggered upon the successful upload. |

docs/getting-url.md

@@ -0,0 +1,27 @@
+## Getting a file URL
+
+```php
+// Retrieve the media instance from the specified relation in the model.
+
+$media = $user->avatar;
+```
+
+```php
+// Gets the URL to the original file.
+echo $media->original_url;
+
+// Gets the URL to the preview version of the file.
+echo $media->preview_url;
+
+// Gets the relative path to the original file.
+echo $media->original_relative_path;
+
+// Gets the absolute path to the original file.
+echo $media->original_absolute_path;
+
+// Gets the relative path to the preview version of the file.
+echo $media->preview_relative_path;
+
+// Gets the absolute path to the preview version of the file.
+echo $media->preview_absolute_path;
+```

docs/installation.md

@@ -0,0 +1,19 @@
+## Installation
+
+### 1. Install the package via Composer:
+
+```
+composer require imahmood/laravel-file-storage
+```
+
+### 2. Publish the configuration file:
+
+```bash
+php artisan vendor:publish --provider="Imahmood\FileStorage\FileStorageServiceProvider"
+```
+
+### 3. Run migrations:
+
+```bash
+php artisan migrate
+```

docs/methods.md

@@ -0,0 +1,37 @@
+## Methods
+
+The `\Imahmood\FileStorage\FileStorage` class offers several methods:
+
+```php
+// Specify the disk where the file will be stored.
+
+$this->fileStorage->onDisk($disk);
+
+$this->fileStorage
+    ->onDisk($disk)
+    ->create($type, $relatedTo, $uploadedFile);
+```
+
+```php
+// Create and associate a new file.
+
+$this->fileStorage->create($type, $relatedTo, $uploadedFile);
+```
+
+```php
+// Update the existing file.
+
+$this->fileStorage->update($type, $relatedTo, $media, $uploadedFile);
+```
+
+```php
+// Create a new file or update an existing one.
+
+$this->fileStorage->updateOrCreate($type, $relatedTo, $media, $uploadedFile);
+```
+
+```php
+// Remove the media instance from both the database and the disk.
+
+$this->fileStorage->delete($media);
+```

docs/quick-start.md

@@ -0,0 +1,81 @@
+## Quick Start
+
+### 1. Define File Types
+Create an enumeration FileType to represent different types of files.
+
+```php
+<?php
+namespace App\Enums;
+
+use Imahmood\FileStorage\Contracts\MediaTypeInterface;
+
+enum FileType: int implements MediaTypeInterface
+{
+    case USER_AVATAR = 1;
+    
+    public function identifier(): int
+    {
+        return $this->value;
+    }
+}
+```
+
+### 2. Preparing your model
+Ensure your  model  correctly implements the `MediaAwareInterface` and define a relation to retrieve the uploaded file.
+
+```php
+<?php
+namespace App\Models;
+
+use App\Enums\FileType;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\MorphOne;
+use Imahmood\FileStorage\Contracts\MediaAwareInterface;
+use Imahmood\FileStorage\MediaAwareTrait;
+use Imahmood\FileStorage\Models\Media;
+
+class User extends Model implements MediaAwareInterface
+{
+    use MediaAwareTrait;
+    
+    public function avatar(): MorphOne
+    {
+        return $this
+            ->morphOne(Media::class, 'model')
+            ->where(['type' => FileType::USER_AVATAR]);
+    }
+}
+```
+
+### 3. Uploading files
+
+```php
+<?php
+namespace App\Http\Controllers;
+
+use App\Models\User;
+use Illuminate\Http\Request;
+use Imahmood\FileStorage\FileStorage;
+
+class UsersController extends Controller
+{
+    public function __construct(
+        private readonly FileStorage $fileStorage,
+    ) {
+    }
+    
+    public final store(Request $request, int $userId)
+    {
+        $user = User::query()->findOrFail($userId);
+        
+        $media = $this->fileStorage->create(
+            type: FileType::USER_AVATAR,
+            relatedTo: $user,
+            media: $user->avatar,
+            uploadedFile: $request->file('avatar'),
+        );
+        
+        // ...
+    }
+}
+```