[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/wp-includes/ -> category.php (source)

   1  <?php
   2  /**
   3   * Taxonomy API: Core category-specific functionality
   4   *
   5   * @package WordPress
   6   * @subpackage Taxonomy
   7   */
   8  
   9  /**
  10   * Retrieve list of category objects.
  11   *
  12   * If you set the 'taxonomy' argument to 'link_category', the link categories
  13   * will be returned instead.
  14   *
  15   * @since 2.1.0
  16   * @see get_terms() Type of arguments that can be changed.
  17   *
  18   * @param string|array $args {
  19   *     Optional. Arguments to retrieve categories. See get_terms() for additional options.
  20   *
  21   *     @type string $taxonomy Taxonomy to retrieve terms for. Default 'category'.
  22   * }
  23   * @return array List of category objects.
  24   */
  25  function get_categories( $args = '' ) {
  26      $defaults = array( 'taxonomy' => 'category' );
  27      $args     = wp_parse_args( $args, $defaults );
  28  
  29      /**
  30       * Filters the taxonomy used to retrieve terms when calling get_categories().
  31       *
  32       * @since 2.7.0
  33       *
  34       * @param string $taxonomy Taxonomy to retrieve terms from.
  35       * @param array  $args     An array of arguments. See get_terms().
  36       */
  37      $args['taxonomy'] = apply_filters( 'get_categories_taxonomy', $args['taxonomy'], $args );
  38  
  39      // Back compat
  40      if ( isset( $args['type'] ) && 'link' == $args['type'] ) {
  41          _deprecated_argument(
  42              __FUNCTION__,
  43              '3.0.0',
  44              sprintf(
  45                  /* translators: 1: "type => link", 2: "taxonomy => link_category" */
  46                  __( '%1$s is deprecated. Use %2$s instead.' ),
  47                  '<code>type => link</code>',
  48                  '<code>taxonomy => link_category</code>'
  49              )
  50          );
  51          $args['taxonomy'] = 'link_category';
  52      }
  53  
  54      $categories = get_terms( $args );
  55  
  56      if ( is_wp_error( $categories ) ) {
  57          $categories = array();
  58      } else {
  59          $categories = (array) $categories;
  60          foreach ( array_keys( $categories ) as $k ) {
  61              _make_cat_compat( $categories[ $k ] );
  62          }
  63      }
  64  
  65      return $categories;
  66  }
  67  
  68  /**
  69   * Retrieves category data given a category ID or category object.
  70   *
  71   * If you pass the $category parameter an object, which is assumed to be the
  72   * category row object retrieved the database. It will cache the category data.
  73   *
  74   * If you pass $category an integer of the category ID, then that category will
  75   * be retrieved from the database, if it isn't already cached, and pass it back.
  76   *
  77   * If you look at get_term(), then both types will be passed through several
  78   * filters and finally sanitized based on the $filter parameter value.
  79   *
  80   * @since 1.5.1
  81   *
  82   * @param int|object $category Category ID or Category row object
  83   * @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to a
  84   *                       WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
  85   * @param string $filter Optional. Default is raw or no WordPress defined filter will applied.
  86   * @return object|array|WP_Error|null Category data in type defined by $output parameter.
  87   *                                    WP_Error if $category is empty, null if it does not exist.
  88   */
  89  function get_category( $category, $output = OBJECT, $filter = 'raw' ) {
  90      $category = get_term( $category, 'category', $output, $filter );
  91  
  92      if ( is_wp_error( $category ) ) {
  93          return $category;
  94      }
  95  
  96      _make_cat_compat( $category );
  97  
  98      return $category;
  99  }
 100  
 101  /**
 102   * Retrieve category based on URL containing the category slug.
 103   *
 104   * Breaks the $category_path parameter up to get the category slug.
 105   *
 106   * Tries to find the child path and will return it. If it doesn't find a
 107   * match, then it will return the first category matching slug, if $full_match,
 108   * is set to false. If it does not, then it will return null.
 109   *
 110   * It is also possible that it will return a WP_Error object on failure. Check
 111   * for it when using this function.
 112   *
 113   * @since 2.1.0
 114   *
 115   * @param string $category_path URL containing category slugs.
 116   * @param bool   $full_match    Optional. Whether full path should be matched.
 117   * @param string $output        Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
 118   *                              a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
 119   * @return WP_Term|array|WP_Error|null Type is based on $output value.
 120   */
 121  function get_category_by_path( $category_path, $full_match = true, $output = OBJECT ) {
 122      $category_path  = rawurlencode( urldecode( $category_path ) );
 123      $category_path  = str_replace( '%2F', '/', $category_path );
 124      $category_path  = str_replace( '%20', ' ', $category_path );
 125      $category_paths = '/' . trim( $category_path, '/' );
 126      $leaf_path      = sanitize_title( basename( $category_paths ) );
 127      $category_paths = explode( '/', $category_paths );
 128      $full_path      = '';
 129      foreach ( (array) $category_paths as $pathdir ) {
 130          $full_path .= ( $pathdir != '' ? '/' : '' ) . sanitize_title( $pathdir );
 131      }
 132      $categories = get_terms(
 133          array(
 134              'taxonomy' => 'category',
 135              'get'      => 'all',
 136              'slug'     => $leaf_path,
 137          )
 138      );
 139  
 140      if ( empty( $categories ) ) {
 141          return;
 142      }
 143  
 144      foreach ( $categories as $category ) {
 145          $path        = '/' . $leaf_path;
 146          $curcategory = $category;
 147          while ( ( $curcategory->parent != 0 ) && ( $curcategory->parent != $curcategory->term_id ) ) {
 148              $curcategory = get_term( $curcategory->parent, 'category' );
 149              if ( is_wp_error( $curcategory ) ) {
 150                  return $curcategory;
 151              }
 152              $path = '/' . $curcategory->slug . $path;
 153          }
 154  
 155          if ( $path == $full_path ) {
 156              $category = get_term( $category->term_id, 'category', $output );
 157              _make_cat_compat( $category );
 158              return $category;
 159          }
 160      }
 161  
 162      // If full matching is not required, return the first cat that matches the leaf.
 163      if ( ! $full_match ) {
 164          $category = get_term( reset( $categories )->term_id, 'category', $output );
 165          _make_cat_compat( $category );
 166          return $category;
 167      }
 168  }
 169  
 170  /**
 171   * Retrieve category object by category slug.
 172   *
 173   * @since 2.3.0
 174   *
 175   * @param string $slug The category slug.
 176   * @return object Category data object
 177   */
 178  function get_category_by_slug( $slug ) {
 179      $category = get_term_by( 'slug', $slug, 'category' );
 180      if ( $category ) {
 181          _make_cat_compat( $category );
 182      }
 183  
 184      return $category;
 185  }
 186  
 187  /**
 188   * Retrieve the ID of a category from its name.
 189   *
 190   * @since 1.0.0
 191   *
 192   * @param string $cat_name Category name.
 193   * @return int 0, if failure and ID of category on success.
 194   */
 195  function get_cat_ID( $cat_name ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid
 196      $cat = get_term_by( 'name', $cat_name, 'category' );
 197      if ( $cat ) {
 198          return $cat->term_id;
 199      }
 200      return 0;
 201  }
 202  
 203  /**
 204   * Retrieve the name of a category from its ID.
 205   *
 206   * @since 1.0.0
 207   *
 208   * @param int $cat_id Category ID
 209   * @return string Category name, or an empty string if category doesn't exist.
 210   */
 211  function get_cat_name( $cat_id ) {
 212      $cat_id   = (int) $cat_id;
 213      $category = get_term( $cat_id, 'category' );
 214      if ( ! $category || is_wp_error( $category ) ) {
 215          return '';
 216      }
 217      return $category->name;
 218  }
 219  
 220  /**
 221   * Check if a category is an ancestor of another category.
 222   *
 223   * You can use either an id or the category object for both parameters. If you
 224   * use an integer the category will be retrieved.
 225   *
 226   * @since 2.1.0
 227   *
 228   * @param int|object $cat1 ID or object to check if this is the parent category.
 229   * @param int|object $cat2 The child category.
 230   * @return bool Whether $cat2 is child of $cat1
 231   */
 232  function cat_is_ancestor_of( $cat1, $cat2 ) {
 233      return term_is_ancestor_of( $cat1, $cat2, 'category' );
 234  }
 235  
 236  /**
 237   * Sanitizes category data based on context.
 238   *
 239   * @since 2.3.0
 240   *
 241   * @param object|array $category Category data
 242   * @param string $context Optional. Default is 'display'.
 243   * @return object|array Same type as $category with sanitized data for safe use.
 244   */
 245  function sanitize_category( $category, $context = 'display' ) {
 246      return sanitize_term( $category, 'category', $context );
 247  }
 248  
 249  /**
 250   * Sanitizes data in single category key field.
 251   *
 252   * @since 2.3.0
 253   *
 254   * @param string $field Category key to sanitize
 255   * @param mixed $value Category value to sanitize
 256   * @param int $cat_id Category ID
 257   * @param string $context What filter to use, 'raw', 'display', etc.
 258   * @return mixed Same type as $value after $value has been sanitized.
 259   */
 260  function sanitize_category_field( $field, $value, $cat_id, $context ) {
 261      return sanitize_term_field( $field, $value, $cat_id, 'category', $context );
 262  }
 263  
 264  /* Tags */
 265  
 266  /**
 267   * Retrieves all post tags.
 268   *
 269   * @since 2.3.0
 270   * @see get_terms() For list of arguments to pass.
 271   *
 272   * @param string|array $args Tag arguments to use when retrieving tags.
 273   * @return WP_Term[]|int $tags Array of 'post_tag' term objects, or a count thereof.
 274   */
 275  function get_tags( $args = '' ) {
 276      $defaults = array( 'taxonomy' => 'post_tag' );
 277      $args     = wp_parse_args( $args, $defaults );
 278  
 279      $tags = get_terms( $args );
 280  
 281      if ( empty( $tags ) ) {
 282          $return = array();
 283          return $return;
 284      }
 285  
 286      /**
 287       * Filters the array of term objects returned for the 'post_tag' taxonomy.
 288       *
 289       * @since 2.3.0
 290       *
 291       * @param WP_Term[]|int $tags Array of 'post_tag' term objects, or a count thereof.
 292       * @param array         $args An array of arguments. @see get_terms()
 293       */
 294      $tags = apply_filters( 'get_tags', $tags, $args );
 295      return $tags;
 296  }
 297  
 298  /**
 299   * Retrieve post tag by tag ID or tag object.
 300   *
 301   * If you pass the $tag parameter an object, which is assumed to be the tag row
 302   * object retrieved the database. It will cache the tag data.
 303   *
 304   * If you pass $tag an integer of the tag ID, then that tag will
 305   * be retrieved from the database, if it isn't already cached, and pass it back.
 306   *
 307   * If you look at get_term(), then both types will be passed through several
 308   * filters and finally sanitized based on the $filter parameter value.
 309   *
 310   * @since 2.3.0
 311   *
 312   * @param int|WP_Term|object $tag    A tag ID or object.
 313   * @param string             $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
 314   *                                   a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
 315   * @param string             $filter Optional. Default is raw or no WordPress defined filter will applied.
 316   * @return WP_Term|array|WP_Error|null Tag data in type defined by $output parameter. WP_Error if $tag is empty, null if it does not exist.
 317   */
 318  function get_tag( $tag, $output = OBJECT, $filter = 'raw' ) {
 319      return get_term( $tag, 'post_tag', $output, $filter );
 320  }
 321  
 322  /* Cache */
 323  
 324  /**
 325   * Remove the category cache data based on ID.
 326   *
 327   * @since 2.1.0
 328   *
 329   * @param int $id Category ID
 330   */
 331  function clean_category_cache( $id ) {
 332      clean_term_cache( $id, 'category' );
 333  }
 334  
 335  /**
 336   * Update category structure to old pre-2.3 from new taxonomy structure.
 337   *
 338   * This function was added for the taxonomy support to update the new category
 339   * structure with the old category one. This will maintain compatibility with
 340   * plugins and themes which depend on the old key or property names.
 341   *
 342   * The parameter should only be passed a variable and not create the array or
 343   * object inline to the parameter. The reason for this is that parameter is
 344   * passed by reference and PHP will fail unless it has the variable.
 345   *
 346   * There is no return value, because everything is updated on the variable you
 347   * pass to it. This is one of the features with using pass by reference in PHP.
 348   *
 349   * @since 2.3.0
 350   * @since 4.4.0 The `$category` parameter now also accepts a WP_Term object.
 351   * @access private
 352   *
 353   * @param array|object|WP_Term $category Category Row object or array
 354   */
 355  function _make_cat_compat( &$category ) {
 356      if ( is_object( $category ) && ! is_wp_error( $category ) ) {
 357          $category->cat_ID               = $category->term_id;
 358          $category->category_count       = $category->count;
 359          $category->category_description = $category->description;
 360          $category->cat_name             = $category->name;
 361          $category->category_nicename    = $category->slug;
 362          $category->category_parent      = $category->parent;
 363      } elseif ( is_array( $category ) && isset( $category['term_id'] ) ) {
 364          $category['cat_ID']               = &$category['term_id'];
 365          $category['category_count']       = &$category['count'];
 366          $category['category_description'] = &$category['description'];
 367          $category['cat_name']             = &$category['name'];
 368          $category['category_nicename']    = &$category['slug'];
 369          $category['category_parent']      = &$category['parent'];
 370      }
 371  }


Generated: Tue Jan 21 01:00:03 2020 Cross-referenced by PHPXref 0.7.1