zenstruck / dimension
Wrap quantity and unit of measure with conversions/humanizers.
Fund package maintenance!
kbond
Installs: 1 283
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 2
Forks: 2
Open Issues: 0
Requires
- php: >=8.0
Requires (Dev)
- phpstan/phpstan: ^1.4
- phpunit/phpunit: ^9.5.0
- symfony/phpunit-bridge: ^6.0
- symfony/var-dumper: ^5.4|^6.0
- twig/twig: ^2.0|^3.0
Suggests
- twig/twig: To use the provided Twig extension
README
Wrap quantity and unit of measure with conversions/humanizers.
Installation
composer require zenstruck/dimension
Usage
A dimension consists of a quantity (numeric
) and a unit of measure (string
).
Dimension Object
use Zenstruck\Dimension; // create $dimension = new Dimension(45.458, 'ft'); $dimension = Dimension::from('45.458ft'); // equivalent to above $dimension->quantity(); // 45.458 $dimension->unit(); // "ft" // render $dimension->toString(); // "45.46 ft" (max 2 decimal places) (string) $dimension; // equivalent to above $dimension->toArray(); // [45.458, "ft"] json_encode($dimension); // '[45.458, "ft"]' // use your own formatter vsprintf('%.4f%s', $dimension->toArray()); // "45.4580ft"
Conversions
A dimension object can be converted to alternate units. The following converters are available:
- Mass
- Length
- Temperature
- Duration (length of time)
- Information (bytes)
- Propose additional converters via issue/PR
Use the convertTo()
method to perform conversions:
use Zenstruck\Dimension; $dimension = Dimension::from('45ft'); $converted = $dimension->convertTo('m'); // Zenstruck\Dimension $converted->quantity(); // 13.716 $converted->unit(); // "m" $converted->toString(); // "13.71 m" $dimension->convertTo('g'); // throws ConversionNotPossible - cannot convert feet to grams
Comparisons
Several comparison methods are available:
use Zenstruck\Dimension; $dimension = Dimension::from('45ft'); $dimension->isEqualTo('6m'); // false $dimension->isLargerThan('6m'); // true $dimension->isLargerThanOrEqualTo('6m'); // true $dimension->isSmallerThan('6m'); // false $dimension->isSmallerThanOrEqualTo('6m'); // false $dimension->isWithin('6m', '1km'); // true $dimension->isOutside('6m', '1km'); // false
Mathematical Operations
use Zenstruck\Dimension; $dimension = Dimension::from('45ft'); $dimension->add('6m')->toString(); // "64.69 ft" $dimension->subtract('6m')->toString(); // "25.31 ft"
Information Object
Zenstruck\Dimension\Information
extends Zenstruck\Dimension
so it has the same API with
some additional features related to humanizing bytes.
use Zenstruck\Dimension\Information; $info = Information::from('4568897B'); $info = Information::from(4568897); // equivalent to above (can create from bytes directly) $info->bytes(); // 4568897 // "humanize" (string) $info->humanize(); // "4.57 MB" (defaults to the decimal system) (string) $info->asBinary()->humanize(); // "4.36 MiB" (convert to binary system before humanizing) (string) Information::binary(4568897)->humanize(); // "4.36 MiB" (explicitly create in binary system) // when creating with a unit of measure, the system is detected (string) Information::from('4570 kb')->humanize(); // "4.57 MB" (string) Information::from('4570 KiB')->humanize(); // "4.46 MiB"
Duration Object
Zenstruck\Dimension\Duration
extends Zenstruck\Dimension
so it has the same API with
the ability to humanize a duration.
use Zenstruck\Dimension\Duration; $duration = Duration::from('8540 s'); $duration = Duration::from(8540); // equivalent to above (can create from seconds directly) (string) $duration->humanize(); // "2 hrs" (string) Duration::from(0)->humanize(); // "0 secs" (string) Duration::from(1)->humanize(); // "1 sec" (string) Duration::from(10)->humanize(); // "10 secs" (string) Duration::from(65)->humanize(); // "1 min"
Bridge
Twig Extension
A Twig extension is provided with dimension
, information
, and duration
filters.
Manual Activation:
/* @var Twig\Environment $twig */ $twig->addExtension(new \Zenstruck\Dimension\Bridge\Twig\DimensionExtension());
Symfony full-stack activation:
# config/packages/zenstruck_dimension.yaml Zenstruck\Dimension\Bridge\Twig\DimensionExtension: ~ # If not using auto-configuration: Zenstruck\Dimension\Bridge\Twig\DimensionExtension: tag: twig.extension
Usage:
{{ '45.458ft'|dimension.convertTo('m') }} {# "13.71 m" #} {{ 4568897|information.humanize() }} {# "4.57 MB" #} {{ 8540|duration.humanize() }} {# "2 hrs" #}