Download the PHP package okaybueno/images without Composer

IMPORTANT ❗

This package has been discontinued so it won't receive any other update. If you're using it please consider migrating to another solution. There are many other great solutions out there (ie. "medialibrary") that this package does not provide any benefit whatsoever anymore.

Image

A package that provides an easy way to work with images attached to models.

Disclaimer

This package was originally released here, but since the future of that package is not clear, it has been forked and re-worked under this repository.

Goal

Pretty often we have to use images attached to models (like profile pictures) and the process to implement this is always pretty much the same: upload image, store it, resize it, move thumbnails and original to cloud storage and so on. Sometimes things get even a bit more complex and we have to re-size the existing images, remove the old ones and so on.

So the goal of this package is to provide a neat and clean way to work with these kind of images attached to models, in a way that allows us to store them (both locally and remotely) and work with them (resize them, remove old ones, etc), both synchronously and asynchronously, reducing the amount of work that we have to do to integrate this in our projects.

Installation

1. Install this package by adding it to your composer.json or by running composer require okaybueno/images in your project's folder.
2. For Laravel 5.5 the Service provider is automatically registered, but if you're using Laravel 5.4, then you must add the provider to your config/app.php file: OkayBueno\Images\ImageServiceProvider::class
3. Publish the configuration file by running php artisan vendor:publish --provider="OkayBueno\Images\ImageServiceProvider"
4. Open the configuration file (config/images.php) and configure the settings according to your needs. Keep reading to know what the parameters mean.
5. Ready to go!

Usage

The package provides 5 different things:

• Image Model: You can establish relations in your entities by using this model.
• Configuration file: It contains the settings for disks, image drivers to use and default settings for image processing.
• Image Service: It allows you to upload, process, and remove the images.
• Events/Listeners: Allow you to handle the operations with the images (process, move them to CDN, etc).
• Commands: Allow you to purge deleted images (destroy from disk) and resize existing ones.

Image Model

The model is located at OkayBueno\Images\Models\Image. You should include this model as a relation in all your models that may contain images. This model contains 2 main functions that just return some values:

+ thumbnails( $size = NULL, $onlyPath = FALSE): Calling this will return the thumbnails generated for this image. By default, the function returns the full URL for ALL thumbnails. You can also select just one size (1st param) or return just the path to the image (2nd param).

+ url(): Returns the full URL to the original image.

Configuration file

It contains the parameters that need to be configured to make the package work properly.

Image Service

The Image Service is bind to an interface located at OkayBueno\Images\Services\ImageServiceInterface.The service contains the next functions:

Events / Listeners

There are some events and listeners included:

EVENTS:

OkayBueno\Images\Events\ImageWasCreated: Triggered when a new image was successfully uploaded and created in the DB/local disk.
OkayBueno\Images\Events\ImageWasProcessed: Triggered when the image is processed and the thumbnails were generated (locally).
OkayBueno\Images\Events\ImageWasMovedToCloud: Triggered when the image (and all its thumbnails) were moved to the cloud disk.
OkayBueno\Images\Events\ImageWasDeleted: Triggered when an image gets deleted (soft deleted).

===========

LISTENERS:

OkayBueno\Images\Listeners\ProcessImageAsync: Processes the received image asynchronously (queued). It can subscribe to the ImageWasCreated event.
OkayBueno\Images\Listeners\ProcessImageSync: Processes the received image synchronously (not queued). It can subscribe to the ImageWasCreated event.
OkayBueno\Images\Listeners\MoveProcessedImagesToCloudImageAsync: Moves the processed image and its thumbnail to the cloud disk asynchronously (queued). It can subscribe to the ImageWasProcessed event.
OkayBueno\Images\Listeners\MoveProcessedImagesToCloudImageSync: Moves the processed image and its thumbnail to the cloud disk synchronously (not queued). It can subscribe to the ImageWasProcessed event.
OkayBueno\Images\Listeners\RemoveLocalImageAsync: Deletes the local files for the received image asynchronously (queued). It can subscribe to the ImageWasMovedToCloud event.
OkayBueno\Images\Listeners\RemoveLocalImageSync: Deletes the local files for the received image synchronously (not queued). It can subscribe to the ImageWasMovedToCloud event.

To configure them just add them to your EventServiceProvider located at app/Providers/EventServiceProvider.php

As you can see, there are Async and Sync events. Subscribe just to one of them, according to your needs.

Commands

There are 2 commands included, that help you maintain the images.

php artisan images:purge-deleted-images {--days=30}:

Takes all the images deleted --days or more days ago (30 by default) and destroys them from the DB and from the local and remote disks.

php artisan images:resize {--image-id=} {--image-type=} {--sizes=}

Resizes the given image (by -image-id) or the group of given images (by --image-type) to the new sizes provided via --sizes.

NOTE: --sizes should contain ALL the sizes, not only the new ones. All the other versions of the pic that do not exist in this parameter will be removed. This parameter should have this structure: "big:500x500,small:100x100,medium:x250".

Practical Example

Let's suppose you have a user entity with a profile pic. You should include the relation with the Image entity like this:

Whenever you need to update the image, you need to use the Image Service provided. We recommended that you handle the image creation and old images removal at once, so you can keep images updated and synchronized. An example of function would be the next one:

$image can be anything that can create an instance of an Intervention Image object.

Then, whenever you call your function to create or update your user, you can include this method to update the image:

In order to make all this work automatically, your EventServiceProvider should wire up the events and listeners:

This way, we are wiring up all the events to the listeners in order to:

• Once the image is created (E) --> Process the image asynchronously (L).
• Once that it's processed (E) --> Move it asynchronously to the cloud (L).
• Once that is moved to the cloud (E) --> Delete it from the local disk (L).

You can of course set this listeners to be processed automatically (by replacing 'Async' by 'Sync' in the name of the listener).

You can also decide if you use cloud disks, or if just store files just locally, etc... For example, you could choose not to move the files to the cloud and process them asynchronously, in which case you would have just something like this:

That's all! Simply put: the way you configure your events and listeners wil define the way that the files will be stored.

Changelog

-- No official version released yet --

Credits

• okay bueno - A fully transparent digital products studio
• Jesús Espejo (Twitter)

Bugs & contributing

• Found a bug? That's good (and bad). Let me know using the Issues on Github.
• Need a feature or have something interesting to contribute with? Great! Open a pull request.

To-dos

• Automated tests: Although this package is already used on production environments, there are no automated tests in place...

License

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