README

A module for uploading and managing images.

Installation Guide

Install the package using Composer.

composer require elysiumrealms/imageable

Run the migrations.

php artisan migrate

Implementation Guide

Use the ImageableTrait trait to your model.

use Elysiumrealms\Imageable;

class User extends Model
implements Imageable\Contracts\Imageable
{
    use Imageable\Traits\ImageableTrait;

    ...
}

Schedule the imageable:prune command to prune deleted images.

function schedule(Schedule $schedule)
{
    $schedule->command('imageable:prune')
        ->onOneServer()
        ->daily();
}

Storage Mode Configuration

The imageable module supports two storage modes:

Proxy Forwarding Mode

Images are stored locally on the backend server or AWS S3 Bucket, access all images through imageable/{image} route.

graph LR;
    A[Browser] --> B[Reverse Proxy];
    B --> C[Backend];
    C -->|Read Local Image File| D[File System];
    D --> C
    C --> B;
    B --> A;

    A[Browser] --> B[Reverse Proxy];
    B --> C[Backend];
    C -->|Http Request| E[AWS S3 Bucket];
    E --> C;
    C --> B;
    B --> A;

The Proxy Forwarding Mode is designed for cases where AWS S3 Bucket is not available or when the system is not yet deployed to a production environment. In production, the Direct Storage Mode is preferred to reduce backend system I/O and improve performance.

Direct Storage Mode (Recommended for Production)

Images are stored in an AWS S3 Bucket, and the system returns the full AWS S3 Bucket URL or file path for access.

graph LR;
    A[Browser] --> B[AWS S3 Bucket];
    B --> A;

    A[Browser] --> C[Reverse Proxy];
    C -->|Read Local Image File| D[File System];
    D --> C;
    C --> A;

In direct Direct Storage Mode mode, all images will be served directly from AWS S3 Bucket or file path on the backend server.

Deployment Considerations

Development/Test Environments

Use Proxy Forwarding Mode to simulate image retrieval before setting up AWS S3 Bucket.

Production Environment

Use Direct Storage Mode to reduce backend load and improve performance.
Set the Storage Mode through IMAGEABLE_DRIVER environment variable to desired driver.

Configuration

When using Direct Storage Mode and s3 driver, ensure proper AWS S3 Bucket permissions and bucket policies.
Configure reverse proxy rules to handle image routing when using Proxy Forwarding Mode.

Usage Guide

Upload images through the POST /api/v1/imageable/{collection} route.

curl -X POST http://localhost:8000/api/v1/imageable/default \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: multipart/form-data" \
    -F "images[]=@/path/to/your/xxx_01.jpg" \
    -F "images[]=@/path/to/your/xxx_02.jpg" \
    -F "images[]=@/path/to/your/xxx_03.jpg"

Delete images through the DELETE /api/v1/imageable route.

curl -X DELETE http://localhost:8000/api/v1/imageable/ \
    -H "Authorization: Bearer {token}"
    -H "Content-Type: application/json"
    -d '{"images": ["xxx_01.jpg", "xxx_02.jpg", "xxx_03.jpg"]}'

Get images paginated through the GET /api/v1/imageable route.

curl -X GET http://localhost:8000/api/v1/imageable \
    -H "Authorization: Bearer {token}"
    -H "Content-Type: application/json"
    -d '{"page": 1, "per_page": 10}'

Access the images through the images relationship.
```
User::find(1)->images;
```

For further details, please contact the development team.

elysiumrealms / imageable

Maintainers

Details