yannoff/collections

A simple object implementation for PHP arrays

Maintainers

Details

github.com/yannoff/collections

Homepage

Source

Issues

Installs: 30

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 3

Forks: 0

Open Issues: 0

1.2.1 2020-11-26 19:18 UTC

Requires (Dev)

MIT 8d7ebe2d656c48f7ea4322ab911a3295b56a198c

This package is auto-updated.

Last update: 2024-04-27 03:17:34 UTC

README

A simple object implementation of PHP arrays.

Latest Stable Version Total Downloads License

The concept

Based upon the Decorator design pattern, the aim is to provide a flexible, object-oriented alternative to PHP Arrays.

Installation

Using composer:

$ composer require yannoff/collections

Usage

Example: PHP Array vs Collection

The classic way - native PHP arrays:

<?php

// Using PHP native arrays, the classic way:
$countries = [ 'France', 'Italia' ];

// Push an element
array_push($countries, 'Switzerland');

// Append an element
$countries[] = 'Belgium';

The new way - using collections:

<?php

use Yannoff\Component\Collections\Collection;

// Using collections:
$countries = new Collection([ 'France', 'Italia' ]);

// Push an element
$countries->push('Switzerland');

// Append an element: the same syntax as for arrays
$countries[] = 'Belgium';

// Exporting the collection back to a native PHP array:
$array = $countries->all();

// As for native arrays, collections can be traversed with a foreach:
foreach($countries as $key => $value) {
    // ...
}

Methods

See the full method list section for more details.

Array / Collection method equivalences:

Array Collection
implode($glue, $array) $collection->join($glue)
array_filter($array, $callback, $flag) $collection->filter($callback, $flag)
array_flip($array) $collection->flip()
array_keys($array) $collection->keys()
array_pop(&$array) $collection->pop()
array_push(&$array, $element) $collection->push($element)
array_reverse($array) $collection->reverse()
array_search($needle, $array) $collection->search($needle)
array_slice($array, $offset, $length) $collection->slice($offset, $length)
array_shift(&$array) $collection->shift()
array_unshift(&$array, $element) $collection->unshift($element)
array_walk(&$array, $callback, $userdata) $collection->walk($callback, $userdata)
current(&$array) $collection->current()
end(&$array) $collection->end()
next(&$array) $collection->next()
prev(&$array) $collection->prev()
sort(&$array) $collection->sort()
asort(&$array) $collection->asort()
ksort(&$array) $collection->ksort()

Along with those classical PHP methods wrappers, a few bag methods are provided:

method description
add($key, $element) Add an element at the given key in the collection
all() Return all the collection elements
clear() Remove all elements from the collection
get($key) Get an element of the collection by its key
has($key) Check for existence of the given key in the collection
set($elements) Set the whole elements of the collection

Full method list

Synopsis

use Yannoff\Component\Collections\Collection;

__construct()

Collection constructor.

Arguments
Name Type Description
$elements array
Return value

No return value.

push()

Push one element onto the end of the collection.

Arguments
Name Type Description
$element mixed
Return value
Type Description
int The new number of elements in the collection.

pop()

Pop the element of the end of the collection and return it.

Arguments

No arguments.

Return value
Type Description
mixed The popped element.

slice()

Extract a slice of $length elements from $offset-th element.

Arguments
Name Type Description
$offset int The element to start from
$length int The number of elements to extract
Return value
Type Description
Collection

shift()

Shift an element off the beginning of the collection and return it.

Arguments

No arguments.

Return value
Type Description
mixed The shifted element.

unshift()

Prepend an element to the beginning of the collection.

NOTE: Prepending multiple elemnts is not supported.

Arguments
Name Type Description
$element mixed The element to prepend.
Return value
Type Description
int The new number of elements in the collection.

keys()

Return all the keys of the collection.

NOTE: Filtering on a search value to fetch a subset of the keys is not implemented.

Arguments

No arguments.

Return value
Type Description
array

search()

Search the collection for a given value and returns the first corresponding key if successful.

NOTE: The strict flag is not implemented for now.

Arguments
Name Type Description
$needle mixed The value to search.
Return value
Type Description
false|int|string The key/offset if found, false otherwise.

join()

Build a string by concatening all elements with the given glue.

Arguments
Name Type Description
$glue string The concatening string.
Return value
Type Description
string

reverse()

Return all elements of the collection in reversed order.

Arguments

No arguments.

Return value
Type Description
Collection

flip()

Flip collection: set value as keys & keys as values.

Arguments

No arguments.

Return value
Type Description
Collection

filter()

Apply a user supplied function to filter elements.

Arguments
Name Type Description
$callback callable Callback to be applied.
$flag int Flag determining what arguments are passed to the callback.

Possible values for the $flag parameter:

  • ARRAY_FILTER_USE_KEY: pass key as the only argument to callback instead of the value.
  • ARRAY_FILTER_USE_BOTH: pass both value and key as arguments to callback instead of the value.

Default is 0 which will pass value as the only argument to callback instead.

Return value
Type Description
Collection The filtered elements collection

walk()

Apply a user supplied function to each element of the collection.

Arguments
Name Type Description
$callback callable Callback to be applied.
$userdata mixed|null Optional user data to be passed the callback to.
Return value
Type Description
bool (always true)

current()

Returns the element that's currently being pointed to by the internal pointer.

Arguments

No arguments.

Return value
Type Description
mixed The current element or false if the internal pointer is beyond the end or collection is empty

end()

Advances internal pointer to the last element, and returns its value

Arguments

No arguments.

Return value
Type Description
mixed The last element or false if collection is empty

prev()

Rewinds the internal array pointer one place backward before returning the element

Arguments

No arguments.

Return value
Type Description
mixed The previous place element or false if there are no more elements

next()

Advances the internal pointer one place forward before returning the element

Arguments

No arguments.

Return value
Type Description
mixed The next place element or false if there are no more elements

all()

Return all the collection elements.

Arguments

No arguments.

Return value
Type Description
array

has()

Check for existence of the given key in the collection.

Arguments
Name Type Description
$key mixed The searched key.
Return value
Type Description
bool true if the key is found, false otherwise.

get()

Get an element of the collection by its key.

Arguments
Name Type Description
$key mixed The requested element's key.
Return value
Type Description
mixed

add()

Add an element at the given key in the collection.

Arguments
Name Type Description
$key mixed Key/offset.
$element mixed Element to add.
Return value

No return value.

set()

Set the whole elements of the collection.

Arguments
Name Type Description
$elements array An elements array.
Return value

No return value.

clear()

Remove all elements from the collection.

Arguments

No arguments.

Return value

No return value.

offsetExists()

Check wether the given offset exists in the collection

Arguments
Name Type Description
$offset mixed An offset to check for.
Return value
Type Description
boolean true on success or false on failure.

offsetGet()

Get the element at the given offset

Arguments
Name Type Description
$offset mixed The offset to retrieve.
Return value
Type Description
mixed

offsetSet()

Set the element at the given offset

Arguments
Name Type Description
$offset mixed The offset to assign the value to.
$value mixed The value to set.
Return value

No return value.

offsetUnset()

Unset the element at the given offset

Arguments
Name Type Description
$offset mixed The offset to unset.
Return value

No return value.

count()

Return elements count in the collection

Arguments

No arguments.

Return value
Type Description
int The custom count as an integer.

key()

Return the key of the current element

Arguments

No arguments.

Return value
Type Description
mixed scalar on success, or null on failure.

valid()

Checks if current position is valid

Arguments

No arguments.

Return value
Type Description
boolean true on success or false on failure.

rewind()

Rewind the Iterator to the first element

Arguments

No arguments.

Return value

No return value.

ksort()

Sort elements by their key

Arguments

No arguments.

Return value
Type Description
Collection The collection instance.

sort()

Sort elements by their value

Arguments

No arguments.

Return value
Type Description
Collection The collection instance.

asort()

Sort elements by their value, but maintain index association

Arguments

No arguments.

Return value
Type Description
Collection The collection instance.

License

Released under the MIT License