reliqarts / laravel-guided-image
Simplified and ready image manipulation for Laravel via intervention image.
Fund package maintenance!
reliq
Installs: 1 226
Dependents: 0
Suggesters: 0
Security: 0
Stars: 34
Watchers: 6
Forks: 3
Open Issues: 0
Requires
- php: ^8.2
- ext-fileinfo: *
- ext-json: *
- anhskohbo/no-captcha: @dev
- illuminate/support: ^11.1
- intervention/image: ^3.7
- reliqarts/laravel-common: ^8.0
Requires (Dev)
- laravel/pint: ^1.15
- orchestra/testbench: ^9.0
- phpro/grumphp: ^2.5
- phpspec/prophecy-phpunit: ^2.0
- phpunit/phpunit: ^11.0
- yieldstudio/grumphp-laravel-pint: ^1.0
- dev-main
- v5.1.1
- v5.1.0
- v5.0.0
- v4.4.2
- v4.4.1
- v4.4.0
- v4.3.0
- v4.2.6
- v4.2.5
- v4.2.4
- v4.2.3
- v4.2.2
- v4.2.1
- v4.2.0
- v4.1.0
- v4.0.0
- v3.3.1
- v3.3.0
- v3.2.2
- v3.2.1
- v3.2.0
- v3.0.1
- v3.0.0
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v2.0.0-beta.6
- v2.0.0-beta.5
- v2.0.0-beta.4
- v2.0.0-beta.3
- v2.0.0-beta.2
- v2.0.0-beta.1
- v2.0.0-beta
- v1.1.1
- v1.1.0
- v1.0.12
- v1.0.11
- v1.0.10
- v1.0.9
- v1.0.8
- v1.0.7
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
This package is auto-updated.
Last update: 2024-11-08 00:52:06 UTC
README
Guided Image is an image utility package for Laravel based on Intervention Image.
Key Features
- On-the-fly image resizing
- On-the-fly thumbnail generation
- Image uploading
- Smart image reuse; mitigating against double uploads and space resource waste.
Guided Image can be integrated seamlessly with your existing image model.
Guided Routes
The package provides routes for generating resized/cropped/dummy images.
- Routes are configurable you you may set any middleware and prefix you want.
- Generated images are cached to disk to avoid regenerating frequently accessed images and reduce overhead.
Image file reuse
For situations where different instances of models use the same image.
- The package provides a safe removal feature which allows images to be detached and only deleted from disk if not being used elsewhere.
- An overridable method is used to determine when an image should be considered safe to delete.
Installation & Usage
Installation
Install via composer; in console:
composer require reliqarts/laravel-guided-image
or require in composer.json:
{ "require": { "reliqarts/laravel-guided-image": "^5.0" } }
then run composer update
in your terminal to pull it in.
Finally, publish package resources and configuration:
php artisan vendor:publish --provider="ReliqArts\GuidedImage\ServiceProvider"
You may opt to publish only configuration by using the guidedimage-config
tag:
php artisan vendor:publish --provider="ReliqArts\GuidedImage\ServiceProvider" --tag="guidedimage-config"
Setup
Set the desired environment variables so the package knows your image model, controller(s), etc.
Example environment config:
GUIDED_IMAGE_MODEL=Image
GUIDED_IMAGE_CONTROLLER=ImageController
GUIDED_IMAGE_ROUTE_PREFIX=image
GUIDED_IMAGE_SKIM_DIR=images
These variables, and more are explained within the config file.
And... it's ready! 👌
Usage
To use Guided Image you must do just that from your Image model. 😏
Implement the ReliqArts\GuidedImage\Contract\GuidedImage
contract and use the ReliqArts\GuidedImage\Concern\Guided
trait, e.g:
use Illuminate\Database\Eloquent\Model; use ReliqArts\GuidedImage\Concern\Guided; use ReliqArts\GuidedImage\Contract\GuidedImage; class Image extends Model implements GuidedImage { use Guided; // ... properties and methods }
See example here.
Implement the ReliqArts\GuidedImage\Contract\ImageGuide
contract and use the ReliqArts\GuidedImage\Concern\Guide
trait from your ImageController, e.g:
use ReliqArts\GuidedImage\Contract\ImageGuide; use ReliqArts\GuidedImage\Concern\Guide; class ImageController extends Controller implements ImageGuide { use Guide; }
See example here.
Features
Safely Remove Image (dissociate & conditionally delete the image)
An guided image instance is removed by calling the remove method. e.g:
$oldImage->remove($force);
$force
is optional and is false
by default.
Link Generation
You may retrieve guided links to resized or cropped images like so:
// resized image: $linkToImage = $image->routeResized([ '550', // width '_', // height, 'null' is OK '_', // keep aspect ratio? true by default, 'null' is OK '_', // allow upsize? false by default, 'null' is OK ]); // thumbnail: $linkToImage = $image->routeThumbnail([ 'crop', // method: crop|fit '550', // width '_', // height ]);
NB: In the above example _
resolves to null
.
Have a look at the GuidedImage contract for more info on model functions.
For more info on controller functions see the ImageGuide contract.
Routes
Your actually routes will depend heavily on your custom configuration. Here is an example of what the routes may look like:
|| GET|HEAD | image/.dum//{width}-{height}/{color?}/{fill?} | image.dummy | App\Http\Controllers\ImageController@dummy | web |
|| GET|HEAD | image/.res/{image}//{width}-{height}/{aspect?}/{upSize?}| image.resize | App\Http\Controllers\ImageController@resized | web |
|| GET|HEAD | image/.tmb/{image}//m.{method}/{width}-{height} | image.thumb | App\Http\Controllers\ImageController@thumb | web |
|| GET|HEAD | image/empty-cache | image.empty-cache | App\Http\Controllers\ImageController@emptyCache | web |