jitimage
, (*1)
Just In Time image manipulation with integration for Laravel 4, supports GD, ImageMagick, and Imagick., (*2)
Installation
Add thapp/jitimage as a requirement to composer.json:, (*3)
{
"require": {
"php":">=5.4.0",
"thapp/jitimage": "~0.1"
}
}
Then run composer update or composer install, (*4)
Next step is to tell laravel to load the service provider. In app/config/app.php add, (*5)
// ...
'Thapp\JitImage\JitImageServiceProvider'
// ...
to the providers array and add JitImage to the alias array:, (*6)
'aliases' => [
'JitImage' => 'Thapp\JitImage\Facades\JitImage'
],
Publish configuration
php artisan config:publish thapp/jitimage
Configuration
route (string)
The base route for dynamic image processing, (*7)
base (string)
The filesystem base path to where your images are stored., (*8)
driver (string)
The processing driver. Available drivers are im, gd and ìmagick, (*9)
cache.route (string)
The base route for retrieving images by their cache id, (*10)
cache.path (string)
Cache directory, (*11)
cache.environments (array)
An array of environments were imagecache should be enabled, (*12)
cache.prefix (string)
Name prefix for cached images, (*13)
quality (string)
compression quality, 0 - 100 (higher is better but also larger), (*14)
imagemagick (array)
This array takes two values: path, the path to the imagick binary, and bin, the binary name.
Typically the binary name is convert., (*15)
filter (array)
An array of available filter that should be enabled by default, (*16)
recipes (array)
An array of predefined parameters that are aliased to a route, e.g., (*17)
'recipes' => [
'thumbs' => '2/200/200/5, filter:gs'
],
would create a route 'thumbs' that could be called like http://example.com/thumbs/path/to/my/image.jpg.
Defining recipes will disable dynamic image processing., (*18)
response-type (string)
You can choose generic or xsend., (*19)
Note: your server must be capable to handle x-send headers when using the
xsend response type., (*20)
'response-type' => 'generic'
trusted-sites (array)
A list of trusted sites that deliver assets, e.g., (*21)
http://25.media.tumblr.com
or as a regexp, (*22)
http://[0-9]+.media.tumblr.(com|de|net)
Image Processors
GD
GD is the standard php image processing library. Choose gd if you have either
no access to imagemagick or to the imagick php extension., (*23)
There're a few downsides when using gd though, e.g. color profiles are not preserved, there's no support for preserving image sequences when processing an animated gif file.
It also has a larger memory footprint so can become impossible in some cases (memory limitations on shared hosting
platforms, etc.)., (*24)
ImageMagick
Imagemagick is an incredible fast and versatile image processing library. Choose im
in your config.php, if you have access to the convert binary., (*25)
For further information on imagemagick please visit the official website, (*26)
Imagick
Imagick is imagemagick OOP for php. Choose imagick if you have the
imagick
extensions installed but no access to the imagemagick binary., (*27)
Usage
Dynamic image processing
A word of warning: Dynamic image processing can harm you system and should be disabled in production., (*28)
Anatomy of an image uri:, (*29)
{base}/{parameter}/{imagesource}/filter:{filter}, (*30)
Parameter consists of one to five components, mode, width, height, gravity (crop position), and background, (*31)
An Image url my look like this: http://exmaple.com/images/2/200/200/5/path/to/my/image.jpg
To apply additional filters, the filter url segment is appended. The filter segments starts with filter: followed by the filter alias and the filter options. Filters are separated by a double colon :, filter parameter are separated by a semicolon ;, eg filter:gs;s=100;c=1:circ;o=12., (*32)
Examples
Example URLs (assuming you have set route to 'images' and your images are
stored in public/uploads/images., (*33)
resizing
Proportionally resize an image to 200px width:, (*34)
http://example.com/images/1/200/0/uploads/images/image.jpg, (*35)
Resize an image to 200 * 200 px, ignoring its aspect ratio :, (*36)
http://example.com/images/1/200/200/uploads/images/image.jpg, (*37)
Proportionally resize an image to best fit 400 * 280 px:, (*38)
http://example.com/images/4/400/280/uploads/images/image.jpg, (*39)
Scale an image down to 50%:, (*40)
http://example.com/images/5/50/uploads/images/image.jpg, (*41)
Limit to 200.000px pixel:, (*42)
http://example.com/images/6/200000/uploads/images/image.jpg, (*43)
cropping
Proportionally crop and resize an image to 200px * 200px with a gravity of
5 (center):, (*44)
http://example.com/images/2/200/200/5/uploads/images/image.jpg, (*45)
Predefined image processing
(will disable dynamic processing), (*46)
You can alias your image processing with predefined recipes., (*47)
Examples
Map mode 2 crop rescale, with a 200x200 px crop and a grey scale
filter to http://example.com/thumbs/uploads/images/image.jpg:, (*48)
'thumbs' => '2/200/200/5, filter:gs'
Map mode 1 resize, with a resize of 800px width and a
greyscale filter to http://example.com/gellery/uploads/images/image.jpg:, (*49)
'gallery' => '1/800/0, filter:gs',
Map mode 4 best fit, with a resize of max 800px width and 600px height, to http://example.com/preview/uploads/images/image.jpg:, (*50)
'preview' => '4/800/600'
Modes
mode 0
Pass through, no processing., (*51)
mode 1 < width/height >
Resizes the image with the given width and height values and ignores aspect
ratio unless one of the values is zero., (*52)
mode 2 < width/height/gravity >
Resize the image to fit within the cropping boundaries defined in width and height., (*53)
Gravity explained:, (*54)
-------------
| 1 | 2 | 3 |
-------------
| 4 | 5 | 6 |
-------------
| 7 | 8 | 9 |
-------------
mode 3 < width/height/gravity/[color] >
Crops the image with cropping boundaries defined in width and height. Will
create a frame if the image is smaller than the cropping area., (*55)
mode 4 < width/height >
Best fit within the given bounds., (*56)
mode 5 < percentage >
Percrentual scale., (*57)
mode 6 < pixelcount >
Pixel limit., (*58)
You may utilize the Convert filter (conv) to convert an image to
a different file format., (*59)
As uri:, (*60)
// convert png to jpg:
'/images/<params>/<source>/filter:conf;f=jpg'
The JitImage class also provides some shortcut methods for this: toJpeg,
toPng, and toGif, (*61)
// convert png to jpg:
JitImage::source($filePNG)->toJpeg()->get();
JitImage::source($fileJPP)->toPng()->scale(50);
Filters
JitImage comes with 4 predfined filters, GreyScale, Cirlce, Overlay,
Colorize, and Convert (since v0.1.3):, (*62)
(Note: since v0.1.4. calling invalid arguments on a filter will throw an
\InvalidArgumentException), (*63)
GreyScale
- alias `gs`
- options (not available for the `gd` driver)
- `b` (Brightness){integer}, 0-100
- `s` (Satturation){integer}, 0-100
- `h` (Hue){integer}, 0-100
- `c` (Contrast){integer} 0 or 1
Circle
- alias `circ`
- options
- `o` {integer} offset, any positive integer value
Overlay
- alias `ovly`
- options
- `a` (alpha) {float} a float value between 0 and 1
- `c` (color) {string} hex representation of an rgb value
Colorize
- alias `clrz`
- options
- `c` (color){string} hex representation of an rgb value
Convert
- alias `conv`
- options
- `f` (file format){string} a valid image file extension such as `png`, `jpg`, etc.
The facade class
This is a convenient way to scale images within your blade templates. It will create an imageurl similar to /jit/storage/2egf4gfg/jit_139e2ead8b71b8c7e.jpg, (*64)
Note: this won't work if both caching and dynamic processing are disabled.
Note: Filters (including the convert shorthands) must be called before any other maipulation method, as resize, scale, etc. will immediately return the computed filesource as string., (*65)
// get the original image:
JitImage::source('path/to/myimage.jpg')->get();
// proportionally resize the image have a width of 200px:
JitImage::source('path/to/myimage.jpg')->resize(200, 0);
// resize the image have a width and height of 200px (ignores aspect ratio):
JitImage::source('path/to/myimage.jpg')->resize(200, 200);
// crop 500px * 500px of the image from the center, creates a frame if image is smaller.
JitImage::source('path/to/myimage.jpg')->crop(500, 500, 5);
// You may also specify a background color for the frame:
JitImage::source('path/to/myimage.jpg')->crop(500, 500, 5, 'fff');
// crop 500px * 500px of the image from the center, resize image if image is smaller:
JitImage::source('path/to/myimage.jpg')->cropAndResize(500, 500, 5);
// resize the image to best fit within the given sizes:
JitImage::source('path/to/myimage.jpg')->fit(200, 200);
// crop 200px * 200px of the image from the center, resize image if image is smaller and apply a greyscale filter:
JitImage::source('path/to/myimage.jpg')->filter('gs')->cropAndResize(200, 200, 5);
// Percentual scale the image:
JitImage::source('path/to/myimage.jpg')->scale(50);
// Limit the image to max. 200000px:
JitImage::source('path/to/myimage.jpg')->pixel(200000);
// Convert png to jpg:
JitImage::source('path/to/myimage.png')->toJpeg()->get();
Register external filter
You may add your own filter classes to be used with JitImage., (*66)
(more to come)., (*67)
Event::listen('jitimage.registerfilter', function ($driverName) {
return [
"mf" => sprintf("Namespace\\Filter\MyFilter\\%s%s", ucfirst($driverName) , 'MfFilter')
];
});
Caching
Artisan commands
There's really just one command right now. php artisan jitimage:clearcache will clear the whole image cache., (*68)
Deleting a cached image if its source file got replaced
It is possible to just delete cached images that have been created from
a certain source. So lets assume you have to replace an image called myimage.jpg in uploads/images,
you could tell the cache class to to remove this specific cache directory., (*69)
$app['jitimage.cache']->delete('uploads/images/myimage.jpg');
You may also hoock this up to an upload event, (*70)
// attention! pseudo code:
Event::listen('image.upload', function ($event) use ($app) {
$app['jitimage.cache']->delete($event->image);
});
API
API documentation will be updated shortly., (*71)
Wallogit.com
