[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/ -> class-wp-list-util.php (source)

   1  <?php
   2  /**
   3   * WordPress List utility class
   4   *
   5   * @package WordPress
   6   * @since 4.7.0
   7   */
   8  
   9  /**
  10   * List utility.
  11   *
  12   * Utility class to handle operations on an array of objects or arrays.
  13   *
  14   * @since 4.7.0
  15   */
  16  #[AllowDynamicProperties]
  17  class WP_List_Util {
  18      /**
  19       * The input array.
  20       *
  21       * @since 4.7.0
  22       * @var array
  23       */
  24      private $input = array();
  25  
  26      /**
  27       * The output array.
  28       *
  29       * @since 4.7.0
  30       * @var array
  31       */
  32      private $output = array();
  33  
  34      /**
  35       * Temporary arguments for sorting.
  36       *
  37       * @since 4.7.0
  38       * @var string[]
  39       */
  40      private $orderby = array();
  41  
  42      /**
  43       * Constructor.
  44       *
  45       * Sets the input array.
  46       *
  47       * @since 4.7.0
  48       *
  49       * @param array $input Array to perform operations on.
  50       */
  51  	public function __construct( $input ) {
  52          $this->output = $input;
  53          $this->input  = $input;
  54      }
  55  
  56      /**
  57       * Returns the original input array.
  58       *
  59       * @since 4.7.0
  60       *
  61       * @return array The input array.
  62       */
  63  	public function get_input() {
  64          return $this->input;
  65      }
  66  
  67      /**
  68       * Returns the output array.
  69       *
  70       * @since 4.7.0
  71       *
  72       * @return array The output array.
  73       */
  74  	public function get_output() {
  75          return $this->output;
  76      }
  77  
  78      /**
  79       * Filters the list, based on a set of key => value arguments.
  80       *
  81       * Retrieves the objects from the list that match the given arguments.
  82       * Key represents property name, and value represents property value.
  83       *
  84       * If an object has more properties than those specified in arguments,
  85       * that will not disqualify it. When using the 'and' operator,
  86       * any missing properties will disqualify it.
  87       *
  88       * @since 4.7.0
  89       *
  90       * @param array  $args     Optional. An array of key => value arguments to match
  91       *                         against each object. Default empty array.
  92       * @param string $operator Optional. The logical operation to perform. 'and' means
  93       *                         all elements from the array must match. 'or' means only
  94       *                         one element needs to match. 'not' means no elements may
  95       *                         match. The value is case-insensitive. Default 'and'.
  96       * @return array Array of found values.
  97       *
  98       * @phpstan-param 'and'|'AND'|'or'|'OR'|'not'|'NOT' $operator
  99       */
 100  	public function filter( $args = array(), $operator = 'and' ) {
 101          if ( empty( $args ) ) {
 102              return $this->output;
 103          }
 104  
 105          $operator = strtoupper( $operator );
 106  
 107          if ( ! in_array( $operator, array( 'AND', 'OR', 'NOT' ), true ) ) {
 108              $this->output = array();
 109              return $this->output;
 110          }
 111  
 112          $count    = count( $args );
 113          $filtered = array();
 114  
 115          foreach ( $this->output as $key => $obj ) {
 116              $matched = 0;
 117  
 118              foreach ( $args as $m_key => $m_value ) {
 119                  if ( is_array( $obj ) ) {
 120                      // Treat object as an array.
 121                      if ( array_key_exists( $m_key, $obj ) && ( $m_value == $obj[ $m_key ] ) ) {
 122                          ++$matched;
 123                      }
 124                  } elseif ( is_object( $obj ) ) {
 125                      // Treat object as an object.
 126                      if ( isset( $obj->{$m_key} ) && ( $m_value == $obj->{$m_key} ) ) {
 127                          ++$matched;
 128                      }
 129                  }
 130              }
 131  
 132              if ( ( 'AND' === $operator && $matched === $count )
 133                  || ( 'OR' === $operator && $matched > 0 )
 134                  || ( 'NOT' === $operator && 0 === $matched )
 135              ) {
 136                  $filtered[ $key ] = $obj;
 137              }
 138          }
 139  
 140          $this->output = $filtered;
 141  
 142          return $this->output;
 143      }
 144  
 145      /**
 146       * Plucks a certain field out of each element in the input array.
 147       *
 148       * This has the same functionality and prototype of
 149       * array_column() (PHP 5.5) but also supports objects.
 150       *
 151       * @since 4.7.0
 152       *
 153       * @param int|string $field     Field to fetch from the object or array.
 154       * @param int|string $index_key Optional. Field from the element to use as keys for the new array.
 155       *                              Default null.
 156       * @return array Array of found values. If `$index_key` is set, an array of found values with keys
 157       *               corresponding to `$index_key`. If `$index_key` is null, array keys from the original
 158       *               `$list` will be preserved in the results.
 159       */
 160  	public function pluck( $field, $index_key = null ) {
 161          $newlist = array();
 162  
 163          if ( ! $index_key ) {
 164              /*
 165               * This is simple. Could at some point wrap array_column()
 166               * if we knew we had an array of arrays.
 167               */
 168              foreach ( $this->output as $key => $value ) {
 169                  if ( is_object( $value ) ) {
 170                      $newlist[ $key ] = $value->$field;
 171                  } elseif ( is_array( $value ) ) {
 172                      $newlist[ $key ] = $value[ $field ];
 173                  } else {
 174                      _doing_it_wrong(
 175                          __METHOD__,
 176                          __( 'Values for the input array must be either objects or arrays.' ),
 177                          '6.2.0'
 178                      );
 179                  }
 180              }
 181  
 182              $this->output = $newlist;
 183  
 184              return $this->output;
 185          }
 186  
 187          /*
 188           * When index_key is not set for a particular item, push the value
 189           * to the end of the stack. This is how array_column() behaves.
 190           */
 191          foreach ( $this->output as $value ) {
 192              if ( is_object( $value ) ) {
 193                  if ( isset( $value->$index_key ) ) {
 194                      $newlist[ $value->$index_key ] = $value->$field;
 195                  } else {
 196                      $newlist[] = $value->$field;
 197                  }
 198              } elseif ( is_array( $value ) ) {
 199                  if ( isset( $value[ $index_key ] ) ) {
 200                      $newlist[ $value[ $index_key ] ] = $value[ $field ];
 201                  } else {
 202                      $newlist[] = $value[ $field ];
 203                  }
 204              } else {
 205                  _doing_it_wrong(
 206                      __METHOD__,
 207                      __( 'Values for the input array must be either objects or arrays.' ),
 208                      '6.2.0'
 209                  );
 210              }
 211          }
 212  
 213          $this->output = $newlist;
 214  
 215          return $this->output;
 216      }
 217  
 218      /**
 219       * Sorts the input array based on one or more orderby arguments.
 220       *
 221       * @since 4.7.0
 222       *
 223       * @param string|array $orderby       Optional. Either the field name to order by or an array
 224       *                                    of multiple orderby fields as `$orderby => $order`.
 225       *                                    Default empty array.
 226       * @param string       $order         Optional. Either 'ASC' or 'DESC'. Only used if `$orderby`
 227       *                                    is a string. Default 'ASC'.
 228       * @param bool         $preserve_keys Optional. Whether to preserve keys. Default false.
 229       * @return array The sorted array.
 230       */
 231  	public function sort( $orderby = array(), $order = 'ASC', $preserve_keys = false ) {
 232          if ( empty( $orderby ) ) {
 233              return $this->output;
 234          }
 235  
 236          if ( is_string( $orderby ) ) {
 237              $orderby = array( $orderby => $order );
 238          }
 239  
 240          foreach ( $orderby as $field => $direction ) {
 241              $orderby[ $field ] = 'DESC' === strtoupper( $direction ) ? 'DESC' : 'ASC';
 242          }
 243  
 244          $this->orderby = $orderby;
 245  
 246          if ( $preserve_keys ) {
 247              uasort( $this->output, array( $this, 'sort_callback' ) );
 248          } else {
 249              usort( $this->output, array( $this, 'sort_callback' ) );
 250          }
 251  
 252          $this->orderby = array();
 253  
 254          return $this->output;
 255      }
 256  
 257      /**
 258       * Callback to sort an array by specific fields.
 259       *
 260       * @since 4.7.0
 261       *
 262       * @see WP_List_Util::sort()
 263       *
 264       * @param object|array $a One object to compare.
 265       * @param object|array $b The other object to compare.
 266       * @return int 0 if both objects equal. -1 if second object should come first, 1 otherwise.
 267       */
 268  	private function sort_callback( $a, $b ) {
 269          if ( empty( $this->orderby ) ) {
 270              return 0;
 271          }
 272  
 273          $a = (array) $a;
 274          $b = (array) $b;
 275  
 276          foreach ( $this->orderby as $field => $direction ) {
 277              if ( ! isset( $a[ $field ] ) || ! isset( $b[ $field ] ) ) {
 278                  continue;
 279              }
 280  
 281              if ( $a[ $field ] == $b[ $field ] ) {
 282                  continue;
 283              }
 284  
 285              $results = 'DESC' === $direction ? array( 1, -1 ) : array( -1, 1 );
 286  
 287              if ( is_numeric( $a[ $field ] ) && is_numeric( $b[ $field ] ) ) {
 288                  return ( $a[ $field ] < $b[ $field ] ) ? $results[0] : $results[1];
 289              }
 290  
 291              return 0 > strcmp( $a[ $field ], $b[ $field ] ) ? $results[0] : $results[1];
 292          }
 293  
 294          return 0;
 295      }
 296  }


Generated : Tue Nov 17 08:20:01 2026 Cross-referenced by PHPXref