1# Slika - simple image handling for PHP 2 3This is a library that covers only the bare basics you need when handling images: 4 5 * resizing 6 * cropping 7 * rotation 8 9It can use either PHP's libGD or a locally installed ImageMagick binary. 10 11## Installation 12 13Use composer 14 15 composer require splitbrain/slika 16 17## Usage 18 19Simply get an Adapter from the Slika factory, run some operations on it and call `save`. 20 21Operations can be chained together. Consider the chain to be one command. Do not reuse the adapter returned by `run()`, it is a single use object. All operations can potentially throw a `\splitbrain\slika\Exception`. 22 23Options (see below) can be passed as a second parameter to the `run` factory. 24 25```php 26use \splitbrain\slika\Slika; 27use \splitbrain\slika\Exception; 28 29$options = [ 30 'quality' => 75 31]; 32 33try { 34 Slika::run('input.png', $options) 35 ->resize(500,500) 36 ->rotate(Slika::ROTATE_CCW 37 ->save('output.jpg', 'jpg'); 38} catch (Exception $e) { 39 // conversion went wrong, handle it 40} 41``` 42 43Please also check the [API Docs](https://splitbrain.github.io/slika/) for details. 44 45## Operations 46 47### resize 48 49All resize operations will keep the original aspect ratio of the image. There will be no distortion. 50 51Keeping either width or height at zero will auto calculate the other value for you. 52 53```php 54# fit the image into a bounding box of 500x500 pixels 55Slika::run('input.jpg')->resize(500,500)->save('output.png', 'png'); 56 57# adjust the image to a maximum width of 500 pixels 58Slika::run('input.jpg')->resize(500,0)->save('output.png', 'png'); 59 60# adjust the image to a maximum height of 500 pixels 61Slika::run('input.jpg')->resize(0,500)->save('output.png', 'png'); 62``` 63 64By default, images smaller than the given dimensions are enlarged. That is not always desirable 65because the quality will suffer. Pass `false` as the third parameter to disable upscaling. The 66image is then never grown beyond its original size (it is returned unchanged when it already fits 67into the bounding box). 68 69```php 70# fit into 500x500 but never enlarge a smaller image 71Slika::run('input.jpg')->resize(500,500,false)->save('output.png', 'png'); 72``` 73 74### crop 75 76Similar to resizing, but this time the image will be cropped to fit the new aspect ratio. 77 78```php 79Slika::run('input.jpg')->crop(500,500)->save('output.png', 'png'); 80``` 81 82Cropping also accepts the `$upscale` parameter. When set to `false` an image that is 83smaller than the requested crop area is never enlarged: dimensions larger than the image 84are cropped, smaller ones are left untouched, and an image that fits entirely into the 85area is returned as is. This means that the output image may be smaller than the requested 86crop area and might have a different aspect ratio than requested. 87 88```php 89# crop to 500x500 but never enlarge a smaller image 90Slika::run('input.jpg')->crop(500,500,false)->save('output.png', 'png'); 91``` 92 93### rotate 94 95Rotates the image. The parameter passed is one of the EXIF orientation flags: 96 97 98 99For your convenience there are three Constants defined: 100 101 102* `Slika::ROTATE_CCW` counter clockwise rotation 103* `Slika::ROTATE_CW` clockwise rotation 104* `Slika::ROTATE_TOPDOWN` full 180 degree rotation 105 106```php 107Slika::run('input.jpg')->rotate(Slika::ROTATE_CW)->save('output.png', 'png'); 108``` 109 110### autorotate 111 112Rotates the image according to the EXIF rotation tag if found. 113 114```php 115Slika::run('input.jpg')->autorotate()->save('output.png', 'png'); 116``` 117 118## Inspecting images without processing them 119 120Sometimes you need to know what dimensions an image *would* have after a chain of operations without actually decoding pixels or calling ImageMagick — for example, to emit `<img width="…" height="…">` attributes on a page that references a resize URL. 121 122`\splitbrain\slika\ImageInfo` mirrors the Adapter's fluent API at the dimension level. It reads only `getimagesize()` and the EXIF orientation tag, never touching the pixel data. 123 124```php 125use \splitbrain\slika\ImageInfo; 126 127$info = new ImageInfo('input.jpg'); 128 129// on-disk state (stable regardless of chain operations) 130$info->getRawWidth(); // e.g. 4000 131$info->getRawHeight(); // e.g. 3000 132$info->getExtension(); // 'jpeg' 133$info->getOrientation(); // EXIF orientation 1..8 134 135// the fluent chain simulates autorotate/rotate/resize/crop 136// and returns the final tracked dimensions 137list($w, $h) = (new ImageInfo('input.jpg')) 138 ->autorotate() 139 ->resize(500, 500) 140 ->getDimensions(); 141``` 142 143This lets you predict the output of `Slika::run(...)->autorotate()->resize(500,500)` 144without doing any actual image work. 145 146## Options 147 148Options can be passed as associatiave array as the second parameter in `Slika::run`. 149 150The following options are availble currently: 151 152| Option | Default | Description | 153|-------------|--------------------|--------------------------------------------| 154| `imconvert` | `/usr/bin/convert` | The path to ImageMagick's `convert` binary | 155| `quality` | `92` | The quality when writing JPEG images | 156
){kind=link}