Thumbnails

Media Module

Basic Usage
Image quality
Refresh thumbnail command
Filters

Basic usage

You can define a set of thumbnails your site needs.

This can be done by using the ThumbnailManager interface and calling the registerThumbnail() on that.

Thumbnails are set by key and can have a set of attributes. For instance you could have a 'smallThumb' that crops the image and adds a blur filter. This is possible with this module.

For the example previously stated, you can call the following in your Module's Service Provider class in the boot() method:

$this->app[ThumbnailManager::class]->registerThumbnail('smallThumb', [
    'resize' => [
        'width' => 50,
        'height' => null,
        'callback' => function ($constraint) {
            $constraint->aspectRatio();
            $constraint->upsize();
        },
    ],
]);

This will make the Media module aware of your thumbnails.

Image quality

Each thumbnail can optionally also specify the image quality. This defaults to 90 and can be overwritten like so:

$this->app[ThumbnailManager::class]->registerThumbnail('smallThumb', [
    'quality' => 60,
    'resize' => [
        'width' => 50,
        'height' => null,
        'callback' => function ($constraint) {
            $constraint->aspectRatio();
            $constraint->upsize();
        },
    ],
]);

It is important you define your thumbnail with filters configuration before uploading any pictures. If you added new thumbnails or changed some thumbnail filters, after some media has already been uploaded you can run a refresh command to regenerate all thumbnails.

The following command will refresh all thumbnails:

php artisan asgard:media:refresh

Filters

The filters use the Intervention/Image library, almost all the filters it has can be used.

Crop
Fit
Blur
Brightness
Colorize
Contrast
Flip
Gamma
Greyscale
Heighten
Invert
LimitColors
Opacity
Orientate
Pixelate
Resize
Rotate
Sharpen
Trim
Widen
Canvas Resize

Crop

Example

 'crop' => [
    'width' => '100', // required 
    'height' => '200', // required 
    'x' => 0 // optional
    'y' => 0 // optional
],

Parameters

Width: [required] Width of the rectangular cutout.
Height: [required] Height of the rectangular cutout.
x: [optional] X-Coordinate of the top-left corner if the rectangular cutout. By default the rectangular part will be centered on the current image.
y: [optional] Y-Coordinate of the top-left corner if the rectangular cutout. By default the rectangular part will be centered on the current image.

Fit

Example

'fit' => [
    'width' => '100',
    'height' => '200',
    'position' => 'top-left',
    'callback' => function($constraint) {
        $constraint->upsize();
    }
],

Parameters

Width: [required] The width the image will be resized to after cropping out the best fitting aspect ratio.
Height: [optional] The height the image will be resized to after cropping out the best fitting aspect ratio. If no height is given, method will use same value as width.
position: [optional] Set a position where cutout will be positioned. By default the best fitting aspect ration is centered.

The possible values are:
- top-left
- top
- top-right
- left
- center (default)
- right
- bottom-left
- bottom
- bottom-right
callback: [optional] Closure callback defining constraint to prevent unwanted upsizing of the image.

Blur

Apply a gaussian blur filter with a optional amount on the current image. Use values between 0 and 100.

Example

'blur' => [
    'amount' => '15'
],

Parameters

amount: [optional] The amount of the blur strength. Use values between 0 and 100. Default: 1

Brightness

Changes the brightness of the current image by the given level. Use values between -100 for min. brightness 0 for no change and +100 for max. brightness.

Example

'brightness' => [
    'level' => '50'
],

Parameters

level: [required] Level of brightness change applied to the current image. Use values between -100 and +100.

Colorize

Change the RGB color values of the current image on the given channels red, green and blue. The input values are normalized so you have to include parameters from 100 for maximum color value 0 for no change and -100 to take out all the certain color on the image.

Example

'colorize' => [
    'red' => 0,
    'green' => 0,
    'blue' => 99
]

Parameters

red: [required] Add or take out a amount of red color on the image. Use values between -100 and +100.
green: [required] Add or take out a amount of green color on the image. Use values between -100 and +100.
blue: [required] Add or take out a amount of blue color on the image. Use values between -100 and +100.

Contrast

Changes the contrast of the current image by the given level. Use values between -100 for min. contrast 0 for no change and +100 for max. contrast.

Example

'contrast' => [
    'level' => '50'
],

Parameters

level: [required] Level of contrast change applied to the current image. Use values between -100 and +100.

Flip

Mirror the current image horizontally or vertically by specifying the mode.

Example

'flip' => [
    'mode' => 'h'
],

Parameters

mode: [required] Specify the mode the image will be flipped. You can set h for horizontal (default) or v for vertical flip.

Gamma

Performs a gamma correction operation on the current image.

Example

'gamma' => [
    'correction' => '1.6'
],

Parameters

correction: [required] Specify the mode the image will be flipped. You can set h for horizontal (default) or v for vertical flip.

Greyscale

Turns image into a greyscale version.

Example

'greyscale' => [],

Parameters

None

Heighten

Resizes the current image to new height, constraining aspect ratio. Pass an optional Closure callback as third parameter, to apply additional constraints like preventing possible upsizing.

Example

'heighten' => [
    'height' => '250'
    'callback' => function($constraint) {
        $constraint->upsize();
    }
],

Parameters

height: [required] The new height of the image
callback: [optional] Closure callback defining constraint to prevent unwanted upsizing of the image.

Invert

Reverses all colors of the current image.

Example

'invert' => [],

Parameters

None

LimitColors

Method converts the existing colors of the current image into a color table with a given maximum count of colors. The function preserves as much alpha channel information as possible and blends transparent pixels against a optional matte color.

Example

'limitColors' => [
    'count' => 255,
    'matte' => '#ff9900'
],

Parameters

count: [required] Maximum number of colors that should be retained in the color palette. Or null to convert to true color.
matte: [optional] A color to blend transparent pixels against. Default: no matte color

Opacity

Set the opacity in percent of the current image ranging from 100% for opaque and 0% for full transparency.

Note: Performance intensive on larger images. Use with care.

Example

'opacity' => [
    'transparency' => '40'
],

Parameters

transparency: [required] The new percent of transparency for the current image.

Orientate

This method reads the EXIF image profile setting 'Orientation' and performs a rotation on the image to display the image correctly.

Example

'orientate' => [],

Parameters

None

Pixelate

Applies a pixelation effect to the current image with a given size of pixels.

Example

'pixelate' => [
    'size' => 10
],

Parameters

size: [required] Size of the pixels.

Resize

Resizes current image based on given width and/or height. To constraint the resize command, pass an optional Closure callback as third parameter.

Example

'resize' => [
    'width' => 100,
    'height' => 100,
    'callback' => function($constraint) {
        $constraint->aspectRatio();
    }
],

Parameters

width: [required] The new width of the image
height: [required] The new height of the image
callback: [optional] Closure callback defining constraints on the resize. It's possible to constraint the aspect-ratio and/or a unwanted upsizing of the image.

Rotate

Rotate the current image counter-clockwise by a given angle. Optionally define a background color for the uncovered zone after the rotation.

Example

'rotate' => [
    'angle' => -45,
    'bgcolor' => '#000000',
],

Parameters

angle: [required] The rotation angle in degrees to rotate the image counter-clockwise.
bgcolor: [required] A background color for the uncovered zone after the rotation. Default: #000000

Sharpen

Sharpen current image with an optional amount. Use values between 0 and 100.

Example

'sharpen' => [
    'amount' => 10
],

Parameters

amount: [optional] The amount of the sharpening strength. Method accepts values between 0 and 100. Default: 10

Trim

Trim away image space in given color. Define an optional base to pick a color at a certain position and borders that should be trimmed away. You can also set an optional tolerance level, to trim similar colors and add a feathering border around the trimmed image.

Note: Resource intensive with GD driver. Use with care.

Example

'trim' => [
    'base' => 'top-left',
    'away' => 'top',
    'tolerance' => 0,
    'feather' => 0,
],

Parameters

base: [required] Define the the point from where the trimming color is picked. For example if you set this parameter to bottom-right, all color will be trimmed away that is equal to the color in the bottom-left corner of the image.

Possible values are:
- top-left (default)
- bottom-right
- transparent
away: [optional] Border(s) that should be trimmed away. You can add multiple borders. as an array of values.

Possible values are:
- top
- bottom
- left
- right
By default the trimming is performed on all borders.
tolerance: [optional] Define a percentaged tolerance level between 0 and 100 to trim away similar color values. Default: 0
feather: [optional] Sometimes it may be useful to leave a untouched "border" around an object while trimming. Especially when trimming non-solid backgrounds you can expand (positive value) or contract (negative value) the space around the trimmed object by a certain amount of pixels. Default: 0

Widen

Resizes the current image to new width, constraining aspect ratio. Pass an optional Closure callback as third parameter, to apply additional constraints like preventing possible upsizing.

Example

'heighten' => [
    'width' => '250'
    'callback' => function($constraint) {
        $constraint->upsize();
    }
],

Parameters

width: [required] The new width of the image
callback: [optional] Closure callback defining constraint to prevent unwanted upsizing of the image.

Canvas Resize

Resize the boundaries of the current image to given width and height. An anchor can be defined to determine from what point of the image the resizing is going to happen. Set the mode to relative to add or subtract the given width or height to the actual image dimensions. You can also pass a background color for the emerging area of the image.

Example

'resizeCanvas' => [
    'width' => 100,
    'height' => 100,
    'anchor' => 'center',
    'relative' => false,
    'bgcolor' => 'rgba(255, 255, 255, 0)',
],

Parameters

width: [required] The new width in pixels of the image in absolute mode or the amount of pixels to add or subtract from height in relative mode.
height: [required] The new height in pixels of the image in absolute mode or the amount of pixels to add or subtract from height in relative mode.
anchor: [optional]

Set a point from where the image resizing is going to happen. For example if you are setting the anchor to bottom-left this side is pinned and the values of width/height will be added or subtracted to the top-right corner of the image.

The possible values for this parameter are:
- top-left
- top
- top-right
- left
- center (default)
- right
- bottom-left
- bottom
- bottom-right
relative: [optional] Determine that the resizing is going to happen in relative mode. Meaning that the values of width or height will be added or substracted from the current height of the image. Default: false
bgcolor: [optional] A background color for the new areas of the image. The background color can be passed in in different color formats. Default: #000000

Documentation

Thumbnails