This package provides a set of handy value objects:
- Duration
- Period
- Whitelist
Makeable is web- and mobile app agency located in Aarhus, Denmark.
You can install this package via composer:
composer require makeabledk/php-value-objects
Duration provides an easy way to interact with and manipulate durations of time.
Create a duration and display formatted
Duration::create(1,30)->toFormat(); // 01:30:00
You can also specify a custom format. Valid placeholders are: h,hh,m,mm,s,ss
Duration::$format = 'h:mm';
Duration::create(1,30)->toFormat(); // 1:30
Perform simple add/subtract calculations
Duration::create(1,30)->add(Duration::create(1,30))->toFormat(); // 03:00:00
Duration::create(1,30)->subtract(Duration::create(0,20))->toFormat(); // 01:10:00
If you are using Laravel and have a Events@getDurationAttribute() accessor that converts to Duration::class, you can even do this:
$events = Events::all();
$eventsTotalDuration = Duration::sum($events, 'duration');
Easily export as an array, and re-instantiate if needed. Great for serving client API*.
$exported = Duration::create(1,30)->toArray(); // ['seconds' => 5400, 'minutes' => 90, 'hours' => 1.5, 'formatted' => '01:30:00']
$imported = Duration::fromArray($exported);
*Note it implements illuminate/support Arrayable contract, so it automatically casts to an array for eloquent models.
The Period object is great when you need to query data within a given period.
Creating a period. Note that both start and end is optional.
$today = new Period(Carbon::today(), Carbon::tomorrow());
$future = new Period(Carbon::now());
$past = new Period(null, Carbon::now());
Manipulate on the fly
$thisWeek = new Period(
Carbon::today()->previous(Carbon::MONDAY)
Carbon::today()->next(Carbon::SUNDAY)
);
$thisWeek->earliest(Carbon::today())->getStart(); // carbon of today
$thisWeek->latest(Carbon::tomorrow())->getEnd(); // carbon of tomorrow
Easily export as an array, and re-instantiate if needed. Great for serving client API*.
$exported = (new Period(Carbon::today(), Carbon::tomorrow()))->toArray(); // ['start' => '2017-06-27 00:00:00', 'end' => '2017-06-28 00:00:00']
$imported = Duration::fromArray($exported);
*Note it implements illuminate/support Arrayable contract, so it automatically casts to an array for eloquent models.
Whitelist is an abstract class that you can extend to specify a certain sets of whitelisted values.
It is great to quickly whip up a Status Object that ensures you are always working with a valid status.
Creating an OrderStatus class
class OrderStatus extends Whitelist
{
const VALUES = ['pending', 'accepted', 'cancelled'];
}
Now you would only be able to instantiate OrderStatus with a valid status:
$accepted = new OrderStatus('accepted');
$invalid = new OrderStatus('foobar'); // throws exception
You can customize the exception thrown. For instance you could swap it for the default Symfony/Laravel '422 UnprocessableEntityExceptions'.
OrderStatus::$exceptionClass = \Symfony\Component\HttpKernel\Exception\UnprocessableEntityHttpException::class;
Now you have error handling out of the box for forms and wildcard controller methods (ie. '/orders/{status}') !
Please see CHANGELOG for more information what has changed recently.
You can run the tests with:
composer test
We are happy to receive pull requests for additional functionality. Please see CONTRIBUTING for details.
Attribution-ShareAlike 4.0 International. Please see License File for more information.