home *** CD-ROM | disk | FTP | other *** search
/ Cricao de Sites - 650 Layouts Prontos / WebMasters.iso / Blogs / wordpress2.6.exe / wordpress2.6 / wp-includes / category.php < prev    next >
Encoding:
PHP Script  |  2008-06-15  |  11.1 KB  |  383 lines

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