README

Spruct gives you a clean PHP struct implementation with optional strong typed fields.

Composer Installation

{
  "require": {
    "spruct/spruct": "~1.0"
  }
}

Through terminal: composer require spruct/spruct:~1.0 🎱

Usage

Declaring Structs

A new struct type can be created by extending the abstract \Spruct\Struct class:

/**
 * Struct representing a 2D point
 */
class D2Point extends \Spruct\Struct
{
    /** @struct.type boolean */
    protected $visible = false;

    /** @struct.type float */
    protected $x;

    /** @struct.type float */
    protected $y;
}

Fields are declared through protected properties and data types are specified through the @struct.type property annotation:

/**
 * @struct.type <type>
 */
  protected $field;

Valid Type Declarations:

Type	Tokens	Example
boolean	`bool`, `boolean`	`/** @struct.type boolean */`
integer	`integer`, `int`	`/** @struct.type integer */`
string	`string`, `str`	`/** @struct.type string */`
double	`double`, `float`	`/** @struct.type float */`
array	`array`	`/** @struct.type array */`
Class	full qualified class name	`/** @struct.type \Some\Existing\Class */`
regex	a valid regex expression	`/** @struct.type #^\w{3}\d+$# */`

Initializing Structs

Structs can be initialized with a key value array prototype, like this:

$point = new D2Point([
    'x' => 1.0,
    'y' => 2.0
]);

Manipulating Structs

Structs can be manipulated just like a common \stdClass instance:

$pointA = new D2Point();
$pointA->visible = false;
$pointA->x = 1.0;
$pointA->y = 1.5;

Struct exception messages are pretty self explanatory \Spruct\StructException:

$pointB = new D2Point();
$pointB->visible = 'y'; // ! Cannot use string(y) as type float in field D2Point->visible
$pointB->x = 1;         // ! Cannot use integer(1) as type float in field D2Point->x
$pointB->y = [];        // ! Cannot use array as type float in field D2Point->y

Required Fields

You can also declare fields that must not be null using @struct.requires class annotation:

/**
 * @struct.requires name, age, role
 */
class Employee extends \Spruct\Struct
{
    /** @struct.type string */
    protected $name;

    /** @struct.type string */
    protected $role;

    /** @struct.type integer */
    protected $age;

    /** @struct.type #^\d{8}$# */
    protected $code;
}

Required fields are validated during struct initialization. If required fields are missing, a \Spruct\StructException is thrown.

new Employee(['age' => 21]);  // ! Cannot initialize Employee with null ["name", "role"]

Contributing

Fork spruct\spruct and clone
Install composer dependencies $ composer install
Run unit tests with phpunit 4.2+
Modify code: correct bug, implement feature
Back to step 3

NOTICE: phpunit 4.2+ is required due to a feature introduced here

spruct / spruct

Maintainers

Details