Handling Images
The Vanilo Framework supports assigning images to products, taxonomies and taxons.
This functionality is not present in the product and category modules, it is an additional layer provided by the framework with the help of the Spatie Media Library and a few Vanilo traits.
It means that if you're not using the Framework, you can either:
- use your very own implementation, or
- you can simply take the solution from the Vanilo Framework and copy it to your app.
The HasImages Interface
The contracts package defines the HasImages
interface
that has 6 image related methods:
-
hasImage(): bool
-
imageCount(): int
(since v2.1) -
getThumbnailUrl(): ?string
-
getThumbnailUrls(): Collection
(since v2.1) -
getImageUrl(string $variant = ''): ?string
-
getImageUrls(string $variant = ''): Collection
(since v2.1)
The support package offers the HasImagesFromMediaLibrary
trait that can be added to any Eloquent Model. The trait implements the 6 methods listed above from
the HasImages
interface. Adding the trait along with Spatie's InteractsWithMedia
will enable the
model class to have images assigned to it.
Define Image Variants
The Spatie Media library supports defining various image sizes, so-called Conversions.
The uploaded images will be then converted to the given sizes with the given parameters.
Vanilo Framework takes a step forward and allows you to define those conversions in the config file.
It's quite common that products and categories need different image sizes in the HTML layout. Therefore, beginning with v2.1, Vanilo supports defining conversions on a per model base:
// config/vanilo.php
return [
// ...
'framework' => [
'image' => [
'product' => [
'variants' => [
'thumbnail' => [ // Name of the image variant
'width' => 250,
'height' => 250,
'fit' => 'crop'
],
'cart' => [ // Image variant names can be arbitrary
'width' => 120,
'height' => 90,
'fit' => 'crop'
]
]
],
'taxon' => [
'variants' => [
'thumbnail' => [
'width' => 320,
'height' => 180,
'fit' => 'crop'
],
'banner' => [
'width' => 1248,
'height' => 702,
'fit' => 'crop'
]
]
]
]
]
//...
];
The loading of these conversions is happening with the help of the LoadsMediaConversionsFromConfig
trait that you can also add to your models. The "key" within the config is derived from the snake
case classname of the given model, eg.:
- Classname:
Product
, config key isvanilo.framework.image.product.variants
, - Classname:
Subscription
config key isvanilo.framework.image.subscription.variants
, - Classname:
EventRegistration
config key isvanilo.framework.image.event_registration.variants
,
If you don't need type specific conversions, you can define "generic" conversions under the
vanilo.framework.image.variants
key. These settings are used as a fallback if there's no type
specific definition in the configuration.
Retrieving Images
Thumbnails
Having thumbnails is a highly common scenario, therefore Vanilo plays smartass here, and supports them by default. This is basically a syntactic sugar, that retrieves the image variant named "thumbnail".
// Retrieves a single URL of the primary thumbnail image:
$product->getThumbnailUrl(); // 250x250
$taxon->getThumbnailUrl(); // 320x180
// The above calls are equivalent to:
$product->getImageUrl('thumbnail');
$taxon->getImageUrl('thumbnail');
Primary Images
Another common use case is that one specific image is marked as the primary image, dedicated to be used to display on listing pages, etc.
In the built-in Vanilo Admin this can be achieved by using the "Set as Primary Image" button:
Primary image is achieved by setting the isPrimary
custom property
on the given image.
To set an image as primary from the code, use the setCustomProperty()
method:
$mediaItem->setCustomProperty('isPrimary', true);
Mind removing the
isPrimary
property from other images assigned to the same model if you're doing this manually
Retrieve Image Variants
To retrieve image variants in client code:
// Returns the product's primary image URL in the size defined by the `cart` conversion:
$product->getImageUrl('cart'); // 120x90
// Returns the taxon's primary image URL in the size defined by the `banner` conversion:
$taxon->getImageUrl('banner'); // 1248x702
Retrieve Multiple Images
It is possible to retrieve a collection of all the images assigned to a specific model:
// All the thumbnails of the product:
$product->getThumbnailUrls();
// All the banners of the taxon:
$taxon->getImageUrls('banner');