https://github.com/reliqarts/laravel-guided-image
Simplified and ready image manipulation for Laravel through intervention image.
https://github.com/reliqarts/laravel-guided-image
hacktoberfest intervention-image laravel laravel-6 laravel-6-package laravel-7 laravel-7-package laravel-8 laravel-8-package routing trait upload view
Last synced: 3 months ago
JSON representation
Simplified and ready image manipulation for Laravel through intervention image.
- Host: GitHub
- URL: https://github.com/reliqarts/laravel-guided-image
- Owner: reliqarts
- License: mit
- Created: 2016-10-20T07:08:14.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2025-03-19T11:33:02.000Z (3 months ago)
- Last Synced: 2025-03-28T11:51:14.506Z (3 months ago)
- Topics: hacktoberfest, intervention-image, laravel, laravel-6, laravel-6-package, laravel-7, laravel-7-package, laravel-8, laravel-8-package, routing, trait, upload, view
- Language: PHP
- Homepage:
- Size: 467 KB
- Stars: 34
- Watchers: 5
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Laravel Guided Image
Guided Image is an image utility package for Laravel based on Intervention Image.
[](http://laravel.com)
[](https://travis-ci.com/reliqarts/laravel-guided-image)
[](https://scrutinizer-ci.com/g/reliqarts/laravel-guided-image/)
[](https://codecov.io/gh/reliqarts/laravel-guided-image)
[](https://codeclimate.com/github/reliqarts/laravel-guided-image/maintainability)
[](https://packagist.org/packages/reliqarts/laravel-guided-image)
[](https://packagist.org/packages/reliqarts/laravel-guided-image)
[](//packagist.org/packages/reliqarts/laravel-guided-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*:
```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](https://github.com/ReliqArts/laravel-guided-image/blob/master/config/config.php) file.
And... it's ready! :ok_hand:
### Usage
To *use* Guided Image you must do just that from your *Image* model. :smirk:
Implement the `ReliqArts\GuidedImage\Contract\GuidedImage` contract and use the `ReliqArts\GuidedImage\Concern\Guided` trait, e.g:
```php
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](https://github.com/ReliQArts/laravel-guided-image/blob/master/docs/examples/Image.php).
Implement the `ReliqArts\GuidedImage\Contract\ImageGuide` contract and use the `ReliqArts\GuidedImage\Concern\Guide` trait from your *ImageController*, e.g:
```php
use ReliqArts\GuidedImage\Contract\ImageGuide;
use ReliqArts\GuidedImage\Concern\Guide;
class ImageController extends Controller implements ImageGuide
{
use Guide;
}
```
See example [here](https://github.com/ReliQArts/laravel-guided-image/blob/master/docs/examples/ImageController.php).
#### Features
##### Safely Remove Image (dissociate & conditionally delete the image)
An guided image instance is removed by calling the *remove* method. e.g:
```php
$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:
```php
// 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](https://github.com/ReliQArts/laravel-guided-image/blob/master/src/Contract/GuidedImage.php) for more info on model functions.
For more info on controller functions see the [ImageGuide contract](https://github.com/reliqarts/laravel-guided-image/blob/master/src/Contract/ImageGuide.php).
##### 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 |
```