Thumbnail generator for Sculpin-based websites and blogs
PHP
Switch branches/tags
Nothing to show
Clone or download
beryllium Merge branch 'configurable-prefix-updates'
* configurable-prefix-updates:
  Update tests for new ImageService constructor signature
  Use a constant to define the default thumbs location.
Latest commit 487987f May 20, 2017
Permalink
Failed to load latest commit information.
DependencyInjection Use a constant to define the default thumbs location. May 20, 2017
Resources/config read prefix argument from sculpin_kernel.yml May 20, 2017
tests
.gitignore
.travis.yml Update .travis.yml Jan 9, 2016
CONTRIBUTING.md changed url Dec 16, 2015
IcelusBundle.php
ImageService.php
LICENSE
README.md Use a constant to define the default thumbs location. May 20, 2017
TwigImageExtension.php Applying Insights Recommendations Mar 6, 2015
composer.json
phpunit.xml.dist

README.md

Icelus

Build Status SensioLabsInsight

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.