Getting started

Table of content

1. How it works ?
2. Model
   1. Simple Model
   2. Complex Model
   3. Model Array
3. ModelManager
4. Comhon Object
   1. Unique Object
   2. Comhon Array
   3. Extends from Comhon Object
   4. Comhon DateTime Object
5. Code Example

How it works ?

Comhon! has two main concepts to understand : Comhon Object and Comhon Model.

• A Comhon Model (actually complex models) contain properties
  • A property has a name and a it own model
  • A property model can be (string, boolean, another complex model ...)
• A Comhon Object is attached to a model and contain values
  • Values is a map of values [a_property_name => a_value]

In other words map of values replace class attributes and model properties replace attributes types.

For example, a Model Person might have properties :

• first_name with model string,
• last_name with model string,
• age with model integer,
• ...

And a Comhon Object with model Person might have values

• first_name set to 'John',
• last_name set to 'Doe',
• age set to 21,
• ...

Important ! Normally, model names contain namespaces, but in this chapter we will omit namespaces to simplify explanations.

Model

Simple Model

list of simple model managed :

• boolean
• integer
• index
• float
• string
• dateTime
• percentage

Complex Model

A complex model is described by a manifest (please take a look at Manifest page). It contain a map of properties and each property has it own model

Model Array

ModelArray is a specific model that is attached to a ComhonArray. ModelArray is actually a container that contain it own Model that may be :

• a simple model
• a complex model
• another model array for multi dimensionnal arrays

For example in a model Person we might have a property homes that have a model array that contain a model House and each element should have the name home.

To instanciate a ModelArray you have to specify

• the contained model
• if array is an associative array
• the name of each array element

Others optional settings are available, they will be explained later.

$modelArray = new ModelArray($model, false, 'element_name'); for indexed comhon array
$modelArray = new ModelArray($model, true, 'element_name'); for associative comhon array

ModelManager

Instanciating models has a cost (due to manifest loading) so we need to instanciate them only one time. The singleton ModelManager manage all models instances so we don't have to know if model is already instanciated or not.

To get an instance of a model you just have to call getInstanceModel() :

$model = ModelManager::getInstance()->getInstanceModel('a_model_name');

Comhon Object

First, we have to describe how different object classes are organized

                            AbstractComhonObject (abstract)
                       __________|__________
                      |                     |
            UniqueObject (abstract)    ComhonArray (final)
            __________|__________
           |                     |
      ComhonObject (final)    ExtendableObject (abstract)

Unique Object

Like we said before, a ComhonObject contain a Model so when you instanciate a ComhonObject you have to specify an instance of Model or a model name.

$model = ModelManager::getInstance()->getInstanceModel('a_model_name');
$object = new ComhonObject($model);
// or
$object = new ComhonObject('a_model_name');

you can also use model and call function getObjectInstance().

$model = ModelManager::getInstance()->getInstanceModel('a_model_name');
$object = $model->getObjectInstance();
// return an instance of ComhonObject if no associated class
// return an instance of ExtendableObject otherwise

To verify if object has a value set you have to call function hasValue :

$object->hasValue('property_name'); // return boolean

To verify if object has a NOT NULL value set you have to call function issetValue :

$object->issetValue('property_name'); // return boolean

To access value you have to call function getValue :

$object->getValue('property_name'); // return null if object doesn't have specified value set

To set a value you have to call function setValue :

$object->setValue('property_name', a_value);

To unset a value you have to call function unsetValue (value is removed from values map) :

$object->unsetValue('property_name');

To get a new instance object of a complex property you can call function getInstanceValue :

$complexValue = $object->getInstanceValue('property_name'); // return instance of AbstractComhonObject

To initialize (instanciate and affect) a complex value you can call function initValue :

$complexValue = $object->initValue('property_name'); // return instance of AbstractComhonObject

Comhon Array

in Comhon! framework, arrays are not simple php arrays. Arrays are objects that contain a ModelArray. A ComhonArray is like a typed array and implements Iterator.
You have four ways to instanciate a ComhonArray yourself :

// 1. by specifying a ModelArray 
$model = ModelManager::getInstance()->getInstanceModel('a_model_name');
$modelArray = new ModelArray($model, false, 'element_name');
$comhonArray = new ComhonArray($modelArray);

// 2. by specifying a Model (the ModelArray is instanciated automaticaly)
$model = ModelManager::getInstance()->getInstanceModel('a_model_name');
$comhonArray = new ComhonArray($model);

// 3. by specifying a Model name (the ModelArray is instanciated automaticaly)
$comhonArray = new ComhonArray('a_model_name');

// 4. by using ModelArray
$comhonArray = $modelArray->getObjectInstance(); // $modelArray is an instanciated ModelArray

Comhon arrays may be multidimentionnal :

$modelArray = new ModelArray(
    new ModelArray('string', false, 'second_level'),
    false,  
    'first_level' 
);
$comhonArray = new ComhonArray($modelArray);

To access value you have to call getter

$comhonArray->getValue('a_key_or_index');

To set a value, you may call

$comhonArray->setValue('index_or_key', a_value); // set element in values at specified index/key
$comhonArray->pushValue(a_value); // Push one element onto the end of values
$comhonArray->unshiftValue(a_value); // Prepend one element to the beginning of values

To unset a value, you may call

$comhonArray->unsetValue('index_or_key'); // unset element in values at specified index/key
$comhonArray->popValue(); // Pop the element off the end of array and return it
$comhonArray->shiftValue(); // Shift an element off the beginning of array and return it

Extends from Comhon Object

if you want to associate a class to your object you can create one and define it in your manifest (see Manifest page). Your class must extends from ExtendableObject class and contain _getModelName method that return model name associated to your class.

use Comhon\Object\ExtendableObject;

class Person Extends ExtendableObject {

  protected function _getModelName() {
    return 'Person';
  }

  public function getName() {
    return $this->getValue('name');
  }
  
  public function setAge($age) {
    $this->setValue('age', $age);
  }
}

Now to get automatically an instance of Person you can use model and call function getObjectInstance().

$personModel = ModelManager::getInstance()->getInstanceModel('Person');
$person = $personModel->getObjectInstance(); // return an instance of Person if you have defined it in manifest

Comhon DateTime Object

ComhonDateTime is the Object linked to model dateTime. ComhonDateTime extends from DateTime.
For example if we have defined a property birth_date with type dateTime on model Person:

$dateTime = new ComhonDateTime('1976-03-20 07:14:33');
// set ComhonDateTime value
$person->setValue('birth_date', $dateTime);

Code Example

$person = new ComhonObject('Person');

// get Comhon object value
$age = $person->getValue('age');
// $age = null because 'age' is not set

// set Comhon object values
$person->setValue('age', 21);

// get Comhon object value
$age = $person->getValue('age');
// $age = 21


// initialize Comhon array value
$person->initValue('homes');

// set first home
$person->getValue('homes')->pushValue(
    new ComhonObject('House');
);