czim / laravel-dataobject
Basic validatable standardized data object.
Installs: 113 672
Dependents: 8
Suggesters: 0
Security: 0
Stars: 10
Watchers: 2
Forks: 0
Open Issues: 0
Requires
- php: ^8.0
Requires (Dev)
- ext-json: *
- orchestra/testbench: ^6.0
- phpunit/phpunit: ^9.0
README
Basic framework for making standardized but flexible data objects. This provides a class (and interfaces) to use to standardize your dependencies or return values with a generic dataobject.
All this really is, is a data storage class with magic getters and setters. It is Arrayable, Jsonable and validatable.
Also provided are the means to make nested validation possible for data objects (containing futher data objects).
Version Compatibility
Install
Via Composer
$ composer require czim/laravel-dataobject
Usage
Simply create your own extension of the base dataobject, and:
Optionally add your own getters and setters
Basic stuff of course, but if you want your IDE to know what your objects contain, you can simply write getters and setters like this:
class TestDataObject extends \Czim\DataObject\AbstractDataObject { public function getName($value) { $this->getAttribute('name'); } public function setName($value) { $this->setAttribute('name', $value); } }
Additionally, if you want to block any type of magic assignment (meaning all assignment would have to be done through the setAttribute()
or setAttributes()
methods, or your own setters), you can disable magic assignment as follows:
class TestDataObject extends \Czim\DataObject\AbstractDataObject { protected $magicAssignment = false; ...
Attempts to set attributes on the DataObject by magic or array access will then throw an UnassignableAttributeException
.
Optionally add validation rules for attributes
class YourDataObject extends \Czim\DataObject\AbstractDataObject { protected $rules = [ 'name' => 'required|string', 'list' => 'array|min:1', ]; }
Validating the data can be done as follows:
$dataObject = new YourDataObject(); // validate() returns a boolean, false if it does not follow the rules if ( ! $dataObject->validate()) { $messages = $dataObject->messages(); // messages() returns a standard Laravel MessageBag dd( $messages->first() ); }
Messages are a MessageBag
object generated by the Validator (whatever is behind the Laravel Facade Validator
).
Validation
To use the extra Validation features for nested DataObject validation rules and better array validation, load the ServiceProvider for this package. This is the only reason to load the ServiceProvider; this package does not itself require the Provider to function.
Add this line of code to the providers array located in your config/app.php
file:
Czim\DataObject\DataObjectServiceProvider::class,
Note that this will rebind the Validator
facade, so if you have done this yourself, you may instead want to use the provided validation Traits to add to your own extended validator class.
Read more information about the validation (traits) here.
Castable Data Object
You may opt to extend the Czim\DataObject\CastableDataObject
.
Besides the standard features, this also includes the possibility of casting its properties to scalar values or (nested) data objects. This works similarly to Eloquent's $casts
property (with some minor differences).
By overriding a protected casts()
method, it is possible to set a cast type per attribute key:
<?php protected function casts() { return [ 'check' => 'boolean', 'count' => 'integer', 'price' => 'float', ]; }
This has the effect of casting each property to its set type before returning it.
<?php $object = new YourDataObject([ 'check' => 'truthy value', 'price' => 45, ]); $object->check; // true $object['price']; // 45.0 $object->count; // 0 (instead of null)
toArray Casting
Cast types are also applied for the toArray()
method of the data object.
This means that unset properties will be present in the array as their default value (false
for boolean, 0.0
for float, etc.).
To disable this behaviour, set $castToArray
to false
.
This will entirely disable casting values on toArray()
.
Nested Object Casting
More useful than scalar-casting, is object casting. This will allow you to create a tree of nested objects that, if set, can be invoked fluently.
Given casts that are set as follows:
<?php class RootDataObject extends \Czim\DataObject\CastableDataObject { protected function casts() { return [ 'some_object' => YourDataObject::class, 'object_list' => YourDataObject::class . '[]', ]; } }
And with the following data example, you can access the data by property:
<?php $data = [ 'some_object' => [ 'type' => 'peaches', ], 'object_list' => [ ['type' => 'cucumbers'], ['type' => 'sherry'], ], ]; $object = new RootDataobject($data); $object->some_object; // instance of YourDataObject $object->some_object->type; // peaches $object->object_list[1]->type; // sherry
Note that unset or null
values will return null
, not an empty data object. Non-array values will cause exceptions to be thrown on being interpreted as data objects.
This behaviour can be changed by setting the $castUnsetObjects
property to true
: unset attributes with an object cast will then be cast as an empty instance of that object class.
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.