Nearly all collections of items in ProcessWire are derived from the WireArray.

This includes groups of pages called PageArrays, as returned by $pages->find, $page->children, and multi-Page reference field types (among others), groups of files or images, as returned by file and image field types, groups of fields, as returned by $page->fields or $template->fields or the $fields API variable, groups of Templates, Roles, Fieldgroups, Comments, Users, Modules, Permissions and more.... Nearly everything. As a result, the WireArray interface is one you will be interacting with regularly in the ProcessWire API whether you know it or not. This page documents all of the methods that are common to all WireArrays.

Related Types

Note: in the following reference, $a represents the name of any WireArray variable, so $a as a variable name is not significant.

Getting Items

$a[$key]Returns the value of the item at the given $key, or null if not set.
$a->$keyReturn the item indexed by $key or null if not found.
$a->get($key)Returns the value of the item at the given $key, or null if not set.
$a->get("selector")Return the first item that matches the given selector, or null if not found.
$a->find("selector")Return all items that match the given selector, or a blank WireArray if none found.
$a->getArray()Returns a regular PHP array of all items in this WireArray.
$a->getKeys()Returns a regular PHP array of all keys used in this WireArray.
$a->getValues()Returns a regular PHP array of all values used in this WireArray.
$a->getRandom()Returns a single random item from this WireArray.
$a->getRandom($n)Returns $n random items from this WireArray (contained in a new WireArray).
$a->slice($n)Returns a new WireArray containing a slice of items from the $n'th item to the end.
$a->slice($n, $limit)  Returns a new WireArray containing a slice of items starting from the $n'th item and including up to $limit number of items.
$a->shift()Remove (shift) the first $item from the WireArray and return it.
$a->pop()Pop the last item off of the WireArray and return it.
$a->index($n)Returns a new WireArray containing the item at the given zero-based index.
$a->eq($n)Returns the single item at the given zero-based index, or NULL if it doesn't exist.
$a->first()Returns the first item in the WireArray.
$a->last()Returns the last item in the WireArray.
$a->getNext($item)  Given an item already in the WireArray, return the item that comes after it in this WireArray or NULL if no match.
$a->getPrev($item)Given an item already in the WireArray, return the item that comes before it in this WireArray or NULL if no match.

Setting and modifying items

$a[] = $itemAdd the given $item.
$a->add($item)Add the given $item.
$a[$key] = $itemAdd the given $item, associating it with index $key.
$a->set($key, $item)Add the given $item, associating it with index $key.
$a->$key = $itemAdd the given $item, associating it with index $key.
$a->import($items)Given an array or WireArray of items, add them all.
$a->prepend($item)Prepend the given item to the beginning of the WireArray.
$a->append($item)  Append the given item to the end of the WireArray.
$a->unshift($item)Prepend the given item to the beginning of the WireArray (same as prepend)
$a->shift()Remove (shift) the first $item from the WireArray and return it.
$a->push($item)Push the given item onto the end of the WireArray.
$a->pop()Pop the last item off of the WireArray and return it.
unset($array[$key])  Removes the item with the given $key from the WireArray.
$a->remove($key)Removes the item with the given $key from the WireArray.
$a->remove($item)  Removes the given $item from the WireArray.

Unless otherwise noted, all set/modify/remove functions listed above return reference to the WireArray, enabling you to stack these functions in a fluent interface. 

Checking for items

$a->count()  Returns the number of items in this WireArray.
count($a)Returns the number of items in this WireArray.
$a->has($key)Is the given key part of this WireArray?
$a->has("selector")Does the given selector match any items in this WireArray?
isset($a[$key])Returns true if the given $key is set with an item.
$a->isValidItem($item)Is the given item a valid type for this WireArray?
$a->isValidKey($key)Is the given $key valid to use for this WireArray?
$a->getItemKey($item)Get the key used by $item or NULL if not available.

Sorting and Filtering

$a->shuffle()  Randomize the order of all the items in the WireArray.
$a->sort("property")  Sorts the WireArray by the given item property (string). You may also specify the property as "property.subproperty", where property resolves to a Wire derived object, and subproperty resolves to a property within that object. Prepend a minus sign "-" to the property name reverse the sort.
$a->filter("selector")  Reduce the WireArray so that it only contains items that match the given selector.
$a->not("selector")  Reduce the WireArray so that it only contains items that don't match the given selector.
$a->reverse()Return a new WireArray containing the items in reverse order.

Change Tracking

$a->setTrackChanges()Turn on change tracking
$a->setTrackChanges(false)Turn off change tracking
$a->resetTrackChanges()Reset any changes that have been tracked and start tracking again.
$a->resetTrackChanges(false)Reset any changes that have been tracked and stop tracking.
$a->getChanges()Return an array of item keys that have changed while change tracking was on.
$a->getItemsAdded()Return an array of items that have been added since change tracking was turned on.
$a->getItemsRemoved()Return an array of items that have been removed since change tracking was turned on.

Miscellaneous

$a->makeBlankItem()Make a new blank item suitable for storage in this WireArray.
$a->makeNew()Make a new blank WireArray of the same type as $a.

Iteration

You can iterate a WireArray just like a regular PHP array.

<?php
foreach($a as $key => $item) {
    echo "$key = $item <br />";
}

See Also

Comments

No comments yet. Be the first to post!

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.