mirror of
https://github.com/WordPress/WordPress.git
synced 2024-09-06 20:58:21 +02:00
Prior to about 2013, many class methods lacked even access modifiers which made the `@access` notations that much more useful. Now that we've gotten to a point where the codebase is more mature from a maintenance perspective and we can finally remove these notations. Notable exceptions to this change include standalone functions notated as private as well as some classes still considered to represent "private" APIs. See #41452. Built from https://develop.svn.wordpress.org/trunk@41162 git-svn-id: http://core.svn.wordpress.org/trunk@41002 1a063a9b-81f0-0310-95a4-ce76da25c4cd
262 lines
6.2 KiB
PHP
262 lines
6.2 KiB
PHP
<?php
|
|
/**
|
|
* WordPress List utility class
|
|
*
|
|
* @package WordPress
|
|
* @since 4.7.0
|
|
*/
|
|
|
|
/**
|
|
* List utility.
|
|
*
|
|
* Utility class to handle operations on an array of objects.
|
|
*
|
|
* @since 4.7.0
|
|
*/
|
|
class WP_List_Util {
|
|
/**
|
|
* The input array.
|
|
*
|
|
* @since 4.7.0
|
|
* @var array
|
|
*/
|
|
private $input = array();
|
|
|
|
/**
|
|
* The output array.
|
|
*
|
|
* @since 4.7.0
|
|
* @var array
|
|
*/
|
|
private $output = array();
|
|
|
|
/**
|
|
* Temporary arguments for sorting.
|
|
*
|
|
* @since 4.7.0
|
|
* @var array
|
|
*/
|
|
private $orderby = array();
|
|
|
|
/**
|
|
* Constructor.
|
|
*
|
|
* Sets the input array.
|
|
*
|
|
* @since 4.7.0
|
|
*
|
|
* @param array $input Array to perform operations on.
|
|
*/
|
|
public function __construct( $input ) {
|
|
$this->output = $this->input = $input;
|
|
}
|
|
|
|
/**
|
|
* Returns the original input array.
|
|
*
|
|
* @since 4.7.0
|
|
*
|
|
* @return array The input array.
|
|
*/
|
|
public function get_input() {
|
|
return $this->input;
|
|
}
|
|
|
|
/**
|
|
* Returns the output array.
|
|
*
|
|
* @since 4.7.0
|
|
*
|
|
* @return array The output array.
|
|
*/
|
|
public function get_output() {
|
|
return $this->output;
|
|
}
|
|
|
|
/**
|
|
* Filters the list, based on a set of key => value arguments.
|
|
*
|
|
* @since 4.7.0
|
|
*
|
|
* @param array $args Optional. An array of key => value arguments to match
|
|
* against each object. Default empty array.
|
|
* @param string $operator Optional. The logical operation to perform. 'AND' means
|
|
* all elements from the array must match. 'OR' means only
|
|
* one element needs to match. 'NOT' means no elements may
|
|
* match. Default 'AND'.
|
|
* @return array Array of found values.
|
|
*/
|
|
public function filter( $args = array(), $operator = 'AND' ) {
|
|
if ( empty( $args ) ) {
|
|
return $this->output;
|
|
}
|
|
|
|
$operator = strtoupper( $operator );
|
|
|
|
if ( ! in_array( $operator, array( 'AND', 'OR', 'NOT' ), true ) ) {
|
|
return array();
|
|
}
|
|
|
|
$count = count( $args );
|
|
$filtered = array();
|
|
|
|
foreach ( $this->output as $key => $obj ) {
|
|
$to_match = (array) $obj;
|
|
|
|
$matched = 0;
|
|
foreach ( $args as $m_key => $m_value ) {
|
|
if ( array_key_exists( $m_key, $to_match ) && $m_value == $to_match[ $m_key ] ) {
|
|
$matched++;
|
|
}
|
|
}
|
|
|
|
if (
|
|
( 'AND' == $operator && $matched == $count ) ||
|
|
( 'OR' == $operator && $matched > 0 ) ||
|
|
( 'NOT' == $operator && 0 == $matched )
|
|
) {
|
|
$filtered[$key] = $obj;
|
|
}
|
|
}
|
|
|
|
$this->output = $filtered;
|
|
|
|
return $this->output;
|
|
}
|
|
|
|
/**
|
|
* Plucks a certain field out of each object in the list.
|
|
*
|
|
* This has the same functionality and prototype of
|
|
* array_column() (PHP 5.5) but also supports objects.
|
|
*
|
|
* @since 4.7.0
|
|
*
|
|
* @param int|string $field Field from the object to place instead of the entire object
|
|
* @param int|string $index_key Optional. Field from the object to use as keys for the new array.
|
|
* Default null.
|
|
* @return array Array of found values. If `$index_key` is set, an array of found values with keys
|
|
* corresponding to `$index_key`. If `$index_key` is null, array keys from the original
|
|
* `$list` will be preserved in the results.
|
|
*/
|
|
public function pluck( $field, $index_key = null ) {
|
|
if ( ! $index_key ) {
|
|
/*
|
|
* This is simple. Could at some point wrap array_column()
|
|
* if we knew we had an array of arrays.
|
|
*/
|
|
foreach ( $this->output as $key => $value ) {
|
|
if ( is_object( $value ) ) {
|
|
$this->output[ $key ] = $value->$field;
|
|
} else {
|
|
$this->output[ $key ] = $value[ $field ];
|
|
}
|
|
}
|
|
return $this->output;
|
|
}
|
|
|
|
/*
|
|
* When index_key is not set for a particular item, push the value
|
|
* to the end of the stack. This is how array_column() behaves.
|
|
*/
|
|
$newlist = array();
|
|
foreach ( $this->output as $value ) {
|
|
if ( is_object( $value ) ) {
|
|
if ( isset( $value->$index_key ) ) {
|
|
$newlist[ $value->$index_key ] = $value->$field;
|
|
} else {
|
|
$newlist[] = $value->$field;
|
|
}
|
|
} else {
|
|
if ( isset( $value[ $index_key ] ) ) {
|
|
$newlist[ $value[ $index_key ] ] = $value[ $field ];
|
|
} else {
|
|
$newlist[] = $value[ $field ];
|
|
}
|
|
}
|
|
}
|
|
|
|
$this->output = $newlist;
|
|
|
|
return $this->output;
|
|
}
|
|
|
|
/**
|
|
* Sorts the list, based on one or more orderby arguments.
|
|
*
|
|
* @since 4.7.0
|
|
*
|
|
* @param string|array $orderby Optional. Either the field name to order by or an array
|
|
* of multiple orderby fields as $orderby => $order.
|
|
* @param string $order Optional. Either 'ASC' or 'DESC'. Only used if $orderby
|
|
* is a string.
|
|
* @param bool $preserve_keys Optional. Whether to preserve keys. Default false.
|
|
* @return array The sorted array.
|
|
*/
|
|
public function sort( $orderby = array(), $order = 'ASC', $preserve_keys = false ) {
|
|
if ( empty( $orderby ) ) {
|
|
return $this->output;
|
|
}
|
|
|
|
if ( is_string( $orderby ) ) {
|
|
$orderby = array( $orderby => $order );
|
|
}
|
|
|
|
foreach ( $orderby as $field => $direction ) {
|
|
$orderby[ $field ] = 'DESC' === strtoupper( $direction ) ? 'DESC' : 'ASC';
|
|
}
|
|
|
|
$this->orderby = $orderby;
|
|
|
|
if ( $preserve_keys ) {
|
|
uasort( $this->output, array( $this, 'sort_callback' ) );
|
|
} else {
|
|
usort( $this->output, array( $this, 'sort_callback' ) );
|
|
}
|
|
|
|
$this->orderby = array();
|
|
|
|
return $this->output;
|
|
}
|
|
|
|
/**
|
|
* Callback to sort the list by specific fields.
|
|
*
|
|
* @since 4.7.0
|
|
*
|
|
* @see WP_List_Util::sort()
|
|
*
|
|
* @param object|array $a One object to compare.
|
|
* @param object|array $b The other object to compare.
|
|
* @return int 0 if both objects equal. -1 if second object should come first, 1 otherwise.
|
|
*/
|
|
private function sort_callback( $a, $b ) {
|
|
if ( empty( $this->orderby ) ) {
|
|
return 0;
|
|
}
|
|
|
|
$a = (array) $a;
|
|
$b = (array) $b;
|
|
|
|
foreach ( $this->orderby as $field => $direction ) {
|
|
if ( ! isset( $a[ $field ] ) || ! isset( $b[ $field ] ) ) {
|
|
continue;
|
|
}
|
|
|
|
if ( $a[ $field ] == $b[ $field ] ) {
|
|
continue;
|
|
}
|
|
|
|
$results = 'DESC' === $direction ? array( 1, -1 ) : array( -1, 1 );
|
|
|
|
if ( is_numeric( $a[ $field ] ) && is_numeric( $b[ $field ] ) ) {
|
|
return ( $a[ $field ] < $b[ $field ] ) ? $results[0] : $results[1];
|
|
}
|
|
|
|
return 0 > strcmp( $a[ $field ], $b[ $field ] ) ? $results[0] : $results[1];
|
|
}
|
|
|
|
return 0;
|
|
}
|
|
}
|