NumberInfo

The NumberInfo class is a handy tool to work with numeric values in HTML and CSS: it handles the most common units, and allows numeric operations like adding and subtracting values.

Usage

The easiest way is to use the parseNumber() function:

use function AppUtils\parseNumber;

$number = parseNumber('14px');

echo $number->getUnits();

This will output the following:

px

Working with instances

Existing NumberInfo instances can be passed to parseNumber(). By default, this will return the existing instance. If you wish to create a new instance instead, set the forceNew parameter:

use function AppUtils\parseNumber;

$number = parseNumber(5);

$sameInstance = parseNumber($number);
$newInstance = parseNumber($number, true);

Immutable instances

The NumberInfo_Immutable class guarantees that each instance is immutable, every method that changes the value returning a new immutable instance. This can make it easier to handle many mathematical operations.

Simply use the function parseNumberImmutable() instead of parseNumber().

use function AppUtils\parseNumberImmutable;

$number = parseNumberImmutable(5);

// $added is a new instance
$added = $number->add(1);

// $subtracted is a new instance yet again
$subtracted = $added->subtract(1);

The only case where parseNumberImmutable() will return the same instance is if the number instance being parsed is exactly the same.

Normalization

The parsing ignores all white space, and will convert numeric values with commas to valid numeric notation with dots.

The following numbers all give the same result:

parseNumber('15 px'); // 15px
parseNumber(' \t  15px \n   '); // 15px
parseNumber('1,5em'); // 1.5em

Getting number information

A number of methods are available to get information on the parsed number:

• isEven() Is it an even number?
• isNegative() Is it a negative number?
• isPositive() It it a positive number?
• isPercent() Is it a percentage?
• isPixels() Is it a pixel value?
• isEmpty() Is it empty or invalid?
• isZero() Does it equal 0?
• isZeroOrEmpty() Is it a zero, or empty/invalid?
• isUnitDecimal() Do the number's units allow decimals?
• isUnitInteger() Do the number's units only allow integers?
• hasDecimals() Does the number have decimals?
• hasUnits() Have units been specified?
• hasValue() Is a valid value present? (not zero or empty)

Numeric operations

Additions and subtractions work only of the units of the numbers are the same. No automatic conversions exist for adding pixels to percentages for example.

NOTE: Unitless numbers are assumed to be pixel values.

Operations between numbers of different units are silently ignored.

Additions

use function AppUtils\parseNumber;

$numberA = parseNumber('40px');
$numberB = parseNumber('10px');

$numberA->add($numberB);

echo $numberA->getNumber();

This will output the following result:

50

Conversions

A number can easily be converted to the notation to use either in an HTML or CSS context.

HTML attributes

In HTML attributes, only numbers or percentages are allowed. As a result, units are ignored if they are not a percentage. If the number has decimals, they are stripped.

use function AppUtils\parseNumber;

echo 'Percentage: '.parseNumber('500%')->toAttribute().PHP_EOL;
echo 'Pixel value: '.parseNumber('50px')->toAttribute().PHP_EOL;
echo 'Unitless number: '.parseNumber(44)->toAttribute().PHP_EOL;
echo 'Non HTML units: '.parseNumber('3.5em')->toAttribute();

This will show the following result:

Percentage: 500%
Pixel value: 50
Unitless number: 44
Non HTML units: 3

CSS

use function AppUtils\parseNumber;

echo 'EM Number: '.parseNumber('1.2em')->toCSS().PHP_EOL;
echo 'Percentage: '.parseNumber('50%')->toCSS().PHP_EOL;
echo 'Pixel value: '.parseNumber('120px')->toCSS().PHP_EOL;
echo 'Unitless number: '.parseNumber(120)->toCSS();

This will show the following output:

EM Number: 1.2em
Percentage: 50%
Pixel value: 120px
Unitless number: 120px