Collection..

Phproberto\Joomla\Entity\Collection

Class to perform common actions on groups of entities.

Index

Usage
Methods

Usage

A couple of fast examples:

<?php
JLoader::import('phproberto_entity.library');

use Joomla\Registry\Registry;
use Phproberto\Joomla\Entity\Content\Article;
use Phproberto\Joomla\Entity\Collection;

$articles = new Collection(array(Article::instance(69), Article::instance(70), Article::instance(71)));

// Collection implements Iterator so you can traverse it like
foreach ($articles as $articleId => $article)
{
    echo $articleId . '. ' . $article->get('title') . '<br />';
}

// It also implements Countable
echo 'Collecton has ' . $articles->count() . ' entities <br />';

// Other entities can return collections
$article = Article::instance(71);

foreach ($article->getTags() as $tagId => $tag)
{
    echo 'Tag ' . $tagId . '. ' . $tag->get('title') . '<br />';
}

// Check if an article is in the collection
if ($articles->has(69))
{
    echo $articles->get(69)->id() . '. ' . $articles->get(69)->get('title') . '<br />';
}

// Add entities
$articles->add(Article::instance(72));

// Remove entities
$articles->remove(69);

// Get the ids of the entities in the collection
var_dump($articles->ids());

// Clear the collection
$articles->clear();

// Check if collection is empty
if ($articles->isEmpty())
{
    echo 'Collection is empty <br />';
}

add(EntityInterface $entity)

Add an entity to the collection.

Parameters:

EntityInterface $entity (required): Entity to add.

Returns:

boolean

Examples:

$collection = new Collection;

$collection->add(Article::instance(1));

all()

Get all the entities in the collection as array. Most of the times you don’t want to use this because collection already behaves like an array.

Parameters:

None

Returns:

array

Examples:

$collection = new Collection(array(Article::instance(70), Article::instance(69)));

foreach ($collection->all() as $entity)
{
    echo $entity->id() . '. ' . $article->get('title') . '<br />';
}

clear()

Clears all the entities of the collection.

Parameters:

None

Returns:

self

Examples:

$collection = new Collection;

$collection->add(Article::instance(1));
$collection->add(Article::instance(2));

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

$collection->clear();

// Will echo 0
echo $collection->count();

count()

Get the count of entities in this collection.

Parameters:

None

Returns:

integer

Examples:

$collection = new Collection;

$collection->add(Article::instance(1));
$collection->add(Article::instance(2));

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

current()

Get the active entity for iterations. Part of the iterator implementation.

Parameters:

None

Returns:

mixed EntityInterface FALSE for no entities

Examples:

$collection = new Collection(array(Article::instance(69), Article::instance(70), Article::instance(71)));

while ($collection->valid())
{
    $article = $collection->current();
    echo $article->id() . '. ' . $article->get('title') . '<br />';
    $collection->next();
}

has($id)

Check if an entity is present in this collection.

Parameters:

integer $id (required): Entity identifier.

Returns:

boolean

Examples:

$collection = new Collection(array(Article::instance(69), Article::instance(70), Article::instance(71)));

// Will return true
var_dump($collection->has(69));

// Will return false
var_dump($collection->has(13));

get($id)

Get an entity by its identifier.

Parameters:

integer $id (required): Entity identifier.

Returns:

EntityInterface

Examples:

$articles = new Collection(array(Article::instance(70), Article::instance(69), Article::instance(71)));

// Will echo 69
var_dump($articles->get(69)->id());

// Trying to retrieve an unexisting entity will throw an exception
try
{
    $article = $articles->get(999);
}
catch (\InvalidArgumentException $e)
{
    $article = $articles->get(69);
}

// Will echo 69 because retrieving 999 threw an exception
var_dump($articles->get(69)->id());

ids()

Returns ids of the entities in this collection in the order they were added.

Parameters:

None

Returns:

array

Examples:

$collection = new Collection(array(Article::instance(70), Article::instance(69), Article::instance(71)));

// Will return: [70, 69, 71]
var_dump($collection->ids());

intersect(Collection $collection)

Get a new collection containing entities present in two collections.

Parameters:

Collection $collection (required): Collection to intersect.

Returns:

static

Examples:

$articles = new Collection(array(Article::instance(69), Article::instance(70)));
$articles2 = new Collection(array(Article::instance(69), Article::instance(72)));

// Will show [69]
var_dump($articles->intersect($articles2)->ids());

isEmpty()

Check if the collection is empty.

Parameters:

None

Returns:

boolean

Examples:

$collection = new Collection;

// Will return true
var_dump($collection->isEmpty());

$collection = new Collection(array(Article::instance(70), Article::instance(69), Article::instance(71)));

// Will return: false
var_dump($collection->isEmpty());

key()

Return the id of the active entity.

Parameters:

None

Returns:

integer

Examples:

$collection = new Collection(array(Article::instance(69), Article::instance(70), Article::instance(71)));

while ($collection->valid())
{
    $article = $collection->current();
    echo $collection->key() . '. ' . $article->get('title') . '<br />';
    $collection->next();
}

krsort()

Sort collection entities reversely by id.

Parameters:

None

Returns:

static New collection with entities ordered

Examples:

$articles = new Collection(array(Article::instance(69), Article::instance(70), Article::instance(71)));

$articles->krsort();

// Will print [71, 70, 69]
var_dump($articles->ids());

ksort()

Sort collection entities by id.

Parameters:

None

Returns:

static New collection with entities ordered

Examples:

$articles = new Collection(array(Article::instance(70), Article::instance(60), Article::instance(71)));

$articles->ksort();

// Will print [60, 70, 71]
var_dump($articles->ids());

map(callable $function)

Execute a function on all the items in the collection.

Parameters:

callable $function (required) : Function to execute. It will receive the entity as first parameter.

Returns:

static New collection with modified entities

Examples:

$articles = new Collection(array(Article::instance(70), Article::instance(60), Article::instance(71)));

// Change the title of all the articles
$articles->map(
    function($article)
    {
        $article->assign('title', $article->get('title') . ' edited');

        return $article;
    }
);

merge(Collection $collection)

Create a new collection containing elements from 2 collections.

Parameters:

Collection $collection (required): Collection to merge.

Returns:

static

Examples:

$articles = new Collection(array(Article::instance(69), Article::instance(70)));
$articles2 = new Collection(array(Article::instance(71), Article::instance(72)));

// Will show [69, 70, 71, 72]
var_dump($articles->merge($articles2)->ids());

next()

Gets the next entity. Part of the iterator implementation.

Parameters:

None

Returns:

mixed EntityInterface FALSE if no entities

Examples:

$collection = new Collection(array(Article::instance(69), Article::instance(70), Article::instance(71)));

$article = $collection->current();

// It will echo something like: 69. Quick Icons
echo $article->id() . '. ' . $article->get('title') . '<br />';

$article = $collection->next();

// It will echo something like: 70. Smart Search
echo $article->id() . '. ' . $article->get('title') . '<br />';

$article = $collection->next();

// It will echo something like: 71. Similar Tags
echo $article->id() . '. ' . $article->get('title') . '<br />';

remove($id)

Remove an entity from the collection.

Parameters:

integer $id (required): Entity identifier.

Returns:

boolean

Examples:

$collection = new Collection(array(Article::instance(70), Article::instance(69), Article::instance(71)));

// Will print [70, 69, 71]
var_dump($collection->ids());

$collection->remove(69);

// Will print [70, 71]
var_dump($collection->ids());

rewind()

Get the first entity in the collection. Part of the iterator implementation.

Parameters:

None

Returns:

mixed EntityInterface FALSE if no entities

Examples:

$articles = new Collection(array(Article::instance(70), Article::instance(69), Article::instance(71)));

foreach ($articles as $article)
{
    echo $article->id() . '. ' . $article->get('title') . '<br />';
}

// Will echo 71
echo '<pre>'; print_r($article->id()); echo '</pre>';

$article = $articles->rewind();

// Will echo 70
echo '<pre>'; print_r($article->id()); echo '</pre>';

sort(callable $function)

Apply custom function to order collection entities.

Parameters:

callable $function (required) : Function to order entities.

Returns:

static New collection with entities ordered

Examples:

$articles = new Collection(array(Article::instance(70), Article::instance(60), Article::instance(71)));

$sortByTitle = function ($entity1, $entity2)
{
    return strcmp($entity1->get('title'), $entity2->get('title'));
};

$reverseSortByTitle = function ($entity1, $entity2)
{
    return strcmp($entity2->get('title'), $entity1->get('title'));
};

$articles->sort($sortByTitle);

echo '<h3>Ascending</h3>';

// This will print article titles ordered alphabetically by title
foreach ($articles as $article)
{
    echo '<pre>'; print_r($article->get('title')); echo '</pre>';
}

$articles->sort($reverseSortByTitle);

echo '<h3>Descending</h3>';

// This will print article titles ordered alphabetically by title in descending order
foreach ($articles as $article)
{
    echo '<pre>'; print_r($article->get('title')); echo '</pre>';
}

sortBy($property)

Sort entities by a property.

Parameters:

string $property (required): Property to use for ordering.
string $direction (optional): Ordering direction: ‘ASC’ ‘DESC’.

Returns:

static New collection with entities ordered

Examples:

$tags = Article::instance(71)->getTags();

$tags->sortBy('id');

// This will show ids ordered ascendently
foreach ($tags as $tag)
{
    echo '<pre>'; print_r($tag->id()); echo '</pre>';
}

$tags->sortBy('id', $tags::DIRECTION_DESCENDING);

// This will show ids ordered descendently
foreach ($tags as $tag)
{
    echo '<pre>'; print_r($tag->id()); echo '</pre>';
}

sortByDesc($property)

Sort entities in descendent order by a property. This is a fast usage proxy sortBy with descendencing direction.

Parameters:

string $property (required): Property to use for ordering.

Returns:

static New collection with entities ordered

Examples:

$tags = Article::instance(71)->getTags();

$tags->sortByDesc('title');

// This will show tags ordered by title descendently
foreach ($tags as $tag)
{
    echo '<pre>'; print_r($tag->get('title')); echo '</pre>';
}

toObjects()

Get all data from all the entities as objects.

Parameters:

None

Returns:

array

Examples:

$articles = new Collection(array(Article::instance(69), Article::instance(70)));

// Will return an array of objects with articles data
var_dump($articles->toObjects());

valid()

Check if there are still entities in the entities array. Part of the iterator implementation.

Parameters:

None

Returns:

boolean

Examples:

$collection = new Collection(array(Article::instance(69), Article::instance(70), Article::instance(71)));

while ($collection->valid())
{
    $article = $collection->current();
    echo $collection->key() . '. ' . $article->get('title') . '<br />';
    $collection->next();
}

write(EntityInterface $entity, $overwrite = true)

Add an entity to the collection.

Parameters:

EntityInterface $entity (required) : Entity to write.
boolean $overwrite (optional): Force writing the entity if it already exists

Returns:

boolean

Examples:

$collection = new Collection;

$collection->add(Article::instance(1));