selamiphp / entity

Framework agnostic entity library which uses JSON Schema standard (draft-07 and draft-06) written in PHP 7.2

Selami Entity

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 = '[e-mail]';
$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 = '[e-mail]';
$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();