README

This package provides a Laravel wrapper for the AWS Serverless Image Handler service.

Requirements

PHP >= 7.3
Laravel >= 5.0
An AWS account with Image Handler service installed

Installation

You can install the package via composer:

composer require rkcreative/aws-image-handler

After installing the package, the AwsImageHandlerServiceProvider and the ImageHandler facade are automatically registered, thanks to Laravel's package discovery feature.

If you're using Laravel 5.5 or later, no further steps are required. You can start using the ImageHandler facade right away:

use Rkcreative\AwsImageHandler\Facades\ImageHandler;

$url = ImageHandler::resize(200, 200)->createUrl('path/to/image.jpg');

If you're using a version of Laravel that's earlier than 5.5, you'll need to manually register the service provider and facade. Add the following lines to the providers and aliases arrays in your config/app.php file:

'providers' => [
    // Other service providers...

    Rkcreative\AwsImageHandler\AwsImageHandlerServiceProvider::class,
],

'aliases' => [
    // Other aliases...

    'ImageHandler' => Rkcreative\AwsImageHandler\Facades\ImageHandler::class,
],

Configuration

After installing the package, you should publish the configuration file:

php artisan vendor:publish --provider="Rkcreative\AwsImageHandler\AwsImageHandlerServiceProvider" --tag="config"

This command will create a aws-image-handler.php configuration file in your config directory. In this file, you can set your distribution URL and the default S3 bucket:

return [
    'distributionUrl' => env('AWS_IMAGE_HANDLER_URL', 'default-url'),
    'defaultBucket'   => env('AWS_IMAGE_HANDLER_S3_BUCKET', 'default-bucket'),
];

You should also add the AWS_IMAGE_HANDLER_URL and AWS_IMAGE_HANDLER_S3_BUCKET variables to your .env file:

AWS_IMAGE_HANDLER_URL=your-distribution-url
AWS_IMAGE_HANDLER_S3_BUCKET=your-default-bucket

Usage

Here's a detailed example of how to use the ImageHandler class:

use Rkcreative\AwsImageHandler\Services\ImageHandler;

$imageHandler = new ImageHandler();
$imageHandler->resize(200, 200);

// Generate the URL for the transformed image
$url = $imageHandler->createUrl('path/to/image.jpg');

In this example, the resize macro is used to set the desired image dimensions, and then the createUrl method is used to generate the URL for the transformed image. The resulting URL will look something like this:

https://your-cloudfront-url.com/eyJidWNrZXQiOiJidWNrZXQiLCJrZXkiOiJwYXRoL3RvL2ltYWdlLmpwZyIsImVkaXRzIjp7InJlc2l6ZSI6eyJ3aWR0aCI6MjAwLCJoZWlnaHQiOjIwMH19fQ==

In this URL, your-cloudfront-url.com is your CloudFront distribution URL, and the long base64 string is the encoded edit options.

Using the Alias

The package also provides an alias, which you can use for even easier access. Here's an example:

use ImageHandler;

$url = ImageHandler::resize(200, 200)->createUrl('path/to/image.jpg');

In this example, ImageHandler::resize(200, 200) is equivalent to (new Rkcreative\AwsImageHandler\Services\ImageHandler())->resize(200, 200). You can use this alias anywhere in your Laravel application.

Available Macros

The ImageHandler class comes with the following macros:

smartCrop
roundCrop
contentModeration
crop
quality
resize
setRgba
rotate

You can use these macros like any other method on the ImageHandler class:

$imageHandler = new ImageHandler();
$imageHandler->smartCrop($options);
$imageHandler->roundCrop($options);
// etc.

Extending with Custom Macros

You can extend the ImageHandler class with your own macros. The options are from the Sharp Node.js image processing library. Here's how to do it:

Create a new service provider:

php artisan make:provider ImageHandlerMacroServiceProvider

In the boot method of your new service provider, add your macro:

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Rkcreative\AwsImageHandler\Services\ImageHandler;

class ImageHandlerMacroServiceProvider extends ServiceProvider
{
    public function boot()
    {
        // Sample blur image operation from the Sharp node.js image library to show how you could add it as a custom option.
        ImageHandler::macro('blur', function ($blur) {
            if ($blur < 0.3 || $blur > 1000) {
                throw new \InvalidArgumentException('Invalid blur value. It must be = a sigma value between 0.3 and 1000.');
            }

            $this->options['blur'] = $blur;

            return $this;
        });
    }
}

In this example, the blur macro receives a blur value as an argument. The blur value is then added to the image handler options. The macro modifies the state of the ImageHandler instance and then returns the instance itself, allowing for method chaining.

'providers' => [
    // Other service providers...

    App\Providers\ImageHandlerMacroServiceProvider::class,
],

Now, you can use your macro like any other method on the ImageHandler class:

$imageHandler = new ImageHandler();
$imageHandler->blur(3)->createUrl('path/to/image.jpg');

In this example, the blur macro is used to add a blur effect to the image. The blur value can be any number between 0.3 (low blur) and 1000 (maximum blur).

Contributing

Contributions are welcome. We accept contributions via Pull Requests on Github.

Bug Reports

If you've found a bug, please create an issue on Github describing the problem and include as much relevant information as you can. Screenshots, error messages, and sample code that reproduces the problem are all helpful.

Pull Requests

Document any change in behavior - Make sure the README.md and any other relevant documentation are kept up-to-date.
Create topic branches - Don't ask us to pull from your master branch.
One pull request per feature - If you want to do more than one thing, send multiple pull requests.
Send coherent history - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please squash them before submitting.
Write tests for your feature - This helps us ensure that everything is working as expected and protects against regressions when new changes are made.

To run the tests, use the following command:

vendor/bin/phpunit

Happy coding!

License

The MIT License (MIT). Please see License File for more information.

Authors

Robert Pettique

rkcreative / aws-image-handler

Maintainers

Details