# Basics

## Create an object

```php
use Dustin\Encapsulation\Encapsulation;

$encapsulation = new Encapsulation();
```

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

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

## Setting values

### Setting a single value to a field

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

### Unsetting a value

```php
$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:

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

### Adding a value to a collection

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

```php
use Dustin\Encapsulation\Encapsulation;
use Dustin\Encapsulation\Container;

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

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

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

The elements of the container in `'myContainer'` will now be `'foo'` and `'bar'`.

* 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 or a container the given value will be added to it.
* If a field does exist but is **not** an array and **not** a container you will get an exception.

### Adding several values to a collection

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

```php
$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

```php
$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:

```php
$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:

```php
$data = $encapsulation->toArray();
```

## More

### Check if a field exists

<pre class="language-php"><code class="lang-php"><strong>$encapsulation = new Encapsulation(['foo' => $foo]);
</strong><strong>
</strong><strong>$encapsulation->has('foo'); // Returns true
</strong><strong>$encapsulation->has('bar'); // Returns false
</strong></code></pre>

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

```php
$fields = $encapsulation->getFields();
```

### Check if an object has values

```php
$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:

```php
$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.