selami / entity
A library to assert variable types and values for a model defined using JSON Schema standard (draft-07 and draft-06).
Requires
- php: ^7.2
- ext-json: *
- opis/json-schema: ^1.0
- ramsey/uuid: ^3.8
Requires (Dev)
README
Framework agnostic entity/value object library to assert variable types and values for a model defined using JSON Schema standard (draft-07 and draft-06) written in PHP 7.2
Motivation
This library is a kind of helper library to generate your own Entity or Value Object models using JSON Schema. It is not expected to use classes in this library directly (See Examples for intended usage section below). To understand differences between Entities and Value Objects read Philip Brown's post on culttt.com
Installation
composer require selami/entity
Value Objects (See the explanation)
- Objects created using ValueObject are Immutable. This means only data injecting point is its constructor.
- It validates data on object creation
- If validation fails it throws InvalidArgumentException.
- Always use ValueObjectBuilder to create a ValueObject instance.
Convention when using ValueObjectBuilder
- Uppercase first character of property name.
- Then add "with" prefix to property name.
i.e. Say our property name is creditCardNumber, then setter method name for this property is withCreditCardNumber.
Usage
Say you have a JSON Schema file at ./models/credit-card.json. See the Credit Card Value Object Schema.
<?php declare(strict_types=1); use Selami\Entity\ValueObjectBuilder; $creditCard = ValueObjectBuilder::createFromJsonFile( './models/credit-card.json' ) ->withCardNumber('5555555555555555') ->withCardHolderName('Kedibey Mırmır') ->withExpireDateMonth(8) ->withExpireDateYear(24) ->withCvvNumber('937') ->build(); echo $creditCard->cardHolderName;
Entities
- Entities require id property.
- Entities are mutable.
- Entities are not automatically validated on object creation.
- When validation failed it throws InvalidArgumentException.
- It is possible to partially validate Entities.
- It can be used to form data validation, data validation before persisting it, etc...
Usage
Say you have a JSON Schema file at ./models/profile.json. See the Profile Entity Schema.
<?php declare(strict_types=1); use Selami\Entity\Entity; use stdClass; use Ramsey\Uuid\Uuid $id = Uuid::uuid4()->toString(); $entity = Entity::createFromJsonFile('./models/profile.json', $id); $entity->name = 'Kedibey'; $entity->age = 11; $entity->email = 'kedibey@world-of-wonderful-cats-yay.com'; $entity->website = 'world-of-wonderful-cats-yay.com'; $entity->location = new stdClass(); $entity->location->country = 'TR'; $entity->location->address = 'Kadıköy, İstanbul'; $entity->available_for_hire = true; $entity->interests = ['napping', 'eating', 'bird gazing']; $entity->skills = []; $entity->skills[0] = new stdClass(); $entity->skills[0]->name = 'PHP'; $entity->skills[0]->value = 0; $entity->validate();
Partial Validation
<?php declare(strict_types=1); use Selami\Entity\Entity; use stdClass; use Ramsey\Uuid\Uuid $id = Uuid::uuid4()->toString(); $entity = Entity::createFromJsonFile('./models/profile.json', $id); $entity->name = 'Kedibey'; $entity->age = 11; $entity->email = 'kedibey@world-of-wonderful-cats-yay.com'; $entity->website = 'world-of-wonderful-cats-yay.com'; $partiallyValidateFields = ['name', 'age', 'email', 'website']; $entity->validatePartially(partiallyValidateFields);
Examples for intended usage
Value Object Example
<?php declare(strict_types=1); namespace MyLibrary\ValueObject; use Selami\Entity\ValueObjectBuilder; final class CreditCard { private static $schemaFile = './models/credit-card.json'; public static function create() : ValueObjectBuilder { return ValueObjectBuilder::createFromJsonFile(self::$schemaFile); } }
<?php declare(strict_types=1); require 'vendor/autoload.php'; use MyLibrary\ValueObject\CreditCard; $valueObject = CreditCard::create() ->withCardNumber('5555555555555555') ->withCardHolderName('Kedibey Mırmır') ->withExpireDateMonth(8) ->withExpireDateYear(24) ->withCvvNumber('937') ->build(); // Prints "Kedibey Mırmır" var_dump($valueObject->cardHolderName);
Entity Example
<?php declare(strict_types=1); namespace MyLibrary\Entity; use Selami\Entity\Interfaces\EntityInterface; use stdClass; use Selami\Entity\Model; use Selami\Entity\EntityTrait; final class Profile implements EntityInterface { private static $schemaFile = './models/profile.json'; use EntityTrait; public static function create(string $id, ?stdClass $data=null) : EntityInterface { $model = Model::createFromJsonFile(self::$schemaFile); return new static($model, $id, $data); } }
<?php declare(strict_types=1); require 'vendor/autoload.php'; use Ramsey\Uuid\Uuid; $id = Uuid::uuid4()->toString(); $entity = Profile::create($id); $entity->name = 'Kedibey'; // Prints "Kedibey" var_dump($entity->name); // Throws "Selami\Entity\Exception\InvalidArgumentException" $entity->validate();