Object management

Table of contents

1. [Object Collection] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Object-management#object-collection)
2. [Main Object Collection] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Object-management#main-object-collection)
3. [Object serialization] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Object-management#object-serialization)
4. [Object deserialization] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Object-management#object-deserialization)
5. [Object export] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Object-management#object-export)
6. [Foreign properties export] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Object-management#foreign-properties-export)
7. [Object import] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Object-management#object-import)
8. [Import via Object instance] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Object-management#import-via-object-instance)
9. [Import via Model instance] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Object-management#import-via-model-instance)
10. [Foreign properties import] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Object-management#foreign-properties-import)
11. [Date time management] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Object-management#date-time-management])

Object Collection

An Object Collection permit to store objects and find them in constant time. Objects are grouped by model and by id. Obviously an object without id property cannot be stored in Object Collection.

Example of an Object Collection structure :

[
    person : [
        an_id_one : person_object_one,
        an_id_two : person_object_two
    ],
    town : [
        an_id_one : town_object_one
    ],
    house : [
        an_id_one : house_object_one,
        an_id_two : house_object_two
    ]
]

Example of usage :

$lPersonOne; // consider object already exists, has a model Person and has an id 'one'

$objectCollection = new OjectCollection();
$objectCollection->addObject($lPersonOne);

$objectCollection->hasObject('one', 'Person');           // return true
$object = $objectCollection->getObject('one', 'Person'); // return object previously added

$objectCollection->hasObject('two', 'Person');           // return false
$object = $objectCollection->getObject('two', 'Person'); // return null

$objectCollection->hasObject('one', 'House');            // return false
$object = $objectCollection->getObject('one', 'House');  // return null

Main Object Collection

MainObjectCollection is a singleton that store all deserialized (loaded) and imported objects. This singleton is usefull to know which object already exists and avoid redundants deserializations.

$object = MainObjectCollection::getInstance()->getObject('an_id', 'a_model_name');

Object serialization

Whatever is your serialzation you just have to call one function save() to serialize your object. Obviously the model associated to your object must have a serialization.

$object->save();

Specific case for sql database

### Your table has an incremental id Like other serializations call save() function but there are two cases to identify :

1. if your Object doesn't have id set, an INSERT will be executed. if INSERT is successfull, id will be set in your object.
2. if Object has id set, an UPDATE will be executed

### Your table doesn't have an incremental id you must specify your operation (insert or update)

$object->save(SqlTable::INSERT);
$object->save(SqlTable::UPDATE);

# Object deserialization Whatever is your serialzation you just have to call one function loadObject() to serialize your object. Obviously the model associated to your object must have a serialization. When you load an object this object is stored in MainObjectCollection.

$object = $modelOne->loadObject('12');

// if your model has several id properties you must specify theme in a json encoded array 
// order of values must be the same as order of id properties in manifest
$object = $modelTwo->loadObject('[1,1501774389]');

Thanks to MainObjectCollection if an object has already been loaded it will not be loaded again (except if you force it).

// load object
$object = $modelOne->loadObject('12');

// return same instance object retrieve from MainObjectCollection
$object = $modelOne->loadObject('12');

// like previous instruction but force to call deserialization 
// and merge current object instance with serialized object
$object = $modelOne->loadObject('12', true);

# Object export You can export object to three formats :

• json (stdClass)
• XML (SimpleXMLElement)
• associative array which each value is a string (like format of an sql database SELECT request)

respectively call functions :

• toObject()
• toXml()
• toSqlDataBase()

$person = new Object('person');
$person->setValue('id', 1);
$person->setValue('firstName', 'alexander');

print json_encode($person->toOject());
// output '{"id":1,"firstName":"alexander"}'

You can specify if you want to export with properties serializations names or not.

print json_encode($person->toOject(true));
// output '{"id":1,"first_name":"alexander"}'

## Foreign properties export A value that correspond to a foreign property is an instance of Object. but only id is exported for a simple reason, value can be defined elsewhere and same value will be described several time, it can be ambiguous and dangerous.

$childOne; // consider that object has already been defined and as id '10'
$childTwo; // consider that object has already been defined and as id '11'
$modelArray = new ModelArray();
$objectArray = $modelArray->getObjectInstance();
$objectArray->pushValue($childOne);
$objectArray->pushValue($childTwo);

print json_encode($person->toOject());
// output '{"id":1,"firstName":"alexander","children":["10","11"]}'

By the way you can export foreign properties but values will be exported outside of current exported object.

$array = [];
// $array is passed by reference
print json_encode($person->toOject(false, nul, $array));
// output '{"id":1,"firstName":"alexander","children":["10","11"]}'

print json_encode($array); 
// output would be like '{"person":{"10":{"id":10,"firstName":"child_one"},"11":{"id":11,"firstName":"child_two"}}}'

# Object import You can import object via three formats :

• json (stdClass)
• XML (SimpleXMLElement)
• associative array which each value is a string (result of a sql database SELECT request)

respectively call functions :

• fromObject()
• fromXml()
• fromSqlDataBase()

Import via Object instance

$person = new Object('person');
$person->setValue('id', 1);
$person->setValue('firstName', 'alexander');

// merge object with values to import
person->fromOject(json_decode('{"id":1,"firstName":"john","lastName":"doe"}'));

print json_encode($person->toOject());
// output '{"id":1,"firstName":"john","lastName":"doe"}'

Import via Model instance

When you import an object via model this object is stored in MainObjectCollection.

$personModel = InstanceModel::getInstance()->getInstanceModel('person');
$person = $personModel->fromOject(json_decode('{"id":1,"firstName":"john","lastName":"doe"}'));

when you import object via model you can configure your import type

// merge (type merge is used by default if you don't specify it)
// if an object with same model and same id is found in MainObjectCollection get this instance 
// otherwise create a new one
// finally merge retrieved (or created) object with values to import
$person = $personModel->fromOject(json_decode('{"id":1,"firstName":"john","lastName":"doe"}'), Model::MERGE);

// overwrite
// if an object with same model and same id is found in MainObjectCollection get this instance and erase all values 
// otherwise create a new one
// finally fill retrieved (or created) object with values to import
$person = $personModel->fromOject(json_decode('{"id":1,"firstName":"john","lastName":"doe"}'), Model::OVERWRITE);

// no merge
// create a new instance even if an instance exists in MainObjectCollection
// finally fill created object with values to import
$person = $personModel->fromOject(json_decode('{"id":1,"firstName":"john","lastName":"doe"}'), Model::NO_MERGE);

Foreign properties import

When a value corresponding to a foreign property is imported it's only an id. Import will automaticaly try to find if referenced object exists and get this instance otherwise it will create a new object.

Date time management

We have seen in [Getting started] (https://github.com/jeanphilippe-p/ObjectManagerLib/wiki/Getting-started) page that a simple model dateTime exists so a property can have a type dateTime. A value with type dateTime will be an instance of [DateTime] (http://php.net/manual/fr/class.datetime.php). Using [DateTime] (http://php.net/manual/fr/class.datetime.php) is a good practice, there are many date and time related functions and it can handle time zones.

Import and export

When you import or export object you can specify an optional parameter that define time zone that you want to work with (by default your [PHP time zone] (http://php.net/manual/fr/function.date-default-timezone-get.php) is used).

// see php DateTime Constructor to know supported date time string formats
// use ISO 8601 format is a good practice
$person = $personModel->fromOject(json_decode('{"birthDate":"1988-05-01T14:53:54+02:00"}'), Model::MERGE, 'Europe/Paris');

// dateTime values are always exported in ISO 8601 format to encourage good practice
$person->toXml(false, Europe/Paris');

Database time zone

For most (all?) SGBD connection you can define your time zone. to set a specific time zone for your connection you must specify it in file [config.json] () (by default time zone connection is UTC).
Whatever is your database time zone you don't have to take care of it, serialization/deserialization will automatically affect good time zone to all your values with type dateTime.