Class WireArray

ProcessWire WireArray

WireArray is the base array access object used in the ProcessWire framework.

Several methods are duplicated here for syntactical convenience and jQuery-like usability. Many methods act upon the array and return $this, which enables WireArrays to be used for fluent interfaces. WireArray is the base of the PageArray (subclass) which is the most used instance.

TODO narrow down to one method of addition and removal, especially for removal, i.e. make shift() run through remove()

http://www.processwire.com http://www.ryancramer.com

Wire implements TrackChanges

WireArray implements IteratorAggregate, ArrayAccess, Countable

Direct known subclasses

Breadcrumbs, CommentArray, Pagefiles, Selectors, TemplatesArray, Fieldgroup, FieldgroupsArray, FieldsArray, Fieldtypes, InputfieldsArray, Modules, Notices, PageArray

Indirect known subclasses

Pageimages

Located at core/Array.php

Methods summary
`public boolean`	# `isValidItem( mixed $item )` Template mehod that descendant classes may use to validate items added to this WireArray Template mehod that descendant classes may use to validate items added to this WireArray Parameters `$item` `mixed` Item to add Returns `boolean` True if item is valid and may be added, false if not
`public boolean`	# `isValidKey( string\|integer $key )` Template method that descendant classes may use to validate the key of items added to this WireArray Template method that descendant classes may use to validate the key of items added to this WireArray Parameters `$key` `string\|integer` Returns `boolean` True if key is valid and may be used, false if not
`public string\|integer\|null`	# `getItemKey( object $item )` Template method that descendant classes may use to find a key from the item itself, or null if disabled. Template method that descendant classes may use to find a key from the item itself, or null if disabled. Used by add() and prepend() Parameters `$item` `object` Returns `string\|integer\|null`
`public mixed`	# `makeBlankItem( )` Get a blank copy of an item of the type that this WireArray holds Get a blank copy of an item of the type that this WireArray holds Returns `mixed`
`public WireArray`	# `makeNew( )` Creates a new blank instance of itself. For internal use. Creates a new blank instance of itself. For internal use. Returns `WireArray`
`public WireArray`	# `import( array\|WireArray $items )` Import items into this WireArray. Import items into this WireArray. Parameters `$items` `array\|WireArray` Items to import. Returns `WireArray` This instance.
`public WireArray`	# `add( integer\|string\|array\|object $item )` Add an item to the end of the WireArray. Add an item to the end of the WireArray. Parameters `$item` `integer\|string\|array\|object` Item to add. Returns `WireArray` This instance.
`protected`	# `_insert( $item, $existingItem, $insertBefore = true )` Insert an item either before or after another Insert an item either before or after another Provides the implementation for the insertBefore and insertAfter functions
`public`	# `insertBefore( integer\|string\|array\|object $item, integer\|string\|array\|object $existingItem )` Insert an item before an existing item Insert an item before an existing item Parameters `$item` `integer\|string\|array\|object` Item you want to insert `$existingItem` `integer\|string\|array\|object` Wire $existingItem Item already present that you want to insert before
`public`	# `insertAfter( integer\|string\|array\|object $item, integer\|string\|array\|object $existingItem )` Insert an item after an existing item Insert an item after an existing item Parameters `$item` `integer\|string\|array\|object` Item you want to insert `$existingItem` `integer\|string\|array\|object` Wire $existingItem Item already present that you want to insert after
`public`	# `set( integer\|string $key, integer\|string\|array\|object $value )` Sets an index in the WireArray. Sets an index in the WireArray. Parameters `$key` `integer\|string` Key of item to set. `$value` `integer\|string\|array\|object` Value of item.
`public`	# `__set( integer\|string $property, integer\|string\|array\|object $value )` Enables setting of WireArray elements in object notation. Enables setting of WireArray elements in object notation. Example: $myArray->myElement = 10; Not applicable to numerically indexed arrays. Parameters `$property` `integer\|string` Key of item to set. `$value` `integer\|string\|array\|object` Value of item to set.
`public`	# `__isset( $key )` Ensures that isset() and empty() work for this classes properties. Ensures that isset() and empty() work for this classes properties.
`public`	# `__unset( $key )` Ensures that unset() works for this classes data. Ensures that unset() works for this classes data.
`public`	# `setArray( array\|WireArray $data )` Like set() but accepts an array or WireArray to set multiple values at once Like set() but accepts an array or WireArray to set multiple values at once Parameters `$data` `array\|WireArray`
`public integer\|string\|array\|object`	# `get( integer\|string $key )` Returns the value of the item at the given index, or false if not set. Returns the value of the item at the given index, or false if not set. You may also specify a selector, in which case this method will return the same result as the findOne() method. Parameters `$key` `integer\|string` Key of item to retrieve. If not specified, 0 is assumed (for first item). Returns `integer\|string\|array\|object` Value of item requested, or null if it doesn't exist.
`public Value`	# `__get( integer\|string $property )` Enables derefencing of WireArray elements in object notation. Enables derefencing of WireArray elements in object notation. Example: $myArray->myElement Not applicable to numerically indexed arrays. Fuel properties and hooked properties have precedence with this type of call. Parameters `$property` `integer\|string` Returns `Value` of requested index, or false if it doesn't exist.
`protected Wire\|null`	# `getItemThatMatches( string $key, string\|integer\|object $value )` Return the first item in this WireArray having a property called $key with the value of $value or NULL if not matched. Return the first item in this WireArray having a property called $key with the value of $value or NULL if not matched. Used internally by get() and has(). Parameters `$key` `string` Property to match. `$value` `string\|integer\|object` $value to match. Returns `Wire\|null`
`public boolean`	# `has( integer\|string $key )` Does this WireArray have the given index or match the given selector? Does this WireArray have the given index or match the given selector? If the WireArray uses numeric keys, then this will also match a wire's "name" field. Parameters `$key` `integer\|string` Key of item to check or selector. Returns `boolean` True if the item exists, false if not.
`public array`	# `getArray( )` Get a regular PHP array of all the items in this WireArray. Get a regular PHP array of all the items in this WireArray. Returns `array` Copy of the array that WireArray uses internally.
`public WireArray`	# `getAll( )` Returns all items in the WireArray. Returns all items in the WireArray. This is for syntax convenience, as it simply eturns this instance of the WireArray. Returns `WireArray`
`public array`	# `getKeys( )` Returns an array of all keys used in this WireArray. Returns an array of all keys used in this WireArray. Returns `array` Keys used in the WireArray.
`public array`	# `getValues( )` Returns an array of all values used in this WireArray. Returns an array of all values used in this WireArray. Returns `array` Values used in the WireArray.
`public integer\|string\|array\|object\|WireArray`	# `getRandom( integer $num = 1, boolean $alwaysArray = false )` Get one or more random elements from this WireArray. Get one or more random elements from this WireArray. If one item is requested, the item is returned (unless $alwaysArray is true). If multiple items are requested, a new WireArray of those items is returned. Parameters `$num` `integer` Number of items to return. Optional and defaults to 1. `$alwaysArray` `boolean` If true, then method will always return a container of items, even if it only contains 1. Returns `integer\|string\|array\|object\|WireArray` Returns value of item, or new WireArray of items if more than one requested.
`public WireArray`	# `slice( integer $start, integer $limit = 0 )` Get a slice of the WireArray. Get a slice of the WireArray. Given a starting point and a number of items, returns a new WireArray of those items. If $limit is ommitted, then it includes everything beyond the starting point. Parameters `$start` `integer` Starting index. `$limit` `integer` Number of items to include. If ommitted, includes the rest of the array. Returns `WireArray` Returns a new WireArray.
`public WireArray`	# `prepend( integer\|string\|array\|object $item )` Prepend an element to the beginning of the WireArray. Prepend an element to the beginning of the WireArray. Parameters `$item` `integer\|string\|array\|object` Item to prepend. Returns `WireArray` This instance.
`public WireArray`	# `append( integer\|string\|array\|object $item )` Append an item to the end of the WireArray. Append an item to the end of the WireArray. Parameters `$item` `integer\|string\|array\|object` Item to append. Returns `WireArray` This instance.
`public WireArray`	# `unshift( integer\|string\|array\|object $item )` Unshift an element to the beginning of the WireArray. Unshift an element to the beginning of the WireArray. Alias for prepend() Parameters `$item` `integer\|string\|array\|object` Item to prepend. Returns `WireArray` This instance.
`public integer\|string\|array\|object`	# `shift( )` Shift an element off the beginning of the WireArray. Shift an element off the beginning of the WireArray. Returns `integer\|string\|array\|object` Item shifted off the beginning.
`public WireArray`	# `push( integer\|string\|array\|object $item )` Push an item at the end of the WireArray. Push an item at the end of the WireArray. Same as add() and append(), but here for syntax convenience. Parameters `$item` `integer\|string\|array\|object` Item to push. Returns `WireArray` This instance.
`public integer\|string\|array\|object`	# `pop( )` Pop an element off the end of the WireArray. Pop an element off the end of the WireArray. Returns `integer\|string\|array\|object` Item popped off the end.
`public WireArray`	# `shuffle( )` Shuffle/randomize the WireArray. Shuffle/randomize the WireArray. Returns `WireArray` This instance.
`public WireArray`	# `index( integer $num )` Returns a WireArray of the item at the given index. Returns a WireArray of the item at the given index. Unlike get() this returns a new WireArray with a single item, or a blank WireArray if item doesn't exist. Applicable to numerically indexed ProcesArray's only. Parameters `$num` `integer` Returns `WireArray`
`public Wire\|null`	# `eq( integer $num )` Returns the item at the given index starting from 0, or NULL if it doesn't exist. Returns the item at the given index starting from 0, or NULL if it doesn't exist. Unlike the index() method, this returns an actual item and not another WireArray. Parameters `$num` `integer` Return the nth item in this WireArray. Specify a negative number to count from the end rather than the start. Returns `Wire\|null`
`public integer\|string\|array\|object`	# `first( )` Returns the first item in the WireArray or boolean FALSE if empty. Returns the first item in the WireArray or boolean FALSE if empty. Note that this resets the internal WireArray pointer, which would affect other active iterations. Returns `integer\|string\|array\|object`
`public integer\|string\|array\|object`	# `last( )` Returns the last item in the WireArray or boolean FALSE if empty. Returns the last item in the WireArray or boolean FALSE if empty. Note that this resets the internal WireArray pointer, which would affect other active iterations. Returns `integer\|string\|array\|object`
`public WireArray`	# `remove( $key )` Removes the item at the given index from the WireArray (if it exists). Removes the item at the given index from the WireArray (if it exists). Returns `WireArray` This instance.
`public`	# `removeAll( )` Removes all items from the WireArray Removes all items from the WireArray
`public WireArray`	# `sort( string $property )` Sort this WireArray by the given property. Sort this WireArray by the given property. 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. Parameters `$property` `string` Field name to sort by. Prepend or append a minus "-" to reverse the sort. Returns `WireArray` reference to current instance. TODO Currently only sorts by one field at a time. Upgrade to support a sortByField string, i.e. "name, datestamp"
`protected WireArray`	# `filterData( string\|Selectors $selectors, boolean $not = false )` Filter out Wires that don't match the selector. Filter out Wires that don't match the selector. This is applicable to and destructive to the WireArray. Parameters `$selectors` `string\|Selectors` AttributeSelector string to use as the filter. `$not` `boolean` Make this a "not" filter? (default is false) Returns `WireArray` reference to current [filtered] instance
`public WireArray`	# `filter( string $selector )` Filter out Wires that don't match the selector. Filter out Wires that don't match the selector. Same as filterData, but for public interface without the $not option. Parameters `$selector` `string` AttributeSelector string to use as the filter. Returns `WireArray` reference to current instance. See `WireArray::filterData()`
`public WireArray`	# `not( string $selector )` Filter out Wires that don't match the selector. Filter out Wires that don't match the selector. Same as filterData, but for public interface with the $not option specifically set to "true". Example: $pages->not("nonav"); // returns all pages that don't have a nonav variable set to a positive value. Parameters `$selector` `string` AttributeSelector string to use as the filter. Returns `WireArray` reference to current instance. See `WireArray::filterData()`
`public WireArray`	# `find( $selector )` Find all Wires in this WireArray that match the given selector. Find all Wires in this WireArray that match the given selector. This is non destructive and returns a brand new WireArray. $param string $selector AttributeSelector string. Returns `WireArray`
`public`	# `findOne( $selector )` Same as find, but returns a single Page rather than WireArray or FALSE if empty. Same as find, but returns a single Page rather than WireArray or FALSE if empty.
`public static boolean`	# `iterable( mixed $item )` Determines if the given item iterable as an array. Determines if the given item iterable as an array. Returns true for arrays and WireArrays. Can be called statically like this WireArray::iterable($a). Parameters `$item` `mixed` Item to check for iterability. Returns `boolean` True if item is an iterable array or WireArray (or subclass of WireArray).
`public ArrayObject`	# `getIterator( )` Allows iteration of the WireArray. Allows iteration of the WireArray. Fulfills IteratorAggregate interface. TODO return $this rather than ArrayObject ? Returns `ArrayObject` Implementation of `IteratorAggregate::getIterator`
`public integer`	# `count( )` Returns the number of items in this WireArray. Returns the number of items in this WireArray. Fulfills Countable interface. Returns `integer` Implementation of `Countable::count`
`public`	# `offsetSet( integer\|string $key, integer\|string\|array\|object $value )` Sets an index in the WireArray. Sets an index in the WireArray. For the ArrayAccess interface. Parameters `$key` `integer\|string` Key of item to set. `$value` `integer\|string\|array\|object` Value of item. Implementation of `ArrayAccess::offsetSet`
`public integer\|string\|array\|object`	# `offsetGet( integer\|string $key )` Returns the value of the item at the given index, or false if not set. Returns the value of the item at the given index, or false if not set. Parameters `$key` `integer\|string` Key of item to retrieve. Returns `integer\|string\|array\|object` Value of item requested, or false if it doesn't exist. Implementation of `ArrayAccess::offsetGet`
`public boolean`	# `offsetUnset( integer\|string $key )` Unsets the value at the given index. Unsets the value at the given index. For the ArrayAccess interface. Parameters `$key` `integer\|string` Key of the item to unset. Returns `boolean` True if item existed and was unset. False if item didn't exist. Implementation of `ArrayAccess::offsetUnset`
`public boolean`	# `offsetExists( integer\|string $key )` Determines if the given index exists in this WireArray. Determines if the given index exists in this WireArray. For the ArrayAccess interface. Parameters `$key` `integer\|string` Key of the item to check for existance. Returns `boolean` True if the item exists, false if not. Implementation of `ArrayAccess::offsetExists`
`public string`	# `__toString( )` Returns a string representation of this WireArray. Returns a string representation of this WireArray. Returns `string`
`public`	# `reverse( )` Return a reversed version of this WireArray Return a reversed version of this WireArray Non destructive
`public WireArray`	# `unique( $sortFlags = SORT_STRING )` Return a new array that is unique (no two of the same elements) Return a new array that is unique (no two of the same elements) Returns `WireArray`
`public this`	# `resetTrackChanges( boolean $trackChanges = true )` Clears out any tracked changes and turns change tracking ON or OFF Clears out any tracked changes and turns change tracking ON or OFF Parameters `$trackChanges` `boolean` True to turn change tracking ON, or false to turn OFF. Default of true is assumed. Returns `this`
`protected`	# `trackAdd( $item )` Track an item added Track an item added
`protected`	# `trackRemove( $item )` Track an item removed Track an item removed
`public array`	# `getItemsAdded( )` Return array of all keys added while trackChanges was on Return array of all keys added while trackChanges was on Returns `array`
`public array`	# `getItemsRemoved( )` Return array of all keys removed while trackChanges was on Return array of all keys removed while trackChanges was on Returns `array`
`public Wire\|null`	# `getNext( Wire $item )` Given the current item, get the next in the array Given the current item, get the next in the array Parameters `$item` `Wire` Returns `Wire\|null`
`public Wire\|null`	# `getPrev( Wire $item )` Given the current item, get the previous item in the array Given the current item, get the previous item in the array Parameters `$item` `Wire` Returns `Wire\|null`
`protected boolean`	# `usesNumericKeys( )` Does this WireArray use numeric keys only? Does this WireArray use numeric keys only? We determine this by creating a blank item and seeing what the type is of it's key. Returns `boolean`

Methods inherited from Wire
`_(), ___changed(), __call(), _n(), _x(), addHook(), addHookAfter(), addHookBefore(), addHookProperty(), className(), error(), fuel(), getAllFuel(), getChanges(), getFuel(), getHooks(), isChanged(), isHooked(), message(), removeHook(), runHooks(), setFuel(), setTrackChanges(), trackChange(), trackChanges(), untrackChange(), useFuel()`

Properties summary
`protected array`	`$data`	`array()`	# Basic type managed by the WireArray for data storage Basic type managed by the WireArray for data storage
`protected array`	`$itemsRemoved`	`array()`	# Array containing the items that have been removed from this WireArray while trackChanges is on Array containing the items that have been removed from this WireArray while trackChanges is on See getRemovedKeys()
`protected array`	`$itemsAdded`	`array()`	# Array containing the items that have been added to this WireArray while trackChanges is on Array containing the items that have been added to this WireArray while trackChanges is on See getRemovedKeys()

Properties inherited from Wire
`$changes, $defaultHookOptions, $fuel, $hookMethodCache, $localHooks, $staticHooks, $trackChanges, $useFuel`

Namespaces

Classes

Interfaces

Exceptions

Functions

Class WireArray

Direct known subclasses

Indirect known subclasses

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Returns

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Parameters

Returns

Returns

Returns

Parameters

Returns

Parameters

Returns

Returns

Returns

Returns

Parameters

Returns

TODO

Parameters

Returns

Parameters

Returns

See

Parameters

Returns

See

Returns

Parameters

Returns

Returns

Implementation of

Returns

Implementation of

Parameters

Implementation of

Parameters