Coleccion

Resumen

Phalcon\Collection es un arreglo o array orientado a objetos. Ofrece velocidad, así como implementaciones de varias interfaces PHP. Estas son:

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
    'year'   => 1776,
];

$collection = new Collection($data);

Constructor

Puede construir el objeto como cualquier otro objeto en PHP. Sin embargo, el constructor acepta un parámetro opcional array, que rellenará el objeto por usted.

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
    'year'   => 1776,
];

$collection = new Collection($data);

Sensible a mayúsculas

Al instanciar el objeto se puede especificar un segundo parámetro de tipo bool, el cual controlará la búsqueda por claves en el objeto. Por defecto $insensitive se establece en true, haciendo que las búsquedas en la colección sean insensibles a mayúsculas. Establecer este valor en false hará que la búsqueda del elemento sea sensible a mayúsculas y minúsculas.

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
    'year'   => 1776,
];

$collection = new Collection($data, false);

echo $collection->has('COLORS'); // false

Reutilización

También puede reutilizar el componente, volviéndolo a rellenar. Phalcon\Collection expone los métodos clear() e init() que borrarán y rellenaran la matriz interna respectivamente,

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
    'year'   => 1776,
];

$collection = new Collection($data);

echo $collection->count(); // 2

$data = [
    'year' => 1776,
];

$collection->clear();
$collection->init($data);

echo $collection->count(); // 1

Obtener

Como se mencionó anteriormente, Phalcon\Collection implementa varias interfaces, con el fin de hacer el componente lo más flexible posible. Recuperar datos almacenados en un elemento se puede hacer usando:

Propiedad
__get()
Acceso como arreglo ($collection[$element])
offsetGet()
get()

La manera más rápida es usando la sintaxis de propiedad:

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
    'year'   => 1776,
];

$collection = new Collection($data);

echo $collection->year; // 1776

Puede usar __get($element) pero no es recomendable ya que es mucho más lenta que la sintaxis de propiedad. Lo mismo se aplica a offsetGet

echo $collection->__get('year');           // 1776
echo $collection['year'];                  // 1776
echo $collection->offsetGet('year');       // 1776
echo $collection->get('year', 1776, true); // 1776

public function get(
    string $element, 
    mixed $defaultValue = null, 
    string $cast = null
):  mixed

Usar get() ofrece tres parámetros extra. Cuando se define $defaultValue en la llamada y el elemento no se encuentra, se devolverá $defaultValue. El parámetro cast acepta una cadena que define a qué tipo será convertido el valor devuelto. Los valores disponibles son:

array
bool
boolean
double
float
int
integer
null
object
string

El objeto de colección también ofrece dos getters más getKeys() y getValues(). getKeys(bool $insensitive = true) devuelve todas las claves almacenadas internamente en la colección. De forma predeterminada, devolverá las claves de forma insensible, es decir, todas las minúsculas. Si se pasa false en la llamada, retornará las claves exactamente como han sido almacenadas. getValues() devuelve los valores almacenados en la colección interna.

Has

Para comprobar si un elemento existe o no en la colección, puede usar lo siguiente:

isset() en la propiedad
__isset()
Acceso como arreglo (isset($coollection[$element]))
offsetExists()
has()

La manera más rápida es usando la sintaxis de propiedad:

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
    'year'   => 1776,
];

$collection = new Collection($data);

echo isset($collection->year); // true

Puede usar __isset(element) pero no es recomendable porque es mucho más lento que la sintaxis de propiedad. Lo mismo se aplica a offsetExists

echo $collection->__isset('year');        // true
echo isset($collection['year']);          // true
echo $collection->offsetExists('year');   // true
echo $collection->has('year', true);      // true

public function has(string $element):  bool

Establecer

Para establecer un elemento en la colección, puede utilizar lo siguiente:

asignar el valor a la propiedad
__set()
asignación basado en vector
offsetSet()
set()

La manera más rápida es usando la sintaxis de propiedad:

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
];

$collection = new Collection($data);

$collection->year = 1776;

Puedes usar __set($element, $value) pero no es recomendable ya que es mucho más lento que la sintaxis de propiedades. Lo mismo se aplica a offsetSet

$collection->__set('year', 1776);
$collection['year'] = 1776;
$collection->offsetSet('year', 1776);
$collection->set('year', 1776); 

Eliminar

Para eliminar un elemento en la colección, puede utilizar lo siguiente:

desestablecer la propiedad
__unset()
desestablecer basado en vector
offsetUnset()
remove()

La manera más rápida es usando la sintaxis de propiedad:

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
];

$collection = new Collection($data);

unset($collection->year);

Puedes usar __unset($element) pero no es recomendable ya que es mucho más lento que la sintaxis de propiedades. Lo mismo se aplica a offsetUnset

$collection->__unset('year');
unset($collection['year']);
$collection->offsetUnset('year');
$collection->remove('year'); 

public function remove(string $element):  void

Iteración

Dado que el objeto de colección implementa \IteratorAggregate, puedes iterar con facilidad a través del objeto. El método getIterator() devuelve un objeto ArrayIterator()

<?php

use Phalcon\Collection;

$data = [
   'red',
   'white',
   'blue'
];

$collection = new Collection($data);

foreach ($collection as $key => $value) {
    echo $key . ' - ' . $value . PHP_EOL;
}

Contar

La implementación de la interfaz \Countable expone el método count(), que almacena el número de elementos en la colección.

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
    'year'   => 1776,
];

$collection = new Collection($data);

echo $collection->count();    // 2

Serialización

Las interfaces \Serializable y \JsonSerializable exponen métodos que le permiten serializar y deserializar un objeto. serialize() y unserialize() utilizan las funciones serialize y unserialize de PHP. jsonSerialize() devuelve un arreglo que puede ser usado con json_encode() para serializar el objeto.

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
    'year'   => 1776,
];

$collection = new Collection($data);

echo $collection->serialize(); // a:2:{s:6:"colors";a:3:{i:0;s:3:"red";i:1;s:5:"white";i:2;s:4:"blue";}s:4:"year";i:1776;}

$serialized = 'a:2:{s:6:"colors";a:3:{i:0;s:3:"red";i:1;s:5:"white";i:2;s:4:"blue";}s:4:"year";i:1776;}';
$collection->unserialize($serialized);

echo $collection->jsonSerialize(); // $data

Transformaciones

Phalcon\Collection también expone dos métodos de transformación: toArray() y toJson(int $options). toArray() devuelve el objeto transformado como un arreglo. Este método devuelve el mismo array que jsonSerialize().

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
    'year'   => 1776,
];

$collection = new Collection($data);

echo $collection->toArray(); // $data

toJson(int $options) devuelve una representación JSON del objeto. Utiliza json_encode() internamente y acepta un parámetro, que representa las banderas que json_encode acepta. Por defecto, las opciones se configuran con el valor 74, (RFC4327) que se traduce a:

JSON_HEX_TAG
JSON_HEX_APOS
JSON_HEX_AMP
JSON_HEX_QUOT
JSON_UNESCAPED_SLASHES

Puede pasar cualquier bandera válida al método según sus necesidades.

<?php

use Phalcon\Collection;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
    'year'   => 1776,
];

$collection = new Collection($data);

echo $collection->toJson(); // ["red","white","blue"],"year":1776}

echo $collection->toJson(74 + JSON_PRETTY_PRINT);
/**
{
    "colors": [
        "red",
        "white",
        "blue"
    ],
    "year": 1776
}
*/

Sólo lectura

Phalcon también ofrece un componente que puede utilizarse de forma de sólo lectura. Phalcon\Collection\ReadOnly puede servir como una colección en su aplicación que sólo puede ser establecida con datos iniciales pero no permite que su contenido sea cambiado en toda la aplicación.

<?php

use Phalcon\Collection\ReadOnly;

$data = [
    'colors' => [
        'red',
        'white',
        'blue',
    ],
    'year'   => 1776,
];

$collection = new ReadOnly($data);

echo $collection->toJson(); // ["red","white","blue"],"year":1776}

$collection->set('colors', ['red']); // Exception