From 0458d919c08dfbb791204d037bed1b12a4312a94 Mon Sep 17 00:00:00 2001 From: ryan Date: Fri, 17 Aug 2007 21:22:37 +0000 Subject: [PATCH] First cut of taxonomy API phpdoc from darkdragon. see #4742 git-svn-id: http://svn.automattic.com/wordpress/trunk@5896 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/bookmark.php | 77 ++++++++++++++++++- wp-includes/taxonomy.php | 157 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 233 insertions(+), 1 deletion(-) diff --git a/wp-includes/bookmark.php b/wp-includes/bookmark.php index d04cad3b5..a6e5fccfa 100644 --- a/wp-includes/bookmark.php +++ b/wp-includes/bookmark.php @@ -1,12 +1,14 @@ get_row("SELECT * FROM $wpdb->links WHERE link_id = '$bookmark_id'"); $link->link_category = wp_get_link_cats($bookmark_id); + $link = sanitize_bookmark($link, $filter); + if ( $output == OBJECT ) { return $link; } elseif ( $output == ARRAY_A ) { @@ -142,6 +144,79 @@ function get_bookmarks($args = '') { return apply_filters('get_bookmarks', $results, $r); } +function sanitize_bookmark($bookmark, $context = 'display') { + $fields = array('link_id', 'link_url', 'link_name', 'link_image', 'link_target', 'link_category', + 'link_description', 'link_visible', 'link_owner', 'link_rating', 'link_updated', + 'link_rel', 'link_', 'link_notes', 'link_rss', ); + + $do_object = false; + if ( is_object($bookmark) ) + $do_object = true; + + foreach ( $fields as $field ) { + if ( $do_object ) + $bookmark->$field = sanitize_bookmark_field($field, $bookmark->$field, $bookmark->link_id, $context); + else + $bookmark[$field] = sanitize_bookmark_field($field, $bookmark[$field], $bookmark['link_id'], $context); + } + + return $bookmark; +} + +function sanitize_bookmark_field($field, $value, $bookmark_id, $context) { + $int_fields = array('ID', 'bookmark_parent', 'menu_order'); + if ( in_array($field, $int_fields) ) + $value = (int) $value; + + if ( 'raw' == $context ) + return $value; + + $prefixed = false; + if ( false !== strpos($field, 'bookmark_') ) { + $prefixed = true; + $field_no_prefix = str_replace('bookmark_', '', $field); + } + + if ( 'edit' == $context ) { + $format_to_edit = array('bookmark_content', 'bookmark_excerpt', 'bookmark_title', 'bookmark_password'); + + if ( $prefixed ) { + $value = apply_filters("edit_$field", $value, $bookmark_id); + // Old school + $value = apply_filters("${field_no_prefix}_edit_pre", $value, $bookmark_id); + } else { + $value = apply_filters("edit_bookmark_$field", $value, $bookmark_id); + } + + if ( in_array($field, $format_to_edit) ) { + if ( 'bookmark_content' == $field ) + $value = format_to_edit($value, user_can_richedit()); + else + $value = format_to_edit($value); + } else { + $value = attribute_escape($value); + } + } else if ( 'db' == $context ) { + if ( $prefixed ) { + $value = apply_filters("pre_$field", $value); + $value = apply_filters("${field_no_prefix}_save_pre", $value); + } else { + $value = apply_filters("pre_bookmark_$field", $value); + $value = apply_filters("${field}_pre", $value); + } + } else { + // Use display filters by default. + $value = apply_filters("bookmark_$field", $value, $bookmark_id, $context); + } + + if ( 'attribute' == $context ) + $value = attribute_escape($value); + else if ( 'js' == $context ) + $value = js_escape($value); + + return $value; +} + function delete_get_bookmark_cache() { wp_cache_delete( 'get_bookmarks', 'bookmark' ); } diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index 7ef74e9f0..07805d7bd 100644 --- a/wp-includes/taxonomy.php +++ b/wp-includes/taxonomy.php @@ -4,11 +4,36 @@ // Taxonomy Registration // +/** + * @global array $wp_taxonomies Fill me out please + */ $wp_taxonomies = array(); $wp_taxonomies['category'] = (object) array('name' => 'category', 'object_type' => 'post', 'hierarchical' => true, 'update_count_callback' => '_update_post_term_count'); $wp_taxonomies['post_tag'] = (object) array('name' => 'post_tag', 'object_type' => 'post', 'hierarchical' => false, 'update_count_callback' => '_update_post_term_count'); $wp_taxonomies['link_category'] = (object) array('name' => 'link_category', 'object_type' => 'link', 'hierarchical' => false); +/** + * get_object_taxonomies() - Appears to return all of the names that are of $object_type + * + * It appears that this function can be used to find all of the names inside of + * $wp_taxonomies global variable. + * + * @example + * + * Should result in 
Array(
+ *      'category',
+ *      'post_tag'
+ *      )
+ * + * @package Taxonomy + * @global array $wp_taxonomies + * @param string $object_type Name of the type of taxonomy object + * @return array The names of all within the object_type. + * + * @internal + * This won't appear but just a note to say that this is all conjecture and parts or whole + * might be inaccurate or wrong. + */ function get_object_taxonomies($object_type) { global $wp_taxonomies; @@ -21,6 +46,21 @@ function get_object_taxonomies($object_type) { return $taxonomies; } +/** + * get_taxonomy() - Returns the "taxonomy" object of $taxonomy. + * + * The get_taxonomy function will first check that the parameter string given + * is a taxonomy object and if it is, it will return it. + * + * @package Taxonomy + * @global array $wp_taxonomies + * @param string $taxonomy Name of taxonomy object to return + * @return object The Taxonomy Object + * + * @internal + * This won't appear but just a note to say that this is all conjecture and parts or whole + * might be inaccurate or wrong. + */ function get_taxonomy( $taxonomy ) { global $wp_taxonomies; @@ -30,12 +70,39 @@ function get_taxonomy( $taxonomy ) { return $wp_taxonomies[$taxonomy]; } +/** + * is_taxonomy() - Checks that the taxonomy name exists + * + * @package Taxonomy + * @global array $wp_taxonomies + * @param string $taxonomy Name of taxonomy object + * @return bool Whether the taxonomy exists or not. + * + * @internal + * This won't appear but just a note to say that this is all conjecture and parts or whole + * might be inaccurate or wrong. + */ function is_taxonomy( $taxonomy ) { global $wp_taxonomies; return isset($wp_taxonomies[$taxonomy]); } +/** + * is_taxonomy_hierarchical() - Whether the taxonomy object is hierarchical + * + * Checks to make sure that the taxonomy is an object first. Then Gets the object, and finally + * returns the hierarchical value in the object. + * + * @package Taxonomy + * @global array $wp_taxonomies + * @param string $taxonomy Name of taxonomy object + * @return bool Whether the taxonomy is hierarchical + * + * @internal + * This won't appear but just a note to say that this is all conjecture and parts or whole + * might be inaccurate or wrong. + */ function is_taxonomy_hierarchical($taxonomy) { if ( ! is_taxonomy($taxonomy) ) return false; @@ -44,6 +111,33 @@ function is_taxonomy_hierarchical($taxonomy) { return $taxonomy->hierarchical; } +/** + * register_taxonomy() - Create or modify a taxonomy object. + * + * A simple function for creating or modifying a taxonomy object based on the parameters given. + * The function will accept an array (third optional parameter), along with strings for the + * taxonomy name and another string for the object type. + * + * The function keeps a default set, allowing for the $args to be optional but allow the other + * functions to still work. It is possible to overwrite the default set, which contains two + * keys: hierarchical and update_count_callback. + * + * hierarachical has some defined purpose at other parts of the API, but is bool value. + * + * update_count_callback works much like a hook, in that it will be called (or something from + * somewhere). + * + * @package Taxonomy + * @global array $wp_taxonomies + * @param string $taxonomy Name of taxonomy object + * @param string $object_type Name of the object type for the taxonomy object. + * @param array $args See above description for the two keys values. + * @return null Nothing is returned, so expect error maybe or use is_taxonomy() to check. + * + * @internal + * This won't appear but just a note to say that this is all conjecture and parts or whole + * might be inaccurate or wrong. + */ function register_taxonomy( $taxonomy, $object_type, $args = array() ) { global $wp_taxonomies; @@ -59,6 +153,34 @@ function register_taxonomy( $taxonomy, $object_type, $args = array() ) { // Term API // +/** + * get_objects_in_term() - Return object_ids of valid taxonomy and term + * + * The strings of $taxonomies must exist before this function will continue. On failure of finding + * a valid taxonomy, it will return an WP_Error class, kind of like Exceptions in PHP 5, except you + * can't catch them. Even so, you can still test for the WP_Error class and get the error message. + * + * The $terms aren't checked the same as $taxonomies, but still need to exist for $object_ids to + * be returned. + * + * It is possible to change the order that object_ids is returned by either using PHP sort family + * functions or using the database by using $args with either ASC or DESC array. The value should + * be in the key named 'order'. + * + * @package Taxonomy + * @subpackage Term + * @global object $wpdb Database Query + * @param string|array $terms String of term or array of string values of terms that will be used + * @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names + * @param array $args Change the order of the object_ids, either ASC or DESC + * @return object WP_Error - A PHP 4 compatible Exception class prototype + * @return array Empty array if there are no $object_ids + * @return array Array of $object_ids + * + * @internal + * This won't appear but just a note to say that this is all conjecture and parts or whole + * might be inaccurate or wrong. + */ function get_objects_in_term( $terms, $taxonomies, $args = array() ) { global $wpdb; @@ -90,6 +212,23 @@ function get_objects_in_term( $terms, $taxonomies, $args = array() ) { return $object_ids; } +/** + * get_term() - + * + * + * + * @package Taxonomy + * @subpackage Term + * @global object $wpdb Database Query + * @param int|object $term + * @param string $taxonomy + * @param string $output Either OBJECT, ARRAY_A, or ARRAY_N + * @return mixed Term Row from database + * + * @internal + * This won't appear but just a note to say that this is all conjecture and parts or whole + * might be inaccurate or wrong. + */ function &get_term(&$term, $taxonomy, $output = OBJECT) { global $wpdb; @@ -124,6 +263,24 @@ function &get_term(&$term, $taxonomy, $output = OBJECT) { } } +/** + * get_term_by() - + * + * + * + * @package Taxonomy + * @subpackage Term + * @global object $wpdb Database Query + * @param string $field + * @param string $value + * @param string $taxonomy + * @param string $output Either OBJECT, ARRAY_A, or ARRAY_N + * @return mixed Term Row from database + * + * @internal + * This won't appear but just a note to say that this is all conjecture and parts or whole + * might be inaccurate or wrong. + */ function get_term_by($field, $value, $taxonomy, $output = OBJECT) { global $wpdb;