This package adds ways to store and link images to your models.
It provides:
You can install the package via composer:
composer require outerweb/image-library
Run the install command:
php artisan image-library:install
Add the <x-image-library-scripts />
blade component to your layout (at the bottom of the body tag).
<x-image-library-scripts />
This will add a script tag to the bottom of the body tag that will dynamically set the image width as the sizes attribute of the image tag. This is an automatic way of letting the browser know which responsive image variant to download based on the device's screen size, resolution, density and supported image formats.
You can configure the package by editing the config/image-library.php
file.
Each setting is documented in the config file itself.
You can define conversions anywhere in your application. We recommend doing this in a service provider.
To do this, you can use the ConversionDefinition
entity.
use OuterWeb\ImageLibrary\Facades\ImageLibrary;
use OuterWeb\ImageLibrary\Entities\AspectRatio;
use OuterWeb\ImageLibrary\Entities\ConversionDefinition;
use OuterWeb\ImageLibrary\Entities\Effects;
ImageLibrary::addConversionDefinition(
ConversionDefinition::make()
->name('thumbnail')
->label('Thumbnail')
->translateLabel()
->aspectRatio(
AspectRatio::make()
->x(1)
->y(1)
)
->defaultWidth(100)
->defaultHeight(100)
->effects(
Effects::make()
->blur(10)
->pixelate(10)
->greyscale()
->sepia()
->sharpen(10)
)
->createSync()
);
The name of the conversion. This is the name you will use to refer to the conversion.
use OuterWeb\ImageLibrary\Entities\ConversionDefinition;
ConversionDefinition::make()
->name('thumbnail');
The label of the conversion. This is can be used by other packages that depend on this package to show the label in the user interface. E.g. in our Filament Image Library package, this is used to display the conversion name above the cropper.
use OuterWeb\ImageLibrary\Entities\ConversionDefinition;
ConversionDefinition::make()
->label('Thumbnail');
Whether the label should be translated. By default, the label will not be translated. This method will take the value of the label and put it through the __()
function.
use OuterWeb\ImageLibrary\Entities\ConversionDefinition;
ConversionDefinition::make()
->label('conversions.labels.thumbnail');
->translateLabel();
The aspect ratio of the conversion. You can define this by using the AspectRatio
entity.
use OuterWeb\ImageLibrary\Entities\AspectRatio;
use OuterWeb\ImageLibrary\Entities\ConversionDefinition;
ConversionDefinition::make()
->aspectRatio(
AspectRatio::make()
->x(1)
->y(1)
);
Or by providing a string.
use OuterWeb\ImageLibrary\Entities\ConversionDefinition;
ConversionDefinition::make()
->aspectRatio('16:9');
Or by providing an array.
use OuterWeb\ImageLibrary\Entities\ConversionDefinition;
ConversionDefinition::make()
->aspectRatio([16, 9]);
The default width and height of the conversion. This is the size the image will be cropped to by default. These values are overridden by the width and height saved in the database.
use OuterWeb\ImageLibrary\Entities\ConversionDefinition;
ConversionDefinition::make()
->defaultWidth(100)
->defaultHeight(100);
You can apply effects to the conversion. You can define this by using the Effects
entity.
use OuterWeb\ImageLibrary\Entities\ConversionDefinition;
use OuterWeb\ImageLibrary\Entities\Effects;
ConversionDefinition::make()
->effects(
Effects::make()
->blur(10)
->pixelate(10)
->greyscale()
->sepia()
->sharpen(10)
);
Or by providing an array.
use OuterWeb\ImageLibrary\Entities\ConversionDefinition;
ConversionDefinition::make()
->effects([
'blur' => 10,
'pixelate' => 10,
'greyscale' => true,
'sepia' => true,
'sharpen' => 10
]);
You can inform the image library to dispatch the generateConversion job synchronously. This is done to make the thumbnail generation conversion visible immediately after uploading an image when using a async queue driver.
use OuterWeb\ImageLibrary\Entities\ConversionDefinition;
ConversionDefinition::make()
->createSync();
You can upload images to the library by using the ImageLibrary
facade.
use OuterWeb\ImageLibrary\Facades\ImageLibrary;
$image = ImageLibrary::upload($request->file('image'));
By default, the image will be stored in the public
disk. You can change this by setting the default_disk
option in the config file or by passing it as the second argument to the upload
method.
use OuterWeb\ImageLibrary\Facades\ImageLibrary;
$image = ImageLibrary::upload($request->file('image'), 's3');
You may also pass a title and alt text in the third argument.
use OuterWeb\ImageLibrary\Facades\ImageLibrary;
$image = ImageLibrary::upload($request->file('image'), 's3', [
'title' => 'My image',
'alt' => 'This is my image'
]);
If you want those attributes to be translatable, we have directly integrated Spatie's laravel-translatable
package. To enable this, you need to set the spatie_translatable
option to true
in the config file. After that, you can pass the translations in the third argument.
use OuterWeb\ImageLibrary\Facades\ImageLibrary;
$image = ImageLibrary::upload($request->file('image'), 's3', [
'title' => [
'en' => 'My image',
'nl' => 'Mijn afbeelding'
],
'alt' => [
'en' => 'This is my image',
'nl' => 'Dit is mijn afbeelding'
]
]);
When an image is uploaded, these things will happen:
images
table. You can use the Image model to interact with this record.image_conversions
table.You can render images by using the <x-image-library-image />
blade component.
<x-image-library-image :image="$image" conversion="thumbnail" />
This will render a responsive image with the thumbnail
conversion.
You can also render a <x-image-library-picture />
blade component.
<x-image-library-picture :image="$image" conversion="thumbnail" />
This gives the browser the ability to choose the best image to download based on the device's screen size, resolution, density and supported image formats.
You can provide a fallback image by using the fallback
attribute.
<x-image-library-image :image="$image" conversion="thumbnail" fallback="fallback-image.jpg" />
This can be a string or another Image
model.
The fallback image will be rendered using the conversion defined in the conversion
attribute.
You can provide a fallback conversion by using the fallback-conversion
attribute.
<x-image-library-image :image="$image" conversion="thumbnail" fallback-conversion="original" />
Combining this with the fallback
attribute, you can have different outcomes when the image and/or conversion are not available:
fallback
attribute and a fallback-conversion
attribute will render the fallback image using the fallback conversion if the fallback image is an Image
model.fallback
attribute will render the fallback image using the fallback conversion if the fallback image is an Image
model.fallback-conversion
attribute will render the image using the fallback conversion.You may link images to your models by any means you like. The package does not provide a way to do this.
You are free to create:
The package provides an Image
model that you can use to interact with the images table.
You may change the model by setting the models.image
option in the config file.
It saves the following data in the database:
id
: The primary keyuuid
: Used as directory name when storing the image on diskdisk
: The disk on which the image is storedmime_type
: The mime type of the imagefile_extension
: The file extension of the imagewidth
: The width of the image in pixelsheight
: The height of the image in pixelssize
: The size of the image in bytestitle
: The title of the image (stored as json to optionally support translations)alt
: The alt text of the image (stored as json to optionally support translations)created_at
: The creation dateupdated_at
: The last update dateThe package provides an ImageConversion
model that you can use to interact with the image_conversions table.
You may change the model by setting the models.image_conversion
option in the config file.
It saves the following data in the database:
id
: The primary keyimage_id
: The id of the imageconversion_name
: The name of the conversionconversion_md5
: The md5 hash of the conversion to check if a conversion images needs to be re-generated after changing the ConversionDefinitionwidth
: The width of the conversion image in pixelsheight
: The height of the conversion image in pixelssize
: The size of the conversion image in bytesx
: The x coordinate to crop the image aty
: The y coordinate to crop the image atrotate
: The rotation of the image in degrees (0, 90, 180, 270)scale_x
: The x scale of the imagescale_y
: The y scale of the imagecreated_at
: The creation dateupdated_at
: The last update datePlease see UPGRADING for information on upgrading to a new major version.
Please see CHANGELOG for more information on what has changed recently.
The MIT License (MIT). Please see License File for more information.