Skip to content

Manifest

Jump to bottom Edit New page
comhon-project edited this page Jun 10, 2020 · 57 revisions

Table of Contents

  1. Manifest description
    1. Version
    2. Name
    3. Properties
      1. Basic property
      2. Id property
      3. Object property
      4. Foreign property
      5. Array property
      6. Aggregation property
      7. Auto increment property
    4. Restrictions
      1. Enumeration
      2. Interval
      3. Pattern
      4. Regular Expression
      5. Length
      6. Size
      7. Not null
      8. Not empty
      9. Required
      10. Model name
    5. Local property type
    6. Inheritance
    7. Abstract model
    8. Share id
    9. Associate a class object
    10. Main
    11. Serializable
  2. Namespace
  3. Autoloading
  4. Manifest Person example

Manifest description

A Manifest permit to describe a concept by listing its properties. Manifests can be defined in XML or JSON format. for each example we will illustrate XML and JSON format.
To explain what is a Manifest we will build a manifest that describe a person as example.

Version

You have to specify the manifest version to determine which parser will be used to parse the document. There is currently two allowed version 2.0 and 3.0. Only version 3.0 is documented.

<manifest version="3.0"/>
{
    "version": "3.0"
}

Name

You have to specify the manifest name. The name must be a fully qualified name, in other words it must contain namespace.
Namespaces and autoloading are explained in next chapters.

<manifest version="3.0" name="Test\Person"/>
{
    "version": "3.0",
    "name": "Test\\Person"
}

Warning! due to JSON format you have to put double slash (\\).

Properties

Properties are listed in properties node.

<manifest version="3.0" name="Test\Person">
    <properties>
        ...
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": []
}

Basic property

A property must ave at least name and __inheritance__ attributes. __inheritance__ value determine the type of property (a string, an object, an array...).
Available __inheritance__ values are :

  • Comhon\Manifest\Property\String for string properties
  • Comhon\Manifest\Property\Integer for integer properties
  • Comhon\Manifest\Property\Index for index properties (integer value supperior than 0)
  • Comhon\Manifest\Property\Float for float properties
  • Comhon\Manifest\Property\Percentage for percentage properties
  • Comhon\Manifest\Property\Boolean for boolean properties
  • Comhon\Manifest\Property\DateTime for date time properties
  • Comhon\Manifest\Property\Object for object properties (explained in next chapter)
  • Comhon\Manifest\Property\Array for array properties (explained in next chapter)
  • Comhon\Manifest\Property\Aggregation for specific array properties (explained in next chapter)
<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="firstName" __inheritance__="Comhon\Manifest\Property\String"/>
        <property name="birthDate" __inheritance__="Comhon\Manifest\Property\DateTime"/>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "firstName",
            "__inheritance__": "Comhon\\Manifest\\Property\\String"
        }
        {
            "name": "birthDate",
            "__inheritance__": "Comhon\\Manifest\\Property\\DateTime"
        }
    ]
}

Id property

We want an id to find easily a person, so we need to add an id property.
An id property is a part of a model id. Commonly models have only one id property but you can define several id properties.
To define a property as id property, you just have to add an attribute is_id (id must be a float, integer or string).

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="id" __inheritance__="Comhon\Manifest\Property\Integer" is_id="1"/>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "id",
            "__inheritance__": "Comhon\\Manifest\\Property\\Integer",
            "is_id": true
        }
    ]
}

Object property

An object property is a property that refer to an object defined in a manifest (or a local type).
For example, a person may have a home. And a home would be described by a manfiest named Test\House.

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="home" model="\Test\House" __inheritance__="Comhon\Manifest\Property\Object"/>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "home",
            "model": "\\Test\\House",
            "__inheritance__": "Comhon\\Manifest\\Property\\Object"
        }
    ]
}

model attribute is a value with relative or absolute namespace (explained in namespace chapter).

Foreign property

A Foreign property is an object property that contain the key is_foreign, it refers another Object that has an existence elsewhere. Like described before Person may have a property home, and this property is basically a foreign property because a house may exist without it's owner.
Often a foreign value is serialized in a different place, for example if we store Person and House in SQL database, they would be in different tables and Person table would only refer to a House id.

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="home" model="\Test\House" is_foreign="1" __inheritance__="Comhon\Manifest\Property\Object"/>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "home",
            "model": "\\Test\\House",
            "is_foreign": true,
            "__inheritance__": "Comhon\\Manifest\\Property\\Object"
        }
    ]
}

Array property

We want to have a property middleNames. actually a person can have a second name, third name... so we can define an array property to store these names.

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="middleNames" __inheritance__="Comhon\Manifest\Property\Array">
            <values name="middleName" __inheritance__="Comhon\Manifest\Value\String"/>
        </property>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "middleNames",
            "__inheritance__": "Comhon\\Manifest\\Property\\Array",
            "values": {
                "name": "middleName",
                "__inheritance__": "Comhon\\Manifest\\Value\\String"
            }
        }
    ]
}

The values node describe what array may contain. this node is like a property node but may be found only in arrays. each properties __inheritance__ are available for values except aggregation, but the namespace is different and must be Comhon\\Manifest\\Value.
The name attribute is the name of an element (basically it's the singular of property name).

By default, an array property describes an indexed array, but you can define an associative array by adding is_associative attribute.

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="middleNames" __inheritance__="Comhon\Manifest\Property\Array" is_associative="1">
            <values name="middleName" __inheritance__="Comhon\Manifest\Value\String"/>
        </property>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "middleNames",
            "__inheritance__": "Comhon\\Manifest\\Property\\Array",
            "is_associative": true,
            "values": {
                "name": "middleName",
                "__inheritance__": "Comhon\\Manifest\\Value\\String"
            }
        }
    ]
}

Aggregation property

Now instead having a unique home we want a person able to have several homes.

One way to do is to define an array property that contain foreign objects values.
The other way to do is to define an aggregation. An aggregation is usually used when two models are serialized (saved) in different "places". In our case, models Test\Person and Test\House would be serialized in different SQL tables, and table for model Test\House would have a column that reference the owner like owner_id.

In aggregation property the model used in values node must have a reference to "parent" model to know how to link models (for example model Test\House should have a property owner with model Test\Person). The link must be described in aggregation property under node aggregations (actually link might be defined on several properties, see children property in manifest example).

In aggregation property, the value is necessarily a foreign object, so no need to specify __inheritance__ and is_foreign.

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="homes" __inheritance__="Comhon\Manifest\Property\Aggregation">
            <values name="home" model="Test\House"/>
            <aggregations>
                <aggregation>owner</aggregation>
            </aggregations>
        </property>
    </properties>
</manifest>
<manifest version="3.0" name="Test\House">
    <properties>
        <property name="id" is_id="1" __inheritance__="Comhon\Manifest\Property\Integer"/>
        <property name="owner" model="\Test\Person" is_foreign="1" __inheritance__="Comhon\Manifest\Property\Object"/>
        ...
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "homes",
            "values": {
                "name": "home",
                "model": "Test\\House"
            },
            "aggregations": [
                "owner"
            ],
            "__inheritance__": "Comhon\\Manifest\\Property\\Aggregation"
        }
    ]
}
{
    "version": "3.0",
    "name": "Test\\House",
    "properties": [
        {
            "name": "id",
            "is_id": true,
            "__inheritance__": "Comhon\\Manifest\\Property\\Integer"
        }
        {
            "name": "owner",
            "model": "\\Test\\Person",
            "is_foreign": true,
            "__inheritance__": "Comhon\\Manifest\\Property\\Object"
        }
    ]
}

Auto increment property

An index property may be defined as auto incremental. It permit to a public client to know if a property is automatically set when creating resource. The auto incremental setting is only available for index property.
For example if we store Test\Person objects in SQL table, the id column could be defined as auto incremental.

<manifest version="3.0" name="Test\Person">
  <properties>
    <property name="id" is_id="1" auto="incremental" __inheritance__="Comhon\Manifest\Property\Index"/>
  </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "id",
            "is_id": true,
            "auto": "incremental",
            "__inheritance__": "Comhon\\Manifest\\Property\\Index"
        }
    ]
}

Restrictions

Some restrictions may be applied on properties or values in array. A restriction is a rule that a value must satisfy. if an array has restrictions on its values, each value must satisfy restrictions. Properties and values in array may have several restrictions.
For each restriction we will indicate on which value it may be defined and we will explain what the value must satisfy.

Enumeration

string integer float

We want to have a property gender and this property can have only 2 values : male or female. So we must define an enumeration.

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="gender" __inheritance__="Comhon\Manifest\Property\String">
            <enum>
                <value>male</value>
                <value>female</value>
            </enum>
        </property>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "gender",
            "__inheritance__": "Comhon\\Manifest\\Property\\String",
            "enum": [
                "male",
                "female"
            ]
        }
    ]
}

Interval

integer float dateTime

We want to have a property age so type might be integer but there is only a reasonable range of possible values. Actually a person can't be 300 years old or -20 (negative). So we must add an interval of allowed values.
To define an interval, we use mathematic notation :

  • [a,b] means a <= value <= b
  • ]a,b[ means a < value < b
  • [a,b[ means a <= value < b
  • ]a,b] means a < value <= b
  • ]a,] means value > a
  • [,a] means value <= a 
<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="age" __inheritance__="Comhon\Manifest\Property\Integer" interval="[0,130]"/>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "age",
            "__inheritance__": "Comhon\\Manifest\\Property\\Integer",
            "interval": "[0,130]"
        }
    ]
}

Pattern

string

Earlier we have defined properties firstName and middleNames with type string. But a name can only contain alphabetic characters and possibly a - (we suppose we use only latin script), so to restrict values we can define a pattern that will refer to a regular expression.

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="firstName" __inheritance__="Comhon\Manifest\Property\String" pattern="name"/>
        <property name="middleNames" __inheritance__="Comhon\Manifest\Property\Array">
            <values name="middleName" pattern="name" __inheritance__="Comhon\Manifest\Value\String"/>
        </property>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "firstName",
            "__inheritance__": "Comhon\\Manifest\\Property\\String",
            "pattern": "name"
        },
        {
            "name": "middleNames",
            "__inheritance__": "Comhon\\Manifest\\Property\\Array",
            "values": {
                "name": "middleName",
                "__inheritance__": "Comhon\\Manifest\\Value\\String",
                "pattern": "name"
            }
        }
    ]
}

At this point we have specified the pattern but we don't have defined the regular expression.
All regular expressions that you want to define must be regrouped in a unique json file. So regular expressions file content should at least look like this :

{
    "name": "/^[a-zA-Z0-9_-]*$/"
}

The regular expression must be compatible for function preg_match.

You can register your regex file where you want on your system, you just have to reference it in config file (already seen in Configuration page).

Regular Expression

string

Regular expression is the same restriction than Pattern but instead of put a name that refer to a defined regular expression in json file, the regular expression is directly defined in manifest with regex attribute.

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="firstName" __inheritance__="Comhon\Manifest\Property\String" regex="/^[a-zA-Z0-9_-]*$/"/>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "firstName",
            "__inheritance__": "Comhon\\Manifest\\Property\\String",
            "regex": "/^[a-zA-Z0-9_-]*$/"
        }
    ]
}

The regular expression must be compatible for function preg_match.

Length

string

We can define a range for string length by adding restriction length. Length follow same syntax than interval. If you want an exact length, it may look like [x,x]

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="name" __inheritance__="Comhon\Manifest\Property\String" length="[2,20]"/>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "name",
            "__inheritance__": "Comhon\\Manifest\\Property\\String",
            "length": "[2,20]"
        }
    ]
}

Size

array

We can define a range for array size by adding restriction size. Size follow same syntax than interval. If you want an exact size, it may look like [x,x]

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="middleNames" __inheritance__="Comhon\Manifest\Property\Array" size="[0,3]">
            <values name="middleName" __inheritance__="Comhon\Manifest\Value\String" length="[2,20]"/>
        </property>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "middleNames",
            "__inheritance__": "Comhon\\Manifest\\Property\\Array",
            "values": {
                "name": "middleName",
                "__inheritance__": "Comhon\\Manifest\\Value\\String",
                "length": "[2,20]"
            },
            "size": "[0,3]"
        }
    ]
}

Not null

all

We can define properties and array values as not null by adding restriction not_null on property to prevent to set a null value.

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="firstName" __inheritance__="Comhon\Manifest\Property\String" not_null="1"/>
        <property name="middleNames" __inheritance__="Comhon\Manifest\Property\Array" not_null="1">
            <values name="middleName" __inheritance__="Comhon\Manifest\Value\String" not_null="1"/>
        </property>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "firstName",
            "__inheritance__": "Comhon\\Manifest\\Property\\String",
            "not_null": true
        },
        {
            "name": "middleNames",
            "__inheritance__": "Comhon\\Manifest\\Property\\Array",
            "values": {
                "name": "middleName",
                "__inheritance__": "Comhon\\Manifest\\Value\\String",
                "not_null": true
            },
            "not_null": true
        }
    ]
}

Not empty

string array

We can define properties and array values as not empty by adding restriction not_empty on :

  • string : to prevent to set an empty string ('').
  • array : to prevent to set an empty array ([]).
<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="firstName" __inheritance__="Comhon\Manifest\Property\String" not_empty="1"/>
        <property name="middleNames" __inheritance__="Comhon\Manifest\Property\Array" not_empty="1">
            <values name="middleName" __inheritance__="Comhon\Manifest\Value\String" not_empty="1"/>
        </property>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "firstName",
            "__inheritance__": "Comhon\\Manifest\\Property\\String",
            "not_empty": true
        },
        {
            "name": "middleNames",
            "__inheritance__": "Comhon\\Manifest\\Property\\Array",
            "values": {
                "name": "middleName",
                "__inheritance__": "Comhon\\Manifest\\Value\\String",
                "not_empty": true
            },
            "not_empty": true
        }
    ]
}

Required

all

We can define a property as required by adding restriction is_required. A required value has to be set. Even if a property is required, it can be set as null, so if you want a required not null value, you have to define is_required AND not_null restrictions.

<manifest version="3.0" name="Test\Person">
    <properties>
        <property name="firstName" __inheritance__="Comhon\Manifest\Property\String" is_required="1"/>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "properties": [
        {
            "name": "firstName",
            "__inheritance__": "Comhon\\Manifest\\Property\\String",
            "is_required": true
        }
    ]
}

Model name

string

We can define restriction is_model_name. This restriction may be defined if property value is a model name. model existence will be checked automatically.

<manifest>
    <properties>
        <property name="my_value" __inheritance__="Comhon\Manifest\Property\String" is_model_name="1"/>
    </properties>
</manifest>
{
    "properties": [
        {
            "name": "my_value",
            "__inheritance__": "Comhon\\Manifest\\Property\\String",
            "is_model_name": true
        }
    ]
}

Local property type

We want to add a property tattoos. A tattoo is not a simple thing, we must define a model to define it. But where define this model ? In Another Manifest file ? no because a tattoo exists only on Person body (on domestic animal too but to simply we ignore it). So we define a local property type inside Person manifest. By the way we could define another manifest file, but it's more efficient and more understandable to define a local property type in this case.

A local type follow exactly the same structure as a manifest except that it can't contain its local types

<manifest version="3.0" name="Test\Person">
    <types>
        <type name="Tattoo">
            <properties>
                <property name="type" __inheritance__="Comhon\Manifest\Property\String"/>
                <property name="location" __inheritance__="Comhon\Manifest\Property\String"/>
                <property name="tattooArtist" __inheritance__="Person" is_foreign="1"/>
            </properties>
	</type>
        <!-- a local property type can contain another one -->
        <type name="Example">
            <properties>
                <property name="tattoo" __inheritance__="Tattoo" />
                <property name="a_name" __inheritance__="Comhon\Manifest\Property\String"/>
            </properties>
        </type>
    </types>

    <properties>
        <property name="tattoos" __inheritance__="Comhon\Manifest\Property\Array">
            <values name="tattoo" __inheritance__="Tattoo"/>
        </property>
        <property name="example" __inheritance__="Example"/>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "types": [
        {
            "name": "Tattoo",
            "properties": [
                {
                    "name": "type",
                    "__inheritance__": "Comhon\\Manifest\\Property\\String"
                },
                {
                    "name": "location",
                    "__inheritance__": "Comhon\\Manifest\\Property\\String"
                },
                {
                    "name": "tattooArtist",
                    "__inheritance__": "Person",
                    "is_foreign": true
                }
            ]
        }
    ],
    "properties": [
        {
            "name": "tattoos",
            "__inheritance__": "Comhon\\Manifest\\Property\\Array",
            "values": {
                "name": "tattoo",
                "__inheritance__": "Tattoo"
            }
        }
    ]
}

As you can see in xml example, a local type can contain other local types.

Use local types if they are not too complex and if they are (almost) always used. Otherwise It's preferable to define other manifests that are loaded only if needed and it avoid to have too complex manifest.

Inheritance

A model can extends another one. Multiple inheritance is managed so model may extends several models. All properties of parent model(s) are added to inherited model. Inherited model can't redefine an existing property in parent model. Inheritance can be defined on manifests and on local types.

If you don't specify a parent model, your model will automatically extends from the "root" model Comhon\Root. It is a special model that doesn't have properties, it permit to have a unique parent model for all defined models.

Before we have defined a property gender with an enumeration, but another way to do is to define two new manifests Man and Woman that extends Person.

Woman manifest may look like :

<manifest version="3.0" name="Test\Person\Woman">
    <extends>
        <type>Person</type>
    </extends>
    <properties>
        <property name="pregnant" __inheritance__="Comhon\Manifest\Property\Boolean">
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person\\Woman",
    "extends": ["Person"],
    "properties": [
        {
            "name": "pregnant",
            "__inheritance__": "Comhon\\Manifest\\Property\\Boolean"
        }
    ]
}

Before we have defined a property tattoos but we can add a property piercings for example, and those two property are very similar so we can inherit models tattoo and piercing from bodyArt.

<manifest version="3.0" name="Test\Person">
    <types>
        <type name="BodyArt">
            <properties>
                <property name="type" __inheritance__="Comhon\Manifest\Property\String"/>
                <property name="location" __inheritance__="Comhon\Manifest\Property\String"/>
            </properties>
        </type>
        <type name="Tattoo">
            <extends>
                <type>BodyArt</type>
            </extends>
            <properties>
                <property name="tattooArtist" __inheritance__="Person" is_foreign="1"/>
            </properties>
        </type>
        <type name="Piercing">
            <extends>
                <type>BodyArt</type>
            </extends>
            <properties>
                <property name="piercer" __inheritance__="Person" is_foreign="1"/>
            </properties>
        </type>
    </types>
    <properties/>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "types": [
        {
            "name": "BodyArt",
            "properties": [
                {
                    "name": "type",
                    "__inheritance__": "Comhon\\Manifest\\Property\\String"
                },
                {
                    "name": "location",
                    "__inheritance__": "Comhon\\Manifest\\Property\\String"
                }
            ]
        },
        {
            "name": "Tattoo",
            "extends": ["BodyArt"],
            "properties": [
                {
                    "name": "tattooArtist",
                    "__inheritance__": "Person",
                    "is_foreign": true
                }
            ]
        },
        {
            "name": "Piercing",
            "extends": ["BodyArt"],
            "properties": [
                {
                    "name": "piercer",
                    "__inheritance__": "Person",
                    "is_foreign": true
                }
            ]
        }
    ],
    "properties": []
}

for multiple inheritance we just have to indicate several model names.

<manifest>
    <extends>
        <type>FirstParent</type>
        <type>SecondParent</type>
    </extends>
    <properties/>
</manifest>
{
    "extends": ["FirstParent","SecondParent"],
    "properties": []
}

Abstract model

You can define model as abstract. Objects with abstract model may be instanciated but can't be :

  • flagged as loaded
  • exported/serialized
  • imported/deserialized
<manifest version="3.0" name="Test\Person" is_abstract="1">
    <properties/>
</>
{
    "version": "3.0",
    "name": "Test\\Person",
    "is_abstract": true,
    "properties": []
}

Share id

Here we will just define how to set a share id. For more informations about what is share id, take a look at Share id chapter.

There are two way to define a share id :

  • With share_parent_id attribute. If model inherit from another one, it will share id with parent model. If a model inherit from several models (multiple inheritance), it will share id with the first parent model. Models may have same share id in cascade.

For example following manifest example will share it id with FirstParent model

<manifest share_parent_id="1">
    <extends>
        <type>FirstParent</type>
        <type>SecondParent</type>
    </extends>
    <properties/>
</manifest>
{
    "share_parent_id": true,
    "extends": ["FirstParent","SecondParent"],
    "properties": []
}
  • With shared_id attribute. You can define directly the model that will share id with current defined model. You can't specify any model, current model must inherit from specified model.
<manifest shared_id="GrandParent">
    <extends>
        <type>Parent</type>
    </extends>
    <properties/>
</manifest>
{
    "shared_id": "GrandParent",
    "extends": ["Parent"],
    "properties": []
}

Associate a class object

if you want to associate a class to your manifest you can define it in the attribute object. The class must contain namespace.

<manifest object="\Fully\Qualified\Name\Class">
    <properties/>
</manifest>
{
    "object": "\\Fully\\Qualified\\Name\\Class",
    "properties": []
}

Take a look at Getting started page to know how to define a class object and how to instanciate it.

Main

The is_main attribute permit to identify model as main model. Objects with main model may be stored in Main Object Collection.

<manifest is_main="1">
    <properties/>
</manifest>
{
    "is_main": true,
    "properties": []
}

Serializable

The is_serializable attribute permit to identify model as serializable model. Objects with serializable model may be serialized/deserialized (in sqlTable, JSON file, XML file...). A serializable model is automatically considered as main model.

<manifest is_serializable="1">
    <properties/>
</manifest>
{
    "is_serializable": true,
    "properties": []
}

Namespace

All models described with manifests and local types have an associated namespace. All namespace are prefixed by a name that correspond to a specific autoloading (we will see why in next chapter). For example all Comhon! models are prefixed by Comhon\. Here are some examples :

  • the Fully qualified name of model Config is Comhon\Config
  • the Fully qualified name of model SqlDatabase is Comhon\SqlDatabase

In a manifest you can refer to a model by using fully qualified name of a model or use name relative to current manifest namespace. A fully qualified name begin with a \ and relative name don't. Simple models doesn't have backslash and are not concerned by namespace (see list of simple models). Local types are concerned by namespace, they must be defined without namespace but you have to refer to them using fully qualified name or relative name.

For example we suppose that model Person namespace is prefixed by Test and it's fully qualified name is Test\Person. The fully qualified name of model Tattoo might be Test\Person\Tattoo and we could refer to it in manifest Person by using fully qualified name \Test\Person\Tattoo or relative name Tattoo.

<type name="Tattoo" extends="\Test\Person\BodyArt">
<!-- ... -->
</type>
<!-- ... -->
<property name="tattoo" __inheritance__="\Test\Person\Tattoo"/>

is equivalent to

<type name="Tattoo" extends="BodyArt">
<!-- ... -->
</type>
<!-- ... -->
<property name="tattoo" __inheritance__="Tattoo"/>

In php sources you have to always use fully qualified name and you have to omit first backslash :

$personModel = ModelManager::getInstance()->getInstanceModel('Test\Person');
$tattooModel = ModelManager::getInstance()->getInstanceModel('Test\Person\Tattoo');

$person = new ComhonObject('Test\Person');
$tattoo = new ComhonObject('Test\Person\Tattoo');

Autoloading

Comhon! use autoloading to find and load manifests (like PHP does to find classes). Actually manifests are loaded only if needed. To do so you have to define your autoloading in Configuration file.

Examples

We want to have two different directories to store our manifests. We may have a config file that look like :

{
  "autoload": {
    "manifest":{
      "Test":"../relative/path/to/manifests/test",
      "Tutorial":"/absolute/path/to/manifests/tutorial"
    }
  }
}
  • All manifest described in directory ../relative/path/to/manifests/test will have namespace prefixed by Test;
  • All manifest described in directory /absolute/path/to/manifests/tutorial will have namespace prefixed by Tutorial;

In file system each manifest must respect following rules :

  • manifest is contained in directory and the directory name must correspond to the model name
  • manifest file must be named manifest.json or manifest.xml (depends on manifest format defined in Configuration file)

Examples

  • We want to add a manifest to describe model Person in namespace Test, it must be saved at:
../relative/path/to/manifests/test/Person/manifest.json
or
../relative/path/to/manifests/test/Person/manifest.xml
  • We want to add a manifest to describe model Guitare in namespace Tutorial\Instrument, it must be saved at :
/absolute/path/to/manifests/tutorial/Instrument/Guitare/manifest.json
or
/absolute/path/to/manifests/tutorial/Instrument/Guitare/manifest.xml

Manifest Person example

<manifest version="3.0" object="\Comhon\Object\Person">
    <types>
        <type name="BodyArt">
            <properties>
                <property __inheritance__="Comhon\Manifest\Property\String" name="type"/>
                <property __inheritance__="Comhon\Manifest\Property\String" name="location"/>
            </properties>
        </type>
        <type name="Tattoo">
            <extends>
                <type>BodyArt</type>
            </extends>
            <properties>
                <property is_foreign="1" __inheritance__="\Test\Person" name="tattooArtist"/>
            </properties>
        </type>
        <type name="Piercing">
            <extends>
                <type>BodyArt</type>
            </extends>
            <properties>
                <property is_foreign="1" __inheritance__="\Test\Person" name="piercer"/>
            </properties>
        </type>
    </types>
    <properties>
        <property __inheritance__="Comhon\Manifest\Property\Integer" is_id="1" name="id"/>
        <property __inheritance__="Comhon\Manifest\Property\String" name="firstName"/>
        <property __inheritance__="Comhon\Manifest\Property\String" name="lastName"/>
        <property __inheritance__="Comhon\Manifest\Property\DateTime" name="birthDate"/>
        <property is_foreign="1" __inheritance__="\Test\Place" name="birthPlace"/>
        <property is_foreign="1" __inheritance__="\Test\Person" name="bestFriend"/>
        <property is_foreign="1" __inheritance__="\Test\Person\Man" name="father"/>
        <property is_foreign="1" __inheritance__="\Test\Person\Woman" name="mother"/>
        <property is_foreign="1" __inheritance__="Comhon\Manifest\Property\Array" name="children">
            <values __inheritance__="\Test\Person" name="child"/>
        </property>
        <property is_foreign="1" __inheritance__="Comhon\Manifest\Property\Array" name="homes">
            <values __inheritance__="\Test\Home" name="home"/>
        </property>
        <property __inheritance__="Comhon\Manifest\Property\Array" name="bodyArts">
            <values __inheritance__="BodyArt" name="bodyArt"/>
        </property>
    </properties>
</manifest>
{
    "version": "3.0",
    "name": "Test\\Person",
    "object": "\\Comhon\\Object\\Person",
    "types": [
        {
            "name": "BodyArt",
            "properties": [
                {
                    "name": "type",
                    "__inheritance__": "Comhon\\Manifest\\Property\\String"
                },
                {
                    "name": "location",
                    "__inheritance__": "Comhon\\Manifest\\Property\\String"
                }
            ]
        },
        {
            "name": "Tattoo",
            "extends": ["BodyArt"],
            "properties": [
                {
                    "name": "tattooArtist",
                    "__inheritance__": "\\Test\\Person",
                    "is_foreign": true
                }
            ]
        },
        {
            "name": "Piercing",
            "extends": ["BodyArt"],
            "properties": [
                {
                    "name": "piercer",
                    "__inheritance__": "\\Test\\Person",
                    "is_foreign": true
                }
            ]
        }
    ],
    "properties": [
        {
            "name": "id",
            "__inheritance__": "Comhon\\Manifest\\Property\\Integer",
            "is_id": true
        },
        {
            "name": "firstName",
            "__inheritance__": "Comhon\\Manifest\\Property\\String"
        },
        {
            "name": "lastName",
            "__inheritance__": "Comhon\\Manifest\\Property\\String"
        },
        {
            "name": "birthDate",
            "__inheritance__": "Comhon\\Manifest\\Property\\DateTime"
        },
        {
            "name": "birthPlace",
            "__inheritance__": "\\Test\\Place",
            "is_foreign": true
        },
        {
            "name": "bestFriend",
            "__inheritance__": "\\Test\\Person",
            "is_foreign": true
        },
        {
            "name": "father",
            "__inheritance__": "\\Test\\Person\\Man",
            "is_foreign": true
        },
        {
            "name": "mother",
            "__inheritance__": "\\Test\\Person\\Woman",
            "is_foreign": true
        },
        {
            "name": "children",
            "__inheritance__": "Comhon\\Manifest\\Property\\Array",
            "values": {
                "__inheritance__": "\\Test\\Person",
                "name": "child"
            },
            "is_foreign": true
        },
        {
            "name": "homes",
            "__inheritance__": "Comhon\\Manifest\\Property\\Array",
            "values": {
                "__inheritance__": "\\Test\\Home",
                "name": "home"
            },
            "is_foreign": true
        },
        {
            "name": "bodyArts",
            "__inheritance__": "Comhon\\Manifest\\Property\\Array",
            "values": {
                "__inheritance__": "BodyArt",
                "name": "bodyArt"
            }
        }
    ]
}
Add a custom footer
  1. Installation
  2. Configuration
  3. Getting started
  4. Manifest
  5. Serialization
  6. Options
  7. Object management
  8. Requester
  9. REST API
  10. Cache

Clone this wiki locally