spruct/spruct

Clean PHP struct implementation with optional strong typed fields

Spruct

, _(*1)

Spruct gives you a clean PHP struct implementation with optional strong typed fields., _(*2)

Composer Installation

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

Through terminal: composer require spruct/spruct:~1.0 :8ball:, _(*3)

Usage

Declaring Structs

A new struct type can be created by extending the abstract \Spruct\Struct class:, _(*4)

/**
 * 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:, _(*5)

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

Valid Type Declarations:

Initializing Structs

Structs can be initialized with a key value array prototype, like this:, _(*6)

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

Manipulating Structs

Structs can be manipulated just like a common \stdClass instance:, _(*7)

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

Struct exception messages are pretty self explanatory \Spruct\StructException:, _(*8)

$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:, _(*9)

/**
 * @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., _(*10)

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

Contributing

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

NOTICE: phpunit 4.2+ is required due to a feature introduced here, _(*11)

Copyright

Copyright (c) 2014 Márcio Almada. Distributed under the terms of an MIT-style license. See LICENSE for details., _(*12)