README

Icelus enables your Sculpin-based websites and blogs to generate space and bandwidth-saving thumbnails of images.

Icelus, otherwise known as "Scaled Sculpin", are a genus of small fish mainly found in the North Pacific.

Requirements

Icelus requires:

• PHP 8.5+
• PHP Composer
• Imagick or Gd extension (installable via apt-get, pecl, pie, homebrew, macports, or yum)

Installation

You can 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 the app/SculpinKernel.php file to resemble the following:

<?php

class SculpinKernel extends \Sculpin\Bundle\SculpinBundle\HttpKernel\AbstractKernel
{
    protected function getAdditionalSculpinBundles(): array
    {
        return array(
            \Beryllium\Icelus\IcelusBundle::class,
        );
    }
}

Note: The class name should be either the class constant (shown above) or a string, not an object instantiation.

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 app/config/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

Note: The crop setting currently only works with the Imagick loader, which has built-in support. Gd allows cropping and many other advanced operations, but implementing them is more challenging.

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.

Future Plans

I would like for Icelus to expose more features of the underlying image processing libraries, particularly with regard to watermarks and drawing text onto images.

Thanks

Special thanks to Beau Simensen, for inviting me into the Sculpin organization, and to Erika Heidi for the ease-of-use of the original Imanee library that worked for many years.