beryllium / icelus
Thumbnail generator for Sculpin-based websites
Requires
- php: ^7.4||^8.0
- imanee/imanee: ^1.2
- symfony/filesystem: ^5.4
Requires (Dev)
- mikey179/vfsstream: ^1.6
- phpunit/phpunit: ^9.4
- symfony/config: ^5.4
- symfony/dependency-injection: ^5.4
- symfony/http-kernel: ^5.4
- twig/twig: ^2.5||^3.0
This package is auto-updated.
Last update: 2024-11-07 08:01:38 UTC
README
Icelus is a quick and easy thumbnail generator for your Sculpin-based websites and blogs.
Icelus, otherwise known as "Scaled Sculpin", are a genus of small fish mainly found in the North Pacific.
Requirements
Icelus requires:
- PHP 5.4+
- Imagick extension (installable via apt-get, pecl, or yum)
- Imanee library (imanee.io - fetched automatically by Composer)
Installation
If you are using the Phar-based Sculpin utility, you can create or modify a sculpin.json file in your project root and add "beryllium/icelus"
to the "require"
block. Then, run sculpin install
or sculpin update
to fetch the required dependencies.
{
"require": {
"beryllium/icelus": "*"
}
}
Alternatively, if you are using a Composer-based sculpin installation, you should simply be able to run composer require beryllium/icelus
to get things rolling.
Once the library is installed, you have to tell Sculpin how to load it. You can do this by creating or modifying a app/SculpinKernel.php
file to resemble the following:
<?php
class SculpinKernel extends \Sculpin\Bundle\SculpinBundle\HttpKernel\AbstractKernel
{
protected function getAdditionalSculpinBundles()
{
return array(
'Beryllium\Icelus\IcelusBundle',
);
}
}
Note: The class name should be a string, not an object instantiation. (This differs from the way Symfony 2 configures bundles.)
Configuration
Generally, no additional configuration is required. If you want to rename
the output subfolder for thumbnails (default is 'yourblog.com/_thumbs'),
add this to your sculpin_kernel.yml
icelus: prefix: '/_thumbs'
icelus.prefix
: A subdirectory under the Sculpin output directory to store the thumbnails. Default is'/_thumbs'
.
Usage
Icelus exposes a thumbnail
function in Twig, which you can use either on its own or by creating Twig macros to customize the output.
thumbnail(image, width, height, crop)
- image (string): The relative path to the image in the
source/
folder. - width (int): Maximum width, in pixels
- height (int): Maximum height, in pixels
- crop (bool): False will fit the whole image inside the provided dimensions. True will crop the image from the center. Default: FALSE
Inline Example:
<a href="image.jpg"><img src="{{ thumbnail('image.jpg', 100, 100) }}"></a>
Macro Example:
index.html:
{% import '_macros.html.twig' as m %}
<h1>Gone Fishin'!</h1>
{{ m.small_thumbnail('image.jpg', 'A picture from my fishing trip') }}
_macros.html.twig:
{% macro small_thumbnail(image, caption) %}
<a href="{{ image }}">
<img src="{{ thumbnail(image, 100, 100) }}">
<br>
<em>{{ caption }}</em>
</a>
{% endmacro %}
A service called icelus.service
is also added to the Sculpin dependency injection container, which you can use in your own Sculpin extensions.
For raw access to the underlying Imanee library, the service is named icelus.imanee
. If you need to go deeper, you can then retrieve an Imagick instance using $imanee->getIMResource()
.
Technically speaking, this extension could also be used as a Symfony 2 bundle. This has not been tested, but experimentation is welcome.
Future Plans
I would like for Icelus to expose more features of the underlying Imanee library, particularly with regard to watermarks and drawing text onto images. Imanee's support for animated gifs could possibly also be advantageous in some way.
I would also like for Icelus to be compatible with a wide variety of PHP frameworks and workflows. I've concentrated on having it as a Twig extension, but it could also work with other template systems and even Markdown-style parsers.
Thanks
Special thanks to Beau Simensen, for inviting me into the Sculpin organization, and to Erika Heidi for the ease-of-use of the Imanee library.