Download the PHP package makeabledk/laravel-cloud-images without Composer

Laravel Cloud Images

This package provides a convenient to manage Google App Engine Images API through Laravel.

Images API allows you to upload an image once to your GCS bucket and afterwards generate unlimited thumbnails just by requesting the specified size in the image-url. No delay, storage concerns or re-generate commands.

Important

Please checkout https://github.com/makeabledk/appengine-php-imageserver for more information on Images API and how to setup an imageserver for your project.

This package assumes you already have a configured App Engine imageserver and GCS Bucket.

Installation

You can install this package via composer:

Add a new gcs disk to your filesystems.php config

See https://github.com/spatie/laravel-google-cloud-storage for more details about configuring filesystems.php.

Creating a Google Service Account

You can create a service account key file through these steps

• Head to your project's Google Cloud Console and locate IAM -> Service accounts
• Create a new service account with an appropriate name, ie. sa-PROJECT-NAME-webapp-ENVIRONMENT.
• On the second step it prompts you to grant permissions. You should as a minimum grant Storage Object Admin permissions
• Finally you should Create key and download a json key file. Place it in your storage folder and set path in filesystems.php accordingly

Upgrading from 0.16.x -> 0.17.0

This release introduces new database fields for responsive images. Please publish migrations and optionally generate placeholders.

Upgrading from 2.x --> 3.x

Starting with version 3 this package uses spatie/laravel-google-cloud-storage instead of superbalist/laravel-google-cloud-storage.

• Please ensure you refer to the configuration options in laravel-google-cloud-storage#installation.
• Specifically make sure you change your disk configuration in config/filesystems.php @ gcs.key_file --> gcs.key_file_path.

Basic usage

Upload an image

Easily upload a \Illuminate\Http\File or \Illuminate\Http\UploadedFile to your GCS bucket and create an image-url for it.

Delete an image

Using the delete method will both delete the bucket file and destroy serving-image URL.

Note that image-serving URL's can take up to 24 hours to clear from cache

The good stuff: Generating images on the fly

Now that our image is served by Google, we can manipulate it on the fly.

All you have to do to start manipulating images, is an instance of ImageFactory:

Contain to max dimension

Example result:

Crop to dimensions

Example result:

Stretch to dimensions

Example result:

Blur

Example result:

Custom parameters (advanced)

If the functionality you need is not provided by the package, you can specify your own google-compatible parameters:

Checkout our makeabledk/appengine-php-imageserver repository for more information on available parameters.

Media Library usage (recommended)

For the examples so far there has been no need to publish any migrations. You are completely free to only use this package for uploading and retrieving image files from Google.

However, while uploading and serving images is all well and good, you will likely need to store the references in your database and attach them to some existing models.

This package will likely provide you with most of the functionality you'll ever need for dealing with images in your application.

Extended installation

1. Install rutorika/sortable package which is used to track sort-order (required)

2. Install intervention/image to read and store exif-data on your images (optional)

3. Publish and run migrations

Uploading images

Model attachment with multiple images

First, use the HasImages trait on your parent model.

Now you have an images() belongs-to-many relationship you can utilize as you normally would:

Ordering attached images

Images will be kept in the order you attach them. However, you are free to reorder them afterwards.

Checkout the Sortable many to many section of the rutorika/sortable package.

Model attachment with a single image

If your model is expected to have just one image, you may use the convenient image() helper provided by the same HasImages trait.

On the Image instance you may use the make() method to generate the size you need.

Differentiating between image types

Sometimes you may wish to have different types of 'single images' on a model. Use the optional tag parameter to achieve this behavior.

Note: Tagging is only intended through the image($tag) helper as the rutorika/sortable package does not differentiate between tags when applying order.

Replacing images

Use the replaceWith method on the Image model to swap any Image with another while preserving attachments.

This is especially useful in combination with the image() helper:

• If the product did not have a 'featured' image, it would simple attach the new one
• If the product did already have 'featured' image it would get replaced, and the old one deleted

Pro tip: Use an eloquent mutator to set the new image

In your controller it would work seamlessly when validating and filling the model (Laravel 5.5 example).

Configuring image sizes per model

Often times you want a few pre-configured sizes available. In this example we would like 'square' and 'wide' available on our Product model.

We may extend the Image model and use that on our Product->images() relationship.

Now you can access the sizes simply by referencing them as properties.

Remember to add the sizes to $appends attribute if you want them available when casting to array:

In Laravel 5.5, ApiResources would be a great place to append your image sizes as well.

Responsive images

Given the previous example of a product image, we may use the responsive() method to generate a collection of responsive image sizes.

By doing this, we can serve srcset optimized images on our website.

Of course all the available transformations are still available for responsive images.

The approach for responsive images is heavily inspired by the spatie/laravel-medialibrary package and offer the same functionality (including placeholders).

Consider reading their documentation for a very thorough explanation of the concept.

Also be sure to checkout their demo here: Responsive images demo

Finally consider checking out ResponsiveTest.php for more usage examples this package offers.

Cleaning up old images

Deleting an image

When deleting an Image instance, the CloudImage::delete() method is automatically fired to delete the actual bucket file.

Deleting images with no attachment

Over time your images table may get bloated with images that no longer has model-attachments to them.

Use the cloud-images:cleanup command to delete images (along with the actual bucket files) that are no longer used.

Testing

You can run the tests with:

Contributing

We are happy to receive pull requests for additional functionality. Please see CONTRIBUTING for details.

Credits

• Rasmus Christoffer Nielsen
• Spatie for their awesome spatie/laravel-medialibrary
• All Contributors

License

Attribution-ShareAlike 4.0 International. Please see License File for more information.