StyleCollection

Utility class used to store a list of CSS styles, with an easy-to-use chainable interface. Supports both inline styles and generating styles for style sheets.

Quick start

use AppUtils;

StyleCollection::create()
    ->style('display', 'block')
    ->style('width', '100%')
    ->display();

Output:

display:block;width:100%

Advanced usage

General rules

• Style sorting: By default, styles are sorted alphabetically by name. This can be turned off in the options, see Setting options.
• Stripping empty values: Styles with an empty value are ignored. Considered empty are empty strings, as well as NULL.
• Replacing styles: Setting an existing style again will overwrite any existing value. The only exception is setting an existing style to an empty value, which does not remove the existing value. Use removeStyle() for this.

Removing styles

use AppUtils;

$collection = StyleCollection::create()
   ->style('display', 'block');

$collection->remove('display');

Removing a style that has not been added has no effect.

Parsing existing style strings

use AppUtils;

StyleCollection::create()
    ->parseStylesString('width:500px;line-height:12px')
    ->style('height', '200px')
    ->display();

Output:

height:200px;line-height:12px;width:500px;

Working with NumberInfo

Style values can be added using an existing NumberInfo instance, or by parsing a numeric value.

use AppUtils;

$width = parseNumber('500px');

StyleCollection::create()
    ->styleNumber('width', $width)
    ->styleParseNumber('line-height', 12)
    ->display()

Output:

width:500px;line-height:12px

Automatic value type handling

The default method style() only accepts string values. The styleAuto() method accepts a wider range of values:

• string
• int
• float
• NumberInfo instance
• Object that implements Interface_Stringable
• NULL

This makes it an easy catch-all, with the guarantee that the style will be ignored if the resulting value is an empty string.

StyleCollection::create()
    ->style('string', 'foo')
    ->style('int', 500)
    ->style('float', 25.6))
    ->style('stringable', sb()->add('test')) // implements the Stringable interface
    ->style('null', null)
    ->display;

Output:

float:25.6;int:500;string:foo;stringable:test

Note: null does not appear in the list, as it is an empty value.

!important flags

If a style value has an !important flag, it will be preserved. The flag can also be added using the third parameter of the style methods, to allow the use of non-string values:

use AppUtils;

StyleCollection::create()
    ->style('display', 'block !important')
    ->styleNumber('font-size', parseNumber('1.1em'), true)
    ->display();

Output:

display:block !important;font-size:1.1em !important

Note: If a value already contains an !important flag, setting the important parameter to true will not cause the flag to be duplicated.

Creating from an existing array

The styles will be added using the styleAuto() method, allowing for complex value types.

use AppUtils;

$styles = array(
    'display' => 'block',
    'width' => '500px',
    'height' => parseNumber('50%')
);

StyleCollection::create($styles)
    ->display();

Output:

display:block;height:50%;width:500px

Note: This is the same as using the setStyles() method, which can be used after the collection has been created.

Merging collections

Modify an existing collection

use AppUtils;

$fontStyles = StyleCollection::create()
    ->style('font-family', 'Arial')
    ->style('font-size', '1.1em');

$sizeStyles = StyleCollection::create()
    ->style('width', '50%')
    ->style('height', '50%');

// Copy all size styles into the font collection
$fontStyles->mergeWith($sizeStyles);

Merge collections into a new one

This variant does not modify any of the collections, but creates a new one that contains all styles.

use AppUtils;

$fontStyles = StyleCollection::create()
    ->style('font-family', 'Arial')
    ->style('font-size', '1.1em');

$sizeStyles = StyleCollection::create()
    ->style('width', '50%')
    ->style('height', '50%');

// Accepts an arbitrary amount of collections
$newCollection = StyleCollection::merge(
    $fontStyles, 
    $sizeStyles
);

Note: The order of the collections is important. Existing styles are overwritten by each collection in the order they are specified.

Switching to style sheet mode

In style sheet mode, the styles are rendered for usage in CSS selectors, with indentation and formatting tweaks to follow the main standard.

use AppUtils;

StyleCollection::create()
    ->style('display', 'block')
    ->style('width', '500px')
    ->configureForStylesheet()
    ->display();

Output:

    display: block;
    width: 500px;

Setting options

A number of options can be set to customize how the styles are rendered, as well as the behavior of some aspects of the collections.

The options live in a dedicated options instance, which can be fetched with getOptions().

use AppUtils;

$collection = StyleCollection::create();

$options = $collection->getOptions();

Sorting

By default, styles are sorted by key. This can be turned off:

$options->enableSorting(false);

Indentation

$options->setIndentLevel(1);
$options->setIndentChar('  '); // 2 spaces

Setting an indent level above 0 automatically enables newlines as well, since the option makes no sense otherwise.

Spaces before values

By default, values are added directly after the hyphen, e.g. display:block. A space can be enabled, so this changes to display: block.

$options->enableSpaceBeforeValue();

Trailing semicolon

By default, no semicolon is added after the last style. e.g. display:block. This enables it, so it becomes display:block;.

$options->enableTrailingSemicolon();

Newlines

By default, styles are rendered in inline mode, in a single line. Newlines can be enabled like this:

$options->enableNewline();