Overview

Contents:

Installation

Phar file (coming soon)

Coming soon.

Composer

Add the following entry to your composer.json:

{ "require": { "pminnieur/sprites": "dev-master" }}

Checkout detailed package information on Packagist.

Clone from GitHub

Clone Sprites git repository:

git clone git://github.com/pminnieur/sprites.git

Download composer.phar file and install dependencies:

wget -nc http://getcomposer.org/composer.phar
php composer.phar install

Run sprites executable from bin directory:

php bin/sprites

Configuration

A simple configuration of a Sprites\ProcessorInterface requires a Sprites\Configuration instance

<?php

use Sprites\Configuration;
use Sprites\Processor\DynamicProcessor;
use Imagine\Gd\Imagine;
use Imagine\Image\Color;

$imagine = new Imagine();

$config = new Configuration();
$config->setImagine($imagine);
$config->setColor(new Color('fff', 100));
$config->setImage('web/images/icons.png');
$config->setStylesheet('web/css/icons.css');
$config->getFinder()->name('*.png')->in('web/images/icons');
$config->setSelector(".icon.{{filename}}{background-position:{{pointer}}px 0px}\n");

$processor = new DynamicProcessor();
$processor->process($config);

// ...

Configuration Options

The following sections describe all the configuration options available on a Sprites\Configuration instance.

Imagine (*REQUIRED*)

<?php
$config->setImagine($imagine);
$config->getImagine();

The Imagine\ImagineInterface instance to use.

Finder (*REQUIRED*)

<?php
$config->setFinder($finder);
$config->getFinder();

The Symfony\Component\Finder\Finder instance used to find files for your sprites.

Note

To unleash the full power of this component, read the Finder documentation.

Image (*REQUIRED*)

<?php
$config->setImage($path);
$config->getImage();

The path to the target image sprite.

Note

If the directory does not exist yet, it will automatically be created.

Color (*OPTIONAL*)

<?php
$config->setColor($color);
$config->getColor();

The Imagine\Image\Color instance to use as background color.

Processor (*OPTIONAL*)

<?php
$config->setProcessor($processor);
$config->getProcessor();

The name of the Sprites\Processor\ProcessorInterface to use. This configuration value is only needed if you use the Sprites\Generator and may be guessed automatically, depending if you set a fixed width or not.

Note

Sprites already supports two different kind of processors:

  • dynamic: Sprites\Processor\DynamicProcessor
  • fixed: Sprites\Processor\FixedProcessor

Width (*OPTIONAL*)

<?php
$config->setWidth($width);
$config->getWidth();

A fixed width for each image in the sprite. This configuration value is only used in the Sprites\Processor\FixedProcessor and speeds up generating the image sprite.

Note

The Sprites\Processor\FixedProcessor could optionally resize your images if they exceed the fixed width.

Stylesheet (*REQUIRED*)

<?php
$config->setStylesheet($path);
$config->getStylesheet();

The path to the target stylesheet.

Note

If the directory does not exist yet, it will automatically be created.

Selector (*OPTIONAL*)

<?php
$config->setSelector($selector);
$config->getSelector();

A string parsed for each image, to be used as the CSS in the generated stylesheet.

Note

The default value of the selector is ".{{filename}}{background-position:{{pointer}}px 0px}\n".

Note

The string is parsed with Mustache and there are two available parameters:

  • ``pointer``: horizontal position of current pointer (in px)
  • ``filename``: an ASCIIfied version of the filename.

Usage

Processor

DynamicProcessor

The DynamicProcessor class is used to generate image sprites from images with a dynamic width and height.

<?php

use Sprites\Configuration;
use Sprites\Processor\DynamicProcessor;

$config = new Configuration();
// ... configure your configuration

$processor = new DynamicProcessor();
$processor->process($config);

FixedProcessor

The FixedProcessor class works similar to the DynamicProcessor. There are two main differences:

  • the getWidth() configuration value is used to determine the absolute width of the final image sprite, to spare recalculating the absolute width each time a new image is pasted into the sprite.
  • you can optionally enable resizing, resulting in images exceeding the fixed width to be scaled down with a correct aspect ratio to fit the fixed width.

Note

The height of the image sprite is still calculated dynamically, but ideally only once (e.g. if you use famfamfam icons which usually are dimensioned in 16px x 16px, the first image sets the sprites’ height to 16px and then the height must not be adjusted again).

<?php

use Sprites\Configuration;
use Sprites\Processor\FixedProcessor;

$config = new Configuration();
$config->setWidth(16); // fixed width of 16px per image
// ... configure your configuration

$processor = new FixedProcessor(array('resize' => true));
$processor->process($config);

Generator

The Sprites\Generator class is used for batch processing multiple Sprites\Configuration instances with their corresponding Sprites\Processor\ProcessorInterface instances.

<?php

use Sprites\Configuration;
use Sprites\Generator;
use Sprites\Processor\DynamicProcessor;
use Sprites\Processor\FixedProcessor;
// ... add your processor classes

$generator = new Generator();

$config = new Configuration();
// ... configure your configuration
$generator->addConfiguration($config);
// ... add your configurations

$dynamic = new DynamicProcessor();
$generator->addProcessor($dynamic);
$fixed = new FixedProcessor();
$generator->addProcessor($fixed);
// ... add your processors

$generator->generate();

Command Line Interface

The Sprites Console is a Command Line Interface tool for simplifying the usage and generation of image sprites without the need of you actually writing a single line of PHP code.

sprites generate:dynamic

The generate:dynamic command generates image sprites and CSS stylesheets with dynamic dimensions:

php sprites generate:dynamic --help

sprites generate:fixed

The generate:fixed command generates image sprites and CSS stylesheets with a fixed width dimension:

php sprites generate:fixed --help