Larupload

https://github.com/mostafaznv/larupload
Admin
Larupload is an ORM-based file uploader for Laravel that enables users to upload images, videos,...
Tokens:60,707
Snippets:399
Trust Score:9
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install Larupload via Composer

Source: https://github.com/mostafaznv/larupload/blob/master/docs/getting-started/installation.md

Run this command to install the Larupload package via Composer.

```shell
composer require mostafaznv/larupload
```

--------------------------------

### Sample output of urls() method

Source: https://github.com/mostafaznv/larupload/blob/master/docs/download/generate-download-link/generate-url-for-all-styles.md

Example JSON output showing the structure of the returned object, with style names as keys and URLs as values.

```json
{
    "original": "https://larupload.dev/storage/users/1/avatar/original/image.jpg",
    "thumbnail": "https://larupload.dev/storage/users/1/avatar/thumbnail/image.jpg",
    "cover": "https://larupload.dev/storage/users/1/avatar/cover/image.jpg"
}
```

--------------------------------

### Set capture-frame to 0.1 seconds (Example 2)

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/configuration/ffmpeg/ffmpeg-capture-frame.md

Sets 'capture-frame' to 0.1, capturing a frame at 0.1 seconds into the video.

```php
<?php

return [
    'ffmpeg' => [
        'capture-frame' => 0.1
    ]
];
```

--------------------------------

### Example JSON output of meta()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/meta.md

Example JSON response returned by the meta method when called without arguments, showing all metadata fields for an attachment.

```json
{
    "name": "9e55cf595703eaa109025073caed65a4.jpg",
    "id": "1",
    "original_name": "image.jpg",
    "size": 35700,
    "type": "IMAGE",
    "mime_type": "image/jpeg",
    "width": 1077,
    "height": 791,
    "duration": null,
    "dominant_color": "#f4c00a",
    "format": "jpg",
    "cover": "9e55cf595703eaa109025073caed65a4.jpg"
  }
```

--------------------------------

### Set capture-frame to 2 seconds (Example 3)

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/configuration/ffmpeg/ffmpeg-capture-frame.md

Sets 'capture-frame' to 2, capturing a frame at 2 seconds into the video.

```php
<?php

return [
    'ffmpeg' => [
        'capture-frame' => 2
    ]
];
```

--------------------------------

### Example output of urls() with metadata

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/configuration/with-meta.md

Shows the JSON response structure when 'withMeta' is enabled. Includes original, thumbnail, cover URLs and a meta object with file details such as name, size, type, dimensions, and dominant color.

```json
{
    "original": "https://larupload.dev/storage/users/1/avatar/original/image.jpg",
    "thumbnail": "https://larupload.dev/storage/users/1/avatar/thumbnail/image.jpg",
    "cover": "https://larupload.dev/storage/users/1/avatar/cover/image.jpg",
    "meta": {
        "name": "image.jpg",
        "id": "1",
        "original_name": "image.jpg",
        "size": 35700,
        "type": "IMAGE",
        "mime_type": "image/jpeg",
        "width": 1077,
        "height": 791,
        "duration": null,
        "dominant_color": "#f4c00a",
        "format": "jpg",
        "cover": "image.jpg"
  }
}
```

--------------------------------

### Basic Example: Configure upload with disk, naming method, and media styles

Source: https://github.com/mostafaznv/larupload/blob/master/docs/standalone-uploader/customization.md

Shows how to initialize an upload with a custom disk ('s3'), a hash-based naming method, and define image, video, and audio styles, including a video stream with custom encoding settings. The upload method accepts the file and an optional cover.

```php
$file = $request->file('file');
$cover = $request->file('cover');

$upload = Larupload::init('path')
            ->disk('s3')
            ->namingMethod(LaruploadNamingMethod::HASH_FILE)
            ->image('thumbnail', 1000, 750, LaruploadMediaStyle::CROP)
            ->video('thumbnail', 1000, 750, LaruploadMediaStyle::CROP)
            ->audio('wav', new Wav())
            ->stream(
                name: '480p',
                width: 640,
                height: 480,
                format: (new X264)
                    ->setKiloBitrate(3000)
                    ->setAudioKiloBitrate(64)
                )
            )
            ->upload($file, $cover);
```

--------------------------------

### Get paths for multiple styles

Source: https://github.com/mostafaznv/larupload/blob/master/docs/path.md

Use `path()` with any generated style name to get the local file path for that style.

```php
$model->attachment('file')->path('thumbnail');
$model->attachment('file')->path('cover');
```

--------------------------------

### Fetch Notification in Listener

Source: https://github.com/mostafaznv/larupload/blob/master/docs/queue-ffmpeg-processes/job-completion-event.md

Implement the handle method to receive the LaruploadFFMpegQueueFinished event and access its properties: id, model, and statusId. This example logs the information using the info helper.

```php
<?php

namespace App\Listeners;

class LaruploadFFMpegQueueNotification
{
    public function handle(LaruploadFFMpegQueueFinished $event)
    {
        info("larupload queue finished. id: $event->id, model: $event->model, statusId: $event->statusId");
    }
}
```

--------------------------------

### Define audio style with audio() in Larupload

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/media-styles.md

Shows how to add an audio style (hq) to an attachment using the audio() method with a Wav format instance. The example uses the FFMpeg Wav format class.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Enums\LaruploadMediaStyle;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;
use FFMpeg\Format\Audio\Wav;

class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')
                ->audio('hq', new Wav())
        ];
    }
}
```

--------------------------------

### Migration with upload macro for Larupload

Source: https://github.com/mostafaznv/larupload/blob/master/docs/basic-usage/database-preparation.md

Use this migration to create a table with Larupload columns. The `upload` macro adds the necessary columns for storing file metadata. The example creates two upload columns: `main_file` with `LaruploadMode::HEAVY` and `other_file` with `LaruploadMode::LIGHT`. The `down` method drops the table.

```php
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
use Mostafaznv\Larupload\Enums\LaruploadMode;

return new class extends Migration {
    public function up()
    {
        Schema::create('uploads', function(Blueprint $table) {
            $table->id();
            $table->upload('main_file', LaruploadMode::HEAVY);
            $table->upload('other_file', LaruploadMode::LIGHT);
            $table->timestamps();
        });
    }

    public function down()
    {
        Schema::dropIfExists('uploads');
    }
};
```

--------------------------------

### Retrieve attachments with toArray() and toJson()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/api-resources.md

Use these methods to manually get the model's array or JSON representation, including all attachments. The example fetches the first Upload record and calls both methods.

```php
$upload = Upload::query()->first();

$upload->toArray();
$upload->toJson();
```

--------------------------------

### Example camelCase JSON output

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/configuration/camel-case-response.md

Shows the JSON response format when the camelCase option is enabled. Note the keys like 'originalName', 'mimeType', 'dominantColor' in camelCase.

```json
{
    "name": "image.jpg",
    "id": "1",
    "originalName": "image.jpg"
    "size": 35700,
    "type": "IMAGE",
    "mimeType": "image/jpeg",
    "width": 1077,
    "height": 791,
    "duration": null,
    "dominantColor": "#f4c00a",
    "format": "jpg",
    "cover": "image.jpg"
  }
```

--------------------------------

### Define image styles with image() in Larupload

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/media-styles.md

Shows how to add image styles (thumbnail and landscape) to an attachment using the image() method with LaruploadMediaStyle enum values. The example uses CROP and AUTO modes with specified dimensions.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Enums\LaruploadMediaStyle;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;

class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')
                ->image('thumbnail', 250, 250, LaruploadMediaStyle::CROP)
                ->image('landscape', 1100, 1100, LaruploadMediaStyle::AUTO)
        ];
    }
}
```

--------------------------------

### Generate URL for the original file

Source: https://github.com/mostafaznv/larupload/blob/master/docs/download/generate-download-link/generate-url-for-particular-style.md

Call the url method without arguments or with 'original' to get the URL of the original file.

```php
$model->attachment('avatar')->url();
# or
$model->attachment('avatar')->url('original');
```

--------------------------------

### Set capture-frame to null (Example 1)

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/configuration/ffmpeg/ffmpeg-capture-frame.md

Sets 'capture-frame' to null, which makes Larupload automatically capture a frame from the center of the video file.

```php
<?php

return [
    'ffmpeg' => [
        'capture-frame' => null
    ]
];
```

--------------------------------

### Set cover style with coverStyle method

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/cover-style.md

Use the coverStyle method on an attachment to define the cover image style. The example sets a cover style named 'cover' with dimensions 400x400 and the CROP style enum.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Enums\LaruploadMediaStyle;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;

class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')
                ->coverStyle('cover', 400, 400, LaruploadMediaStyle::CROP)
        ];
    }
}
```

--------------------------------

### url method

Source: https://github.com/mostafaznv/larupload/blob/master/docs/download/generate-download-link/generate-url-for-particular-style.md

Generates a URL for an uploaded file. By default, it returns the URL of the original style. Pass a style name to get a URL for that specific style.

```APIDOC
## url method

### Description
Generates a URL for accessing an uploaded file. If no style is specified, returns the URL for the original file. If a style name is provided, returns the URL for that specific style.

### Method
url

### Parameters
#### Path Parameters
- **style** (string) - Optional - The name of the style to generate the URL for. If omitted, the original style is used.

### Request Example
```php
$model->attachment('avatar')->url('thumb');
```

### Response
#### Success Response
- **string** - The generated URL for the specified style or original file.

#### Response Example
```php
$model->attachment('avatar')->url();
# or
$model->attachment('avatar')->url('original');
```
```

--------------------------------

### Call urls() to get file URLs with metadata

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/configuration/with-meta.md

Invoke the urls() method on an attachment to retrieve URLs. With 'withMeta' enabled (default), the response includes metadata like format, dimensions, and dominant color.

```php
$user->attachment('avatar')->urls();
```

--------------------------------

### Get path for a particular style

Source: https://github.com/mostafaznv/larupload/blob/master/docs/path.md

Pass a style name to `path()` to retrieve the path of a specific generated style, such as 'cover'.

```php
$model->attachment('file')->path('cover');
```

--------------------------------

### Get All Attachments with getAttachments()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/get-attachments.md

Retrieves URLs and meta for all attachments on a user model. The output shows the structure for 'avatar' and 'cv' attachments, including original, thumbnail, cover URLs and meta fields.

```php
$user = User::query()->first();
$attachments = $user->getAttachments();
```

```json
{
  "avatar": {
    "original": "https://larupload.dev/storage/users/1/avatar/original/image.jpg",
    "thumbnail": "https://larupload.dev/storage/users/1/avatar/thumbnail/image.jpg",
    "cover": "https://larupload.dev/storage/users/1/avatar/cover/image.jpg",
    "meta": {
       "name": "image.jpg",
       "id": "1",
       "original_name": "image.jpg"
       "size": 35700,
       "type": "IMAGE",
       "mime_type": "image/jpeg",
       "width": 1077,
       "height": 791,
       "duration": null,
       "dominant_color": "#f4c00a",
       "format": "jpg",
       "cover": "image.jpg"
    }
  },
  "cv": {
    "original": "https://larupload.dev/storage/users/1/cv/original/cv.pdf",
    "cover": "https://larupload.dev/storage/users/1/cv/cover/cv.jpg",
    "meta": {
       "name": "cv.pdf",
       "id": "1",
       "original_name": "image.jpg"
       "size": 71710,
       "type": "DOCUMENT",
       "mime_type": "application/pdf",
       "width": null,
       "height": null,
       "duration": null,
       "dominant_color": "#f4c00a",
       "format": "pdf",
       "cover": "cv.jpg"
    }
  }
}
```

--------------------------------

### Upload response JSON output

Source: https://github.com/mostafaznv/larupload/blob/master/docs/standalone-uploader/upload.md

Example JSON response returned by the upload method, showing the original file URL and metadata including name, size, type, dimensions, duration, format, cover, MIME type, and dominant color.

```json
{
    "original": "http://larupload.site/storage/uploader/original/a3ac7ddabb263c2d00b73e8177d15c8d.mp4",
    "meta": {
        "name": "a3ac7ddabb263c2d00b73e8177d15c8d.mp4",
        "id": "125940123",
        "original_name": "video.mp4",
        "size": 383631,
        "type": "video",
        "width": 560,
        "height": 320,
        "duration": 5,
        "format": "mp4",
        "cover": "66ad2a5ebfe7ea349c8b861399c060d8.jpeg",
        "mime_type": "video/mp4",
        "dominant_color": "#e5d2d4",
    }
}
```

--------------------------------

### Set image processing library to GD in Attachment

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/image-processing-library.md

Use this snippet to configure an attachment to use the GD library for image processing. The method accepts 'GD' or 'IMAGICK' as a string parameter, and GD is the default. This example sets it explicitly to GD.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Enums\LaruploadImageLibrary;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;

class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')
                ->imageProcessingLibrary(LaruploadImageLibrary::GD)
        ];
    }
}
```

--------------------------------

### Add Larupload trait and define attachments method

Source: https://github.com/mostafaznv/larupload/blob/master/docs/basic-usage/model-preparation.md

Adds the Larupload trait to a model and defines the attachments method, which returns an array of Attachment instances. The example creates two attachments: 'main_file' with default mode and 'other_file' with LaruploadMode::LIGHT.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Enums\LaruploadMode;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload; 
    
class Upload extends Model
{
    use Larupload;
    
    /**
     * Define Upload Entities
     *
     * @return Attachment[]
     */
    public function attachments(): array
    {
        return [
            Attachment::make('main_file'),
            Attachment::make('other_file', LaruploadMode::LIGHT),
        ];
    }
}
```

--------------------------------

### Set attachment language with lang('fa')

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/lang.md

Use the `lang` method on an Attachment instance to specify a language for file name generation. In this example, the language is set to 'fa' (Persian). This overrides the default language from the `config/larupload.php` configuration file for this attachment.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;

class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')->lang('fa')
        ];
    }
}
```

--------------------------------

### Run Larupload migrations

Source: https://github.com/mostafaznv/larupload/blob/master/docs/getting-started/installation.md

Run this artisan command to create the necessary database tables for Larupload.

```shell
php artisan migrate
```

--------------------------------

### Get original file path

Source: https://github.com/mostafaznv/larupload/blob/master/docs/path.md

Call `path()` without arguments to retrieve the path of the original attachment file.

```php
$model->attachment('file')->path();
```

--------------------------------

### Create Listener with Artisan Command

Source: https://github.com/mostafaznv/larupload/blob/master/docs/queue-ffmpeg-processes-1/job-completion-event.md

Run this Artisan command to generate a new listener class for the LaruploadMediaDetailsQueueFinished event.

```bash
php artisan make:listener LaruploadMediaDetailsQueueFinishedListener
```

--------------------------------

### Configure image optimization in config/larupload.php

Source: https://github.com/mostafaznv/larupload/blob/master/docs/image-optimization.md

Enable the optimize-image feature and set custom optimizers for various image formats. The 'enable' flag is false by default; set it to true to activate. The 'timeout' option is set to 60 seconds. Each optimizer class is configured with command-line arguments to control compression quality and behavior.

```php
<?php

return [
    'optimize-image' => [
        'enable'  => false,
        'timeout' => 60,

        'optimizers' => [
            Spatie\ImageOptimizer\Optimizers\Jpegoptim::class => [
                '-m85', // set maximum quality to 85%
                '--force', // ensure that progressive generation is always done also if a little bigger
                '--strip-all', // this strips out all text information such as comments and EXIF data
                '--all-progressive', // this will make sure the resulting image is a progressive one
            ],

            Spatie\ImageOptimizer\Optimizers\Pngquant::class => [
                '--force', // required parameter for this package
            ],

            Spatie\ImageOptimizer\Optimizers\Optipng::class => [
                '-i0', // this will result in a non-interlaced, progressive scanned image
                '-o2', // this set the optimization level to two (multiple IDAT compression trials)
                '-quiet', // required parameter for this package
            ],

            Spatie\ImageOptimizer\Optimizers\Svgo::class => [
                '--config=svgo.config.js', // disabling because it is known to cause troubles
            ],

            Spatie\ImageOptimizer\Optimizers\Gifsicle::class => [
                '-b', // required parameter for this package
                '-O3', // this produces the slowest but best results
            ],

            Spatie\ImageOptimizer\Optimizers\Cwebp::class => [
                '-m 6', // for the slowest compression method in order to get the best compression.
                '-pass 10', // for maximizing the amount of analysis pass.
                '-mt', // multithreading for some speed improvements.
                '-q 90', //quality factor that brings the least noticeable changes.
            ],
        ]
    ]
];
```

--------------------------------

### Create Listener with Artisan Command

Source: https://github.com/mostafaznv/larupload/blob/master/docs/queue-ffmpeg-processes/job-completion-event.md

Run this artisan command to generate a new listener class for the Larupload FFMpeg queue finished event.

```bash
php artisan make:listener LaruploadFFMpegQueueNotification
```

--------------------------------

### Configure video styles with LaruploadMediaStyle

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/media-styles.md

Shows how to define video styles (thumbnail, landscape, mp3) using the video method with parameters like width, height, mode, and format. The mp3 style uses an Mp3 format instance.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Enums\LaruploadMediaStyle;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;
use FFMpeg\Format\Audio\Mp3;


class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')
                ->video('thumbnail', 250, 250, LaruploadMediaStyle::CROP)
                ->video('landscape', 1100, 1100, LaruploadMediaStyle::AUTO)
                ->video(name: 'mp3', format: new Mp3)
        ];
    }
}
```

--------------------------------

### Enable FFMpeg queue in config/larupload.php

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/configuration/ffmpeg/ffmpeg-queue.md

Set 'ffmpeg.queue' to true to queue the FFMpeg process and perform video conversion in the background. Requires a queue worker to process the queued jobs.

```php
<?php

return [
    'ffmpeg' => [
        'queue' => true
    ]
];
```

--------------------------------

### Create Listener with Artisan

Source: https://github.com/mostafaznv/larupload/blob/master/docs/process-finished-event.md

Command to generate a new listener class for the Larupload process finished event.

```bash
php artisan make:listener LaruploadProcessFinishedListener
```

--------------------------------

### Get Particular Attachment with getAttachments('avatar')

Source: https://github.com/mostafaznv/larupload/blob/master/docs/get-attachments.md

Retrieves URLs and meta for a specific attachment by passing its name as an argument. The output shows the structure for the 'avatar' attachment.

```php
$user = User::query()->first();
$attachment = $user->getAttachments('avatar');
```

```json
{
   "original": "https://larupload.dev/storage/users/1/avatar/original/image.jpg",
   "thumbnail": "https://larupload.dev/storage/users/1/avatar/thumbnail/image.jpg",
   "cover": "https://larupload.dev/storage/users/1/avatar/cover/image.jpg",
   "meta": {
       "name": "image.jpg",
       "id": "1",
       "original_name": "image.jpg"
       "size": 35700,
       "type": "IMAGE",
       "mime_type": "image/jpeg",
       "width": 1077,
       "height": 791,
       "duration": null,
       "dominant_color": "#f4c00a",
       "format": "jpg",
       "cover": "image.jpg"
    }
 }
```

--------------------------------

### Set custom ffmpeg and ffprobe binary paths in config/larupload.php

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/configuration/ffmpeg/ffmpeg-binaries.md

Use this PHP configuration to define the absolute paths to the `ffmpeg` and `ffprobe` binaries. The `ffmpeg` binary handles video and audio processing, while `ffprobe` is used for metadata extraction. This is only needed when the binaries are not in the system environment path.

```php
<?php

return [
    'ffmpeg' => [
        'ffmpeg.binaries'  => '/usr/local/bin/ffmpeg',
        'ffprobe.binaries' => '/usr/local/bin/ffprobe'
    ]
];
```

--------------------------------

### Configure stream styles with X264 format

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/media-styles.md

Shows how to define stream styles (480p, 720p) using the stream method with width, height, and format parameters. The format uses X264 with custom kilo bitrate settings.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use FFMpeg\Format\Video\X264;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;

class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')
                ->stream(
                    name: '480p',
                    width: 640,
                    height: 480,
                    format: (new X264)
                        ->setKiloBitrate(1000)
                        ->setAudioKiloBitrate(32)
                )
                ->stream(
                    name: '720p',
                    width: 1280,
                    height:  720,
                    format: (new X264)
                        ->setKiloBitrate(3000)
                        ->setAudioKiloBitrate(64)
                )
        ];
    }
}
```

--------------------------------

### Upload with Create Method

Source: https://github.com/mostafaznv/larupload/blob/master/docs/upload.md

Create and upload a file in one line by passing the file to the model's create method.

```php
$upload = Upload::create([
    'file' => $request->file('file')
]);
```

--------------------------------

### Publish Larupload configuration file

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/configuration/README.md

Run this artisan command to publish the configuration file to config/larupload.php. The command specifies the Larupload service provider.

```bash
php artisan vendor:publish --provider="Mostafaznv\Larupload\LaruploadServiceProvider"
```

--------------------------------

### Upload a file with Larupload in a controller

Source: https://github.com/mostafaznv/larupload/blob/master/docs/standalone-uploader/upload.md

Use `Larupload::init('your/base/path')->upload($file, $cover)` to upload a file and optional cover. The method returns an array with the file URL and metadata, which is returned as a JSON response.

```php
<?php

namespace App\Http\Controllers;

use Mostafaznv\Larupload\Larupload;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class UploadController extends Controller
{
    public function store(Request $request): JsonResponse
    {
        $file = $request->file('file');
        $cover = $request->file('cover');
        
        $upload = Larupload::init('your/base/path')->upload($file, $cover);

        return response()->json($upload);
    }
}
```

--------------------------------

### Listener handle Method

Source: https://github.com/mostafaznv/larupload/blob/master/docs/queue-ffmpeg-processes-1/job-completion-event.md

Implements the handle method that receives the LaruploadMediaDetailsQueueFinished event and logs the extracted media details using the event's id, model, and statusId properties.

```php
<?php

namespace App\Listeners;

class LaruploadMediaDetailsQueueFinishedListener
{
    public function handle(LaruploadMediaDetailsQueueFinished $event)
    {
        info("larupload media details extraction finished. id: $event->id, model: $event->model, statusId: $event->statusId");
    }
}
```

--------------------------------

### Attach a cover file with attach()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/cover/upload-cover.md

Use this snippet to upload a file with an optional cover. The cover is passed as the second argument to attach(), which prevents automatic cover creation for images and videos.

```php
$file = $request->file('file');
$cover = $request->file('cover');
# or
$upload->attachment('file')->attach($file, $cover);

$upload->save();
```

--------------------------------

### Using secureIdsMethod with ULID format

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/secureids-method.md

Configures the secure ID method for a file attachment to use ULID format. Requires the hashids package for HASHID and sqids package for SQID. SecureIds is disabled in standalone mode.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Enums\LaruploadSecureIdsMethod;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;

class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')
                ->secureIdsMethod(LaruploadSecureIdsMethod::ULID)
        ];
    }
}
```

--------------------------------

### Set naming method to HASH_FILE in Laravel model

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/naming-method.md

Configures an attachment to use the HASH_FILE naming method, which generates a unique name based on file contents using the md5 algorithm. The example shows the required imports and the use of the Larupload trait.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Enums\LaruploadNamingMethod;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;

class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')
                ->namingMethod(LaruploadNamingMethod::HASH_FILE)
        ];
    }
}
```

--------------------------------

### Configure cover-style in config/larupload.php

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/configuration/cover-style.md

Sets the cover image style to 500x500 pixels with center cropping using the LaruploadMediaStyle::CROP constant. The default is an ImageStyle object.

```php
<?php

return [
    'cover-style' => ImageStyle::make(
        name: 'cover',
        width: 500,
        height: 500,
        mode: LaruploadMediaStyle::CROP
    )
];
```

--------------------------------

### Register Listener in EventServiceProvider

Source: https://github.com/mostafaznv/larupload/blob/master/docs/queue-ffmpeg-processes/job-completion-event.md

Add the event and listener mapping to the $listen property in App\Providers\EventServiceProvider. The listener will be called when the LaruploadFFMpegQueueFinished event is dispatched.

```php
use App\Events\OrderShipped;
use Mostafaznv\Larupload\Events\LaruploadFFMpegQueueFinished;
use App\Listeners\LaruploadFFMpegQueueNotification;
 

protected $listen = [
    LaruploadFFMpegQueueFinished::class => [
        LaruploadFFMpegQueueNotification::class,
    ],
];
```

--------------------------------

### download(style)

Source: https://github.com/mostafaznv/larupload/blob/master/docs/download/generate-download-response.md

Generates an HTTP download response for a specific style of the attachment. Pass the style name as an argument to download that variant.

```APIDOC
## download(style)

### Description
Generates an HTTP download response for a particular style of the attachment. This method is called on an attachment instance with the desired style name and returns a response object.

### Method
GET (HTTP response)

### Endpoint
Not applicable (method call on attachment instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Path Parameters (Method Argument)
- **style** (string) - Required - The name of the style to download (e.g., 'thumbnail').

### Request Example
```php
$user->attachment('avatar')->download('thumbnail');
```

### Response
#### Success Response (200)
- **file contents** (binary) - The file content to be downloaded.
- **headers** (object) - Includes filename and content type headers.

#### Response Example
Not provided in source.
```

--------------------------------

### download()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/download/README.md

Creates an HTTP download response for an attachment. The method takes an optional style name and returns a Symfony HttpFoundation StreamedResponse object.

```APIDOC
## download()

### Description
Creates an HTTP download response for an attachment. The method takes an optional style name and returns a Symfony HttpFoundation StreamedResponse object.

### Method
download()

### Parameters
- **style** (string) - Optional - The name of the style to download. If omitted, the default style is used.

### Returns
- **StreamedResponse** - A Symfony HttpFoundation StreamedResponse object that streams the attachment to the client.
```

--------------------------------

### Manually Register Listener in AppServiceProvider

Source: https://github.com/mostafaznv/larupload/blob/master/docs/process-finished-event.md

Optional registration for when event discovery is disabled. Place this in the boot method of AppServiceProvider.

```php
<?php

namespace App\Providers;

use App\Listeners\LaruploadProcessFinishedListener;
use Illuminate\Support\Facades\Event;
use Mostafaznv\Larupload\Events\LaruploadProcessFinished;


class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen(
            LaruploadProcessFinished::class,
            LaruploadProcessFinishedListener::class
        );
    }
}
```

--------------------------------

### Larupload::upload(file, cover)

Source: https://github.com/mostafaznv/larupload/blob/master/docs/standalone-uploader/upload.md

Documentation for the Larupload upload method in standalone mode.

```APIDOC
## Larupload::upload(file, cover)

### Description
Uploads a file in standalone mode. The method accepts the original file and an optional cover file. After upload, Larupload generates a unique filename and saves the file to the specified path.

### Method
upload

### Parameters
- **file** (UploadedFile) - Required - The original file to upload.
- **cover** (UploadedFile) - Optional - The cover image for the file.

### Request Example
```php
$upload = Larupload::init('your/base/path')->upload($file, $cover);
```

### Response
#### Success Response
Returns an array containing the uploaded file's URL and metadata.

#### Response Example
```json
{
    "original": "http://larupload.site/storage/uploader/original/a3ac7ddabb263c2d00b73e8177d15c8d.mp4",
    "meta": {
        "name": "a3ac7ddabb263c2d00b73e8177d15c8d.mp4",
        "id": "125940123",
        "original_name": "video.mp4",
        "size": 383631,
        "type": "video",
        "width": 560,
        "height": 320,
        "duration": 5,
        "format": "mp4",
        "cover": "66ad2a5ebfe7ea349c8b861399c060d8.jpeg",
        "mime_type": "video/mp4",
        "dominant_color": "#e5d2d4"
    }
}
```
```

--------------------------------

### Set disk for attachment with disk('s3')

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/disk.md

Use the disk method to specify a custom storage disk for an attachment. The disk name must be defined in config/filesystems.php. After setting, all operations on the attachment use the specified disk.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;

class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')->disk('s3')
        ];
    }
}
```

--------------------------------

### Migration: Create uploads table with HEAVY mode

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/migrations/heavy-columns.md

Creates an 'uploads' table with an 'upload' column configured for HEAVY mode. The down() method drops the table. All fields created in HEAVY mode are nullable, and file_original_name, file_size, file_type, and file_duration columns have an index.

```php
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
use Mostafaznv\Larupload\Enums\LaruploadMode;

return new class extends Migration {
    public function up()
    {
        Schema::create('uploads', function(Blueprint $table) {
            $table->id();
            $table->upload('file', LaruploadMode::HEAVY);
            $table->timestamps();
        });
    }

    public function down()
    {
        Schema::dropIfExists('uploads');
    }
};
```

--------------------------------

### Eager load laruploadQueue and laruploadQueues relationships

Source: https://github.com/mostafaznv/larupload/blob/master/docs/queue-ffmpeg-processes/ffmpeg-queue-relationships.md

Use this query to fetch a model with its current FFMpeg queue job and all historical FFMpeg jobs. The `laruploadQueue` relationship returns the currently running job, while `laruploadQueues` returns a list of all jobs including status, start/end times, and errors.

```php
Upload::query()
    ->where('id', 21)
    ->with('laruploadQueue', 'laruploadQueues')
    ->first();
```

--------------------------------

### Eager load media details queue relationships

Source: https://github.com/mostafaznv/larupload/blob/master/docs/queue-ffmpeg-processes-1/ffmpeg-queue-relationships.md

Use this query to fetch a media record with its currently running extraction job and the history of all extraction jobs. The relationships are available on all Eloquent models using Larupload.

```php
Upload::query()
    ->where('id', 21)
    ->with('laruploadMediaDetailsQueue', 'laruploadMediaDetailsQueues')
    ->first();
```

--------------------------------

### meta()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/meta.md

Documentation for the meta() method in Larupload, which retrieves attachment metadata.

```APIDOC
## meta()

### Description
Retrieves meta information about an attachment. If called without arguments, returns all available meta information. If called with a specific key, returns only that piece of meta information.

### Method
meta()

### Parameters
#### Optional Argument
- **key** (string) - Optional - The specific meta information to retrieve. Possible values include: `originalName`, `size`, `type`, `mimeType`, `duration`, `width`, `height`, `dominantColor`. If omitted, all meta information is returned.

### Return Value
- If a key is provided, returns the value of that meta field (e.g., integer for size, string for mime_type).
- If no key is provided, returns an object containing all meta fields.

### Example
```php
$size = $model->attachment('file')->meta('size');
$mime = $model->attachment('file')->meta('mime_type');
$meta = $model->attachment('file')->meta();
```

### Response Example (when called without arguments)
```json
{
    "name": "9e55cf595703eaa109025073caed65a4.jpg",
    "id": "1",
    "original_name": "image.jpg",
    "size": 35700,
    "type": "IMAGE",
    "mime_type": "image/jpeg",
    "width": 1077,
    "height": 791,
    "duration": null,
    "dominant_color": "#f4c00a",
    "format": "jpg",
    "cover": "9e55cf595703eaa109025073caed65a4.jpg"
}
```

### Notes
- The `type` field is based on the file extension, not the actual file contents.
- Possible `type` values: IMAGE, VIDEO, AUDIO, DOCUMENT, COMPRESSED, FILE.
```

--------------------------------

### Update cover with changeCover method

Source: https://github.com/mostafaznv/larupload/blob/master/docs/standalone-uploader/cover/update-cover.md

Use this PHP controller method to update the cover file. It retrieves the new cover from the request and calls Larupload::init('uploaded/base/path')->changeCover($cover).

```php
<?php

namespace App\Http\Controllers;

use Mostafaznv\Larupload\Larupload;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UploadController extends Controller
{
    public function store(Request $request): RedirectResponse
    {
        $cover = $request->file('cover');
        
        Larupload::init('uploaded/base/path')->changeCover($cover);

        return redirect()->back();
    }
}
```

--------------------------------

### Download Particular Style

Source: https://github.com/mostafaznv/larupload/blob/master/docs/download/generate-download-response.md

Pass the desired style name to the download method to generate a download response for that style. Returns an HTTP response object with file contents and headers.

```php
$user->attachment('avatar')->download('thumbnail');
```

--------------------------------

### Upload with Attach Function

Source: https://github.com/mostafaznv/larupload/blob/master/docs/upload.md

Use the attach function to upload a file and an optional cover image. The first argument is required, the second is optional. If a cover is provided, it is used instead of an auto-generated one.

```php
$file = $request->file('file');
$cover = $request->file('cover');
   
$upload->file->attach($file, $cover);
// or (recommended)
$upload->attachment('file')->attach($file, $cover);

$upload->save();
```

--------------------------------

### download()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/download/generate-download-response.md

Generates an HTTP download response for the attachment's original file. Call this method on an attachment instance to return a response from your controller.

```APIDOC
## download()

### Description
Generates an HTTP download response for the attachment's original file. This method is called on an attachment instance and returns a response object suitable for returning from a controller action.

### Method
GET (HTTP response)

### Endpoint
Not applicable (method call on attachment instance)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
$user->attachment('avatar')->download();
```

### Response
#### Success Response (200)
- **file contents** (binary) - The file content to be downloaded.
- **headers** (object) - Includes filename and content type headers.

#### Response Example
Not provided in source.
```

--------------------------------

### url()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/download/README.md

Generates a download link for a specified style of an attachment. The method takes an optional style name and returns a URL string.

```APIDOC
## url()

### Description
Generates a download link for a specified style of an attachment. The method takes an optional style name and returns a URL string.

### Method
url()

### Parameters
- **style** (string) - Optional - The name of the style to generate a download link for. If omitted, the default style is used.

### Returns
- **string** - The download URL for the specified style.
```

--------------------------------

### Enable image optimization in a Larupload attachment

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/optimize-image.md

Call optimizeImage(true) on an Attachment to enable image optimization using the spatie/image-optimizer package. By default, optimization is disabled.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Enums\LaruploadSecureIdsMethod;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;

class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')->optimizeImage(ture)
        ];
    }
}
```

--------------------------------

### Delete cover with Larupload::init()->deleteCover()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/standalone-uploader/cover/delete-cover.md

Use this snippet to delete the cover file for an attachment in standalone mode. It initializes Larupload with a base path and calls deleteCover() before redirecting back.

```php
<?php

namespace App\Http\Controllers;

use Mostafaznv\Larupload\Larupload;
use Illuminate\Http\Request;

class UploadController extends Controller
{
    public function store(): RedirectResponse
    {        
        Larupload::init('uploaded/base/path')->deleteCover();

        return redirect()->back();
    }
}
```

--------------------------------

### Enable extractMediaDetailsOnQueue in Larupload attachment

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/extract-media-details-on-queue.md

Configure a Larupload attachment to extract media details asynchronously by calling `extractMediaDetailsOnQueue(true)` on the attachment. Requires a running queue worker; details are unavailable until the job completes. Only works in ORM mode.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mostafaznv\Larupload\Storage\Attachment;
use Mostafaznv\Larupload\Traits\Larupload;

class Media extends Model
{
    use Larupload;

    public function attachments(): array
    {
        return [
            Attachment::make('file')->extractMediaDetailsOnQueue(true)
        ];
    }
}
```

--------------------------------

### imageProcessingLibrary(LaruploadImageLibrary $library)

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/image-processing-library.md

Sets the image processing library for a specific attachment. Accepts a string parameter that can be either 'GD' or 'IMAGICK' to specify the library to use for image manipulation operations like cropping and resizing.

```APIDOC
## imageProcessingLibrary(LaruploadImageLibrary $library)

### Description
Sets the image processing library for a specific attachment. Accepts a string parameter that can be either `GD` or `IMAGICK` to specify the library to use for image manipulation operations like cropping and resizing.

### Method
imageProcessingLibrary

### Parameters
- **$library** (LaruploadImageLibrary) - Required - The image processing library to use. Must be one of the enum values: `LaruploadImageLibrary::GD` or `LaruploadImageLibrary::IMAGICK`.

### Request Example
```php
Attachment::make('file')
    ->imageProcessingLibrary(LaruploadImageLibrary::GD)
```

### Response
No return value is documented. The method is used for configuration purposes.
```

--------------------------------

### Upload file in controller

Source: https://github.com/mostafaznv/larupload/blob/master/docs/basic-usage/upload.md

Create a new model instance, assign the uploaded file to the 'main_file' attribute, and save. The file is automatically uploaded and stored in the database.

```php
<?php

namespace App\Http\Controllers;

use App\Models\Upload;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UploadController extends Controller
{
    public function store(Request $request): RedirectResponse
    {
        $upload = new Upload;
        $upload->main_file = $request->file('file');
        $upload->save();

        return redirect()->back();
    }
}
```

--------------------------------

### Retrieve all attachment metadata with meta()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/meta.md

Retrieves all available meta information for an attachment named 'file' by calling the meta method without arguments.

```php
$meta = $model->attachment('file')->meta();
```

--------------------------------

### Attachment::make()->optimizeImage()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/advanced-usage/attachment/optimize-image.md

Enables or disables image optimization for an uploaded image. Pass true to enable optimization, which reduces file size without affecting quality.

```APIDOC
## optimizeImage()

### Description
Enables or disables the image optimization feature for uploaded images. When enabled, the uploaded image is optimized using the `spatie/image-optimizer` package, reducing file size without affecting quality.

### Method
optimizeImage

### Parameters
- **enabled** (boolean) - Required - Set to `true` to enable image optimization, `false` to disable.

### Usage Example
```php
Attachment::make('file')->optimizeImage(true)
```

### Notes
- By default, image optimization is disabled.
- The function is called on an `Attachment` instance.
```

--------------------------------

### Download Original File

Source: https://github.com/mostafaznv/larupload/blob/master/docs/download/generate-download-response.md

Call the download method on an attachment instance to generate a download response for the original file. Returns an HTTP response object with file contents and headers.

```php
$user->attachment('avatar')->download();
```

--------------------------------

### Update file cover with cover() and save()

Source: https://github.com/mostafaznv/larupload/blob/master/docs/cover/update-cover.md

Updates the cover of an uploaded file. Use the file's cover() relationship and then call save() on the upload model. The recommended alternative uses attachment('file')->cover()->update().

```php
$cover = $request->file('cover');

$upload = Upload::query()->first();

$upload->file->cover()->update($cover);
# or (recommended)
$upload->attachment('file')->cover()->update($cover);

$upload->save();
```

--------------------------------

### Delete file using detach method

Source: https://github.com/mostafaznv/larupload/blob/master/docs/delete.md

Use the detach method to delete a file. The recommended approach is to call detach on the attachment instance, then save the model. The first line shows an alternative direct call on the file property.

```php
$upload->file->detach();
# or (recommended)
$upload->attachment('file')->detach();

$upload->save();
```
Tokens:
Raw