Basics

Create an object

use Dustin\Encapsulation\Encapsulation;

$encapsulation = new Encapsulation();

Most encapsulations can be initialized with data in their constructor. The data is needed as associative array:

$encapsulation = new Encapsulation([
    'foo' => $foo,
    'bar' => $bar
]);

Setting values

Setting a single value to a field

$encapsulation->set('foo', $foo);
//or
$encapsulation['foo'] = $foo;

Unsetting a value

$encapsulation->unset('foo');
//or
unset($encapsulation['foo']);

Setting several values

You can set values of several fields at once. All keys of an associative array will overwrite or set the corresponding field:

$encapsulation->setList([
    'foo' => $foo,
    'bar' => $bar
]);

Adding a value to an array

If a field of your encapsulation holds an array you can append an item to it:

$encapsulation = new Encapsulation([
    'myList' => [1,2,3]
]);

$encapsulation->add('myList', 4);

The array in 'myList' will now be [1,2,3,4]

If a field does not exist a new array will be created and filled with the given value.

If a field does exist and is an array the given value will be appended to it.

If a field does exist but is not an array you will get an exception.

Adding several values to an array

You also can add more than one value to an array:

$encapsulation = new Encapsulation([
    'fruits' => ['apple', 'banana', 'melon']
]);

$encapsulation->addList('fruits', ['orange', 'grapefruit', 'kiwi']);

The array in 'fruits' will now be:

['apple', 'banana', 'melon', 'orange', 'grapefruit', 'kiwi']

Getting values

Get a single value

$foo = $encapsulation->get('foo');
//or
$foo = $encapsulation['foo'];

Getting several values as associative array

You can access more than one value of an encapsulation and get them as associative array by providing an array with a list of all requested fields. Each requested field will appear as key in the array result:

$data = $encapsulation->getList(['foo', 'bar']);

// will return:
[
    'foo' => '<the value of foo>',
    'bar' => '<the value of bar>'
]

Getting all values as associative array

An encapsulation can be "converted" into an array by getting an associative array of all of it's values:

$data = $encapsulation->toArray();

More

Check if a field exists

$encapsulation = new Encapsulation(['foo' => $foo]);

$encapsulation->has('foo'); // Returns true
$encapsulation->has('bar'); // Returns false

The has-method does only check if a field is present. It does not check if it's value is empty or not.

Get an array of all fields

$fields = $encapsulation->getFields();

Check if an object has values

$isEmpty = $encapsulation->isEmpty();

ArrayEncapsulations will check if fields are present regardless of wether the value is empty.

PropertyEncapsulations always have fields so they check if all fields are empty.

Iterate over all fields

You can iterate over one encapsulation object and get each field with it's value:

$encapsulation = new Encapsulation([
    'foo' => $foo,
    'bar' => $bar
]);

foreach($encapsulation as $field => $value) {
    // do something
}

Cloning

An encapsulation will always be deep-cloned which means cloning an encapsulation clones it's inner objects too which allows to clone a whole encapsulation tree at once.