WOOF_Collection

Extends WOOF_Wrap

Methods

Represents a collection of other objects, supporting foreach iteration via PHP’s Iterator interface, and many other features such as sorting. The MasterPress API makes heavy use of collections, which offer far more power than basic arrays.

Example: A few ways (of the many) to obtain a collection.

List of Methods

Property Methods

  • contains( String $prop, Mixed $value )Boolean

    Checks if the collection contains the specified value for the specified property. .

  • count()Integer

    Retrieves the number of items in the collection.

  • csv( String $prop )String

    A preset of the WOOF_Collection::flatten method to generate a comma separated values list of the values in the given property.

  • eq( Integer $index )Mixed OR WOOF_Silent

    Retrieves the item at the specified index.

  • extract( String $name, Arguments $args = array(), String $remove_call_args = separator,prefix,suffix )Array

    Extracts a given property from each item in the collection into an array of property values. .

  • find_by( String $prop, Mixed $val )Mixed OR Boolean

    Finds the first item in the collection for a given property and value.

  • find_by_in( String $prop, Array / String $vals )WOOF_Collection

    Finds all items in the collection for a given property and one or more values.

  • first( Integer $count = 1 )Mixed OR WOOF_Collection OR WOOF_Silent

    Retrieve the first item in the collection, a collection of the first $count items in the collection, or an object for silent failure if the collection contains no items.

  • flatten( String $name, Arguments $args = array(), String $remove_call_args = separator,prefix,suffix )String

    Flattens the collection to a string made up of a given single property value from each separated by a given separator. .

  • i( Integer $index )Mixed OR WOOF_Silent

    A synonym for the WOOF_Collection::eq method, to retrieve the item at the specified index.

  • index_of( Mixed $value, String $prop = "id" )Integer

    Returns the index of the given item, searching each object in the collection for a given value from the specified property  .

  • is_empty()Boolean

    Checks if this collection is empty, that is, contains no items.

  • item( Integer $index )Mixed OR WOOF_Silent

    A synonym for the WOOF_Collection::eq method, to retrieve the item at the specified index.

  • items( Integer $index = null )Mixed OR Array OR WOOF_Silent

    A dual purpose method to either return an array of all of the items in the collection, or return an item at the specified index (essentially forwards on to the WOOF_Collection::eq method).

  • last( Integer $count = 1 )Mixed OR WOOF_Collection OR WOOF_Silent

    Retrieve the final item in the collection, a collection of the final $count items in the collection, or an object for silent failure if the collection contains no items.

  • number( Integer $index )Mixed OR WOOF_Silent

    A normalised version of the WOOF_Collection::eq method to return an item from the collection at a specific index, while assuming that all access is 1-based – that is, index 1 is the first element, not 0. This method also supports negative indexes, which will retrieve the nth-item backwards from the end of the collection (so -1 is the final item, -2 is the second last item, and so on).The name of this method “number” is intended to make code using it more readable, since it makes sense to refer to, say, the second item as item “number 2”.

  • range( Integer $from, Integer $to = null )WOOF_Collection

    Returns a collection representing a slice of the field set items in the collection starting at the from index supplied, and ending at the to index supplied.Note: the from and to indexes are zero-based. .

  • tag_wrap( String $tag = li, String $name, Arguments $attr = array() )String

    Wraps a given property from each of the items in the collection in the specified HTML tag with the given attributes.

Manipulation

Theming

  • count_text( String $zero, String $one, String $many )String

    Formats the count of items in the collection based on string templates for the cases of one item, many items, or zero items.

Sorting

Searching

  • find_by( String $prop, Mixed $val )Mixed OR Boolean

    Finds the first item in the collection for a given property and value.

  • index_of( Mixed $value, String $prop = "id" )Integer

    Returns the index of the given item, searching each object in the collection for a given value from the specified property  .

Utility

  • cls( Integer $i, Arguments $args = array() )String

    An alias for the WOOF_Collection::item method to add ‘class=”first”‘ or ‘class=”last”‘ (or other classes as specified in $args) to HTML tags as you loop through the collection, without needing to track this yourself.

  • item_class( Integer $i, Arguments $args = array() )String

    A useful method to add ‘class=”first”‘ or ‘class=”last”‘ (or other classes as specified in $args) to HTML tags as you loop through the collection, without needing to track this yourself.

PHP Interface Method

  • current()Mixed

    Implements the PHP iterator interface’s current method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • key()Integer

    Implements the PHP iterator interface’s key method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • next()

    Implements the PHP iterator interface’s next method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • offsetExists( Integer $offset )Boolean

    Implements the offsetExists method from PHP’s ArrayAccess interface, to allow the isset function to be called on a numeric array access on this collection (see example). Note: this method is not intended to be called directly.

  • offsetGet( Integer $offset )Mixed

    Implements the offsetGet method from PHP’s ArrayAccess interface, to allow a direct numeric array access on this collection (see example).

  • offsetSet( Integer $offset )

    Implements the offsetSet method from PHP’s ArrayAccess interface, to allow an item at a specific index to be set via numeric array access on this collection (see example). Note: this method is not intended to be called directly.

  • offsetUnset( $offset )

    Implements the offsetUnset method from PHP’s ArrayAccess interface, to allow the unset function to be called on a numeric array access on this collection (see example). Note: this method is not intended to be called directly.

  • rewind()

    Implements the PHP iterator interface’s rewind method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • valid()Boolean

    Implements the PHP iterator interface’s valid method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

Internal Use

  • current()Mixed

    Implements the PHP iterator interface’s current method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • init_items()Array

    An internal method that primes the items in the collection based on calling the iterator_items method, if the items are not already available.

  • key()Integer

    Implements the PHP iterator interface’s key method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • next()

    Implements the PHP iterator interface’s next method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • offsetExists( Integer $offset )Boolean

    Implements the offsetExists method from PHP’s ArrayAccess interface, to allow the isset function to be called on a numeric array access on this collection (see example). Note: this method is not intended to be called directly.

  • offsetGet( Integer $offset )Mixed

    Implements the offsetGet method from PHP’s ArrayAccess interface, to allow a direct numeric array access on this collection (see example).

  • offsetSet( Integer $offset )

    Implements the offsetSet method from PHP’s ArrayAccess interface, to allow an item at a specific index to be set via numeric array access on this collection (see example). Note: this method is not intended to be called directly.

  • offsetUnset( $offset )

    Implements the offsetUnset method from PHP’s ArrayAccess interface, to allow the unset function to be called on a numeric array access on this collection (see example). Note: this method is not intended to be called directly.

  • rewind()

    Implements the PHP iterator interface’s rewind method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • valid()Boolean

    Implements the PHP iterator interface’s valid method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • append( Mixed $var )

    Appends one or more elements to the end of the collection, via the PHP function array_push.

  • by( String $name, String $order = "ASC", Boolean $case_insensitive = true, Boolean $clone = false, String $numeric = "AUTO" )WOOF_Collection

    A synonym for the WOOF_Collection::sort method, to sort the collection by the value of a property specified. A “property” here can be a genuine object property, or the result of a method call as handled by the WOOF_Wrap::get method. .

  • by_number( String $name, String $order = "ASC", Boolean $case_insensitive = false, Boolean $clone = false )WOOF_Collection

    A synonym for the WOOF_Collection::sort method, to sort the collection by the value of a property specified, preset to a forced numeric sort. A “property” here can be a genuine object property, or the result of a method call as handled by the WOOF_Wrap::get method. .

  • cls( Integer $i, Arguments $args = array() )String

    An alias for the WOOF_Collection::item method to add ‘class=”first”‘ or ‘class=”last”‘ (or other classes as specified in $args) to HTML tags as you loop through the collection, without needing to track this yourself.

  • contains( String $prop, Mixed $value )Boolean

    Checks if the collection contains the specified value for the specified property. .

  • count()Integer

    Retrieves the number of items in the collection.

  • count_text( String $zero, String $one, String $many )String

    Formats the count of items in the collection based on string templates for the cases of one item, many items, or zero items.

  • csv( String $prop )String

    A preset of the WOOF_Collection::flatten method to generate a comma separated values list of the values in the given property.

  • current()Mixed

    Implements the PHP iterator interface’s current method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • dedupe( String $by = id )WOOF_Collection

    Removes duplicates from the collection as identified by the specified property, that is, two objects are considered duplicate if the property value on each of those objects is the same.

  • eq( Integer $index )Mixed OR WOOF_Silent

    Retrieves the item at the specified index.

  • extract( String $name, Arguments $args = array(), String $remove_call_args = separator,prefix,suffix )Array

    Extracts a given property from each item in the collection into an array of property values. .

  • find_by( String $prop, Mixed $val )Mixed OR Boolean

    Finds the first item in the collection for a given property and value.

  • find_by_in( String $prop, Array / String $vals )WOOF_Collection

    Finds all items in the collection for a given property and one or more values.

  • first( Integer $count = 1 )Mixed OR WOOF_Collection OR WOOF_Silent

    Retrieve the first item in the collection, a collection of the first $count items in the collection, or an object for silent failure if the collection contains no items.

  • flatten( String $name, Arguments $args = array(), String $remove_call_args = separator,prefix,suffix )String

    Flattens the collection to a string made up of a given single property value from each separated by a given separator. .

  • i( Integer $index )Mixed OR WOOF_Silent

    A synonym for the WOOF_Collection::eq method, to retrieve the item at the specified index.

  • index_of( Mixed $value, String $prop = "id" )Integer

    Returns the index of the given item, searching each object in the collection for a given value from the specified property  .

  • init_items()Array

    An internal method that primes the items in the collection based on calling the iterator_items method, if the items are not already available.

  • is_empty()Boolean

    Checks if this collection is empty, that is, contains no items.

  • item( Integer $index )Mixed OR WOOF_Silent

    A synonym for the WOOF_Collection::eq method, to retrieve the item at the specified index.

  • item_class( Integer $i, Arguments $args = array() )String

    A useful method to add ‘class=”first”‘ or ‘class=”last”‘ (or other classes as specified in $args) to HTML tags as you loop through the collection, without needing to track this yourself.

  • items( Integer $index = null )Mixed OR Array OR WOOF_Silent

    A dual purpose method to either return an array of all of the items in the collection, or return an item at the specified index (essentially forwards on to the WOOF_Collection::eq method).

  • key()Integer

    Implements the PHP iterator interface’s key method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • last( Integer $count = 1 )Mixed OR WOOF_Collection OR WOOF_Silent

    Retrieve the final item in the collection, a collection of the final $count items in the collection, or an object for silent failure if the collection contains no items.

  • merge( WOOF_Collection $array )

    Merges another collection or array into this collection, using PHP’s array_merge function. .

  • next()

    Implements the PHP iterator interface’s next method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • number( Integer $index )Mixed OR WOOF_Silent

    A normalised version of the WOOF_Collection::eq method to return an item from the collection at a specific index, while assuming that all access is 1-based – that is, index 1 is the first element, not 0. This method also supports negative indexes, which will retrieve the nth-item backwards from the end of the collection (so -1 is the final item, -2 is the second last item, and so on).The name of this method “number” is intended to make code using it more readable, since it makes sense to refer to, say, the second item as item “number 2”.

  • offsetExists( Integer $offset )Boolean

    Implements the offsetExists method from PHP’s ArrayAccess interface, to allow the isset function to be called on a numeric array access on this collection (see example). Note: this method is not intended to be called directly.

  • offsetGet( Integer $offset )Mixed

    Implements the offsetGet method from PHP’s ArrayAccess interface, to allow a direct numeric array access on this collection (see example).

  • offsetSet( Integer $offset )

    Implements the offsetSet method from PHP’s ArrayAccess interface, to allow an item at a specific index to be set via numeric array access on this collection (see example). Note: this method is not intended to be called directly.

  • offsetUnset( $offset )

    Implements the offsetUnset method from PHP’s ArrayAccess interface, to allow the unset function to be called on a numeric array access on this collection (see example). Note: this method is not intended to be called directly.

  • orderby( $name, String $order = "ASC", Boolean $case_insensitive = false, Mixed $numeric = "AUTO" )WOOF_Collection

    Returns a collection of the items in the collection sorted by the values for the given property.

  • prepend( Mixed $var )WOOF_Collection

    Prepends one or more elements to the start of the collection, via the PHP function array_unshift.

  • push( Mixed $var )

    A synonym for the WOOF_Collection::append method, which appends one or more elements to the end of the collection, via the PHP function array_push.

  • range( Integer $from, Integer $to = null )WOOF_Collection

    Returns a collection representing a slice of the field set items in the collection starting at the from index supplied, and ending at the to index supplied.Note: the from and to indexes are zero-based. .

  • reverse( Boolean $clone = true )WOOF_Collection

    Reverses the items in the collection.

  • rewind()

    Implements the PHP iterator interface’s rewind method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

  • sort( String $name, String $order = "ASC", Boolean $case_insensitive = true, Boolean $clone = false, Mixed $numeric = "AUTO" )WOOF_Collection

    Returns a collection of the items in the collection sorted by the values for the given property. A “property” here can be a genuine object property, or the result of a method call as handled by the WOOF_Wrap::get method. .

  • sort_to( String $field, Array $values, String $order = ASC, Boolean $clone = false )WOOF_Collection

    Returns a collection of the items in this collection sorted by the given field in the order of a supplied values map.

  • tag_wrap( String $tag = li, String $name, Arguments $attr = array() )String

    Wraps a given property from each of the items in the collection in the specified HTML tag with the given attributes.

  • unshift( Mixed $var )WOOF_Collection

    A synonym for the WOOF_Collection::prepend method, to prepend one or more elements to the start of the collection, via the PHP function array_unshift.

  • valid()Boolean

    Implements the PHP iterator interface’s valid method, to facilitate iteration over the collection.Note: this method is not intended to be called directly.

Base Class Methods

View method list from the base class WOOF_Wrap.

Latest From the Blog

MasterPress 1.1.4 now available

MasterPress 1.1.4 is now available. This release contains an important compatibility fix for WordPress 4.5 to allow correct detection of the taxonomy term editing screen. Without this fix, any custom fields you have attached to custom taxonomies will not be shown at all in the editing form. Note also that MasterPress will still detect the edit screen correctly in… 

Plugin Requirements

MasterPress requires a minimum of WordPress version 3.4, MySQL 5, and PHP version 5.2.4.

We also recommend that PHP is configured to use a memory limit of 64MB per request (128MB may be required for sites with higher complexity).

This plug-in is not compatible with the WordPress.com hosted service.

Traversal