# Container

A container holds a list of elements and does not take care of keys.

## Create a container

```php
use Dustin\Encapsulation\Container;

$container = new Container();
```

A container can optionally be initialized with a list of elements:

```php
$container = new Container([$foo, $bar]);
```

## Add elements

```php
$container = new Container();

$container->add($foo, $bar);
```

You can pass as many elements as you want to the `add`-method.

## Access Elements

You can get a single element of a container at a specific position:

```php
$productNumbers = new Container(['My1003', 'My1004', 'My1005']);

$number = $productNumbers->getAt(1); // Returns 'My1004'
```

You also can get all elements of a container as array:

```php
$container = new Container([$foo, $bar]);

$array = $container->toArray();
```

## Count elements of a container

```php
$container = new Container([$foo, $bar]);

$container->count();
// or
count($container); 
// Returns 2
```

You can also check if a container has elements:

```php
$container->isEmpty();
```

## Iterate over all elements

You can also use a container in a loop and iterate over all elements:

```php
$container = new Container([$foo, $bar]);

foreach($container as $element) {
    // do something
}
```

## Delete elements

You can clear a container which unsets all of it's elements:

```php
$container->clear();
```

## Copy a container

```php
$container = new Container([$foo, $bar]);

$newContainer = $container->copy();
```

{% hint style="warning" %}
Copying a container does **not** clone object elements.
{% endhint %}

### Merging serveral containers together

{% code overflow="wrap" %}

```php
$container = Container::merge(
    new Container([$foo, $bar]), 
    new Container([$alice, $bob]),
    new Container([$hello, $world])
);
```

{% endcode %}

`$container` will now be a new container object holding the values of `$foo`, `$bar`, `$alice`, `$bob`, `$hello` and `$world`.

You can pass as many container objects to the `merge`-function as you want.

## Sorting elements

You can sort the elements of a container ascending, descending or by a callback. Internally the array functions [usort](https://www.php.net/manual/en/function.usort.php), [sort](https://www.php.net/manual/en/function.sort.php) and [rsort](https://www.php.net/manual/en/function.rsort.php) will be used so you optionally can pass their flags.

### Sort elements by callback

```php
$container->sort(function($a, $b) {
    // return sort result
});
```

### Sort elements ascending

```php
$container->sort();
// or
$container->sort(null, Container::ASCENDING, $optionalFlags);
```

### Sort elements descending

```php
$container->sort(null, Container::DESCENDING, $optionalFlags);
```

## Array functions

The container class brings a bunch of wrapper methods according to some of PHP's array functions. Each function takes the same parameters as the default PHP function except the input array.

Most methods return the container itself or a new instance which makes it easy to concat method calls to get the wanted container object:

```php
$newContainer = $container->map($myCallback)->filter()->unique();
```

### [array\_map](https://www.php.net/manual/en/function.array-map.php)

```php
$newContainer = $container->map(function($element) {
    // do and return something
});
```

{% hint style="info" %}
`map` will create and return a new container instance.
{% endhint %}

### [array\_reduce](https://www.php.net/manual/en/function.array-reduce.php)

```php
$value = $container->reduce(
    function($carry, $element) {
        // do and return something
    }, 
    $optionalInitValue
);
```

### [array\_filter](https://www.php.net/manual/en/function.array-filter.php)

```php
$newContainer = $container->filter($optionalCallbackFunction);
```

{% hint style="info" %}
`filter` will create and return a new container instance.
{% endhint %}

### [array\_slice](https://www.php.net/manual/en/function.array-slice.php)

```php
$newContainer = $container->slice($offset, $optionalLength);
```

{% hint style="info" %}
`slice` will create and return a new container instance.
{% endhint %}

### [array\_splice](https://www.php.net/manual/en/function.array-splice.php)

```php
$container->splice($offset, $optionalLength, $replacement);
```

### [array\_unique](https://www.php.net/manual/en/function.array-unique.php)

```php
$newContainer = $container->unique($optionalFlags);
```

{% hint style="info" %}
`unique` will create and return a new container instance.
{% endhint %}

### [array\_shift](https://www.php.net/manual/en/function.array-shift.php)

```php
$value = $container->shift();
```

### [array\_unshift](https://www.php.net/manual/en/function.array-unshift.php)

```php
$container->unshift(...$elements);
```

### [array\_pop](https://www.php.net/manual/en/function.array-pop.php)

```php
$value = $container->pop();
```

### [array\_replace](https://www.php.net/manual/en/function.array-replace.php)

```php
$newContainer = $container->replace(... $replacements);
```

{% hint style="info" %}
`replace` will create and return a new container instance.
{% endhint %}

### [array\_walk](https://www.php.net/manual/en/function.array-walk.php)

```php
$container->walk(
    function($element) { 
        // do something
    },
    $optionalArg
);
```

### [array\_reverse](https://www.php.net/manual/en/function.array-reverse.php)

```php
$newContainer = $container->reverse();
```

{% hint style="info" %}
`reverse` will create and return a new container instance.
{% endhint %}

### [array\_search](https://www.php.net/manual/en/function.array-search.php)

```php
$index = $container->search($needle, $strict);
```

### [in\_array](https://www.php.net/manual/en/function.in-array.php)

```php
$result = $container->has($element);
```

### [array\_chunk](https://www.php.net/manual/en/function.array-chunk.php)

```php
$arrayOfNewContainers = $container->chunk($size);
```


---

# 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/v1.1/getting-started/basics/container.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.