# 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 encapsulation objects too which allows to clone a whole encapsulation tree at once.

Non-encapsulation objects will **not** be deep-cloned.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dustinsimon.gitbook.io/encapsulation/getting-started/basics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.