Laravel Value Objects
, (*1)
This package provides a set of handy value objects:, (*2)
- Duration
- Period
- Whitelist
Makeable is web- and mobile app agency located in Aarhus, Denmark., (*3)
Install
You can install this package via composer:, (*4)
``` bash
composer require makeabledk/php-value-objects, (*5)
## Usage
### Duration
Duration provides an easy way to interact with and manipulate durations of time.
#### Example usages
Create a duration and display formatted
```php
Duration::create(1,30)->toFormat(); // 01:30:00
You can also specify a custom format. Valid placeholders are: h,hh,m,mm,s,ss, (*6)
Duration::$format = 'h:mm';
Duration::create(1,30)->toFormat(); // 1:30
Perform simple add/subtract calculations, (*7)
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:, (*8)
$events = Events::all();
$eventsTotalDuration = Duration::sum($events, 'duration');
Easily export as an array, and re-instantiate if needed. Great for serving client API*., (*9)
$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., (*10)
Period
The Period object is great when you need to query data within a given period., (*11)
Example usages
Creating a period. Note that both start and end is optional., (*12)
$today = new Period(Carbon::today(), Carbon::tomorrow());
$future = new Period(Carbon::now());
$past = new Period(null, Carbon::now());
Manipulate on the fly, (*13)
$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*., (*14)
$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., (*15)
Whitelist
Whitelist is an abstract class that you can extend to specify a certain sets of whitelisted values., (*16)
It is great to quickly whip up a Status Object that ensures you are always working with a valid status., (*17)
Example usages
Creating an OrderStatus class, (*18)
class OrderStatus extends Whitelist
{
const VALUES = ['pending', 'accepted', 'cancelled'];
}
Now you would only be able to instantiate OrderStatus with a valid status:, (*19)
$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'., (*20)
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}') !, (*21)
Change log
Please see CHANGELOG for more information what has changed recently., (*22)
Testing
You can run the tests with:, (*23)
composer test
Contributing
We are happy to receive pull requests for additional functionality. Please see CONTRIBUTING for details., (*24)
Credits
License
Attribution-ShareAlike 4.0 International. Please see License File for more information., (*25)
Wallogit.com
