5

In WordPress we have several objects defined through classes that are enough documented.

These are the WP_Query, WPDB, WP_Post and other.

There are other objects however that are actually created at runtime, usually converting an array to a standard object, or reading from the DB.

For instance, the taxonomy object you get from get_taxonomy() function.

Even though there isn't an actual class that defines these objects, I wonder if there is any detailed documentation of all properties we can find in these objects that doesn't require me to alway dig in the code to remember which are the properties names.

2
  • 4
    Great question. There isn't quite anything at moment, just pieces in Codex here and there. I raised the issue for new code reference, currently being developed (#233).
    – Rarst
    Nov 27 '13 at 14:23
  • Your right and I'm eager to contribute to the codex but I'm not sure if I'm ready. I found a file yesterday with many functions that had no documentation either. I may need to soak up more of the Wordpress way of doing things before I try to contribute. Going to do another 6 months plugin development then I want to document the objects that we are currently dumping.
    – Ryan Bayne
    Jan 10 '14 at 14:13
1

There is no such documentation, and I don’t expect one anytime soon. WordPress could implement specialized property objects for these cases, for get_taxonomies() it could look like this:

class WP_Taxonomy_Properties {

    private $data;

    public function __construct( Array $data ) {
        $this->data = $data;
    }

    public function get_labels() {
        return $this->data['labels'];
    }
    public function get_description() {}
    public function get_public() {}
    public function get_hierarchical() {}
    public function get_show_ui() {}
    public function get_show_in_menu() {}
    public function get_show_in_nav_menus(){}
    public function get_show_tagcloud() {}
    public function get_meta_box_cb() {}
    public function get_capabilities() {}
    public function get_rewrite() {}
    public function get_query_var() {}
    public function get_update_count_callback() {}
    public function is_builtin() {}
}

Your IDE would provide the methods per auto-complete then. No need for manual look-ups anymore.

But there are at least two reasons why this will not happen in the near future.

  1. There is little interest in implementing OOP in core code. If you find an object at all, it does too much (look at WP_Screen for an example), or it is a third-party library (SimplePie).

  2. It would require a large clean-up, because many objects are de facto hidden. An example from the class Walker_Nav_Menu; look very carefully at $args:

    /**
     * Start the element output.
     *
     * @see Walker::start_el()
     *
     * @since 3.0.0
     *
     * @param string $output Passed by reference. Used to append additional content.
     * @param object $item   Menu item data object.
     * @param int    $depth  Depth of menu item. Used for padding.
     * @param array  $args   An array of arguments. @see wp_nav_menu()
     * @param int    $id     Current item ID.
     */
    function start_el( &$output, $item, $depth = 0, $args = array(), $id = 0 ) {
        $indent = ( $depth ) ? str_repeat( "\t", $depth ) : '';
    
        $class_names = $value = '';
    
        $classes = empty( $item->classes ) ? array() : (array) $item->classes;
        $classes[] = 'menu-item-' . $item->ID;
    
        /**
         * Filter the CSS class(es) applied to a menu item's <li>.
         *
         * @since 3.0.0
         *
         * @param array  $classes The CSS classes that are applied to the menu item's <li>.
         * @param object $item    The current menu item.
         * @param array  $args    An array of arguments. @see wp_nav_menu()
         */
        $class_names = join( ' ', apply_filters( 'nav_menu_css_class', array_filter( $classes ), $item, $args ) );
        $class_names = $class_names ? ' class="' . esc_attr( $class_names ) . '"' : '';
    
        /**
         * Filter the ID applied to a menu item's <li>.
         *
         * @since 3.0.1
         *
         * @param string The ID that is applied to the menu item's <li>.
         * @param object $item The current menu item.
         * @param array $args An array of arguments. @see wp_nav_menu()
         */
        $id = apply_filters( 'nav_menu_item_id', 'menu-item-'. $item->ID, $item, $args );
        $id = $id ? ' id="' . esc_attr( $id ) . '"' : '';
    
        $output .= $indent . '<li' . $id . $value . $class_names .'>';
    
        $atts = array();
        $atts['title']  = ! empty( $item->attr_title ) ? $item->attr_title : '';
        $atts['target'] = ! empty( $item->target )     ? $item->target     : '';
        $atts['rel']    = ! empty( $item->xfn )        ? $item->xfn        : '';
        $atts['href']   = ! empty( $item->url )        ? $item->url        : '';
    
        /**
         * Filter the HTML attributes applied to a menu item's <a>.
         *
         * @since 3.6.0
         *
         * @param array $atts {
         *     The HTML attributes applied to the menu item's <a>, empty strings are ignored.
         *
         *     @type string $title  The title attribute.
         *     @type string $target The target attribute.
         *     @type string $rel    The rel attribute.
         *     @type string $href   The href attribute.
         * }
         * @param object $item The current menu item.
         * @param array  $args An array of arguments. @see wp_nav_menu()
         */
        $atts = apply_filters( 'nav_menu_link_attributes', $atts, $item, $args );
    
        $attributes = '';
        foreach ( $atts as $attr => $value ) {
            if ( ! empty( $value ) ) {
                $value = ( 'href' === $attr ) ? esc_url( $value ) : esc_attr( $value );
                $attributes .= ' ' . $attr . '="' . $value . '"';
            }
        }
    
        $item_output = $args->before;
        $item_output .= '<a'. $attributes .'>';
        /** This filter is documented in wp-includes/post-template.php */
        $item_output .= $args->link_before . apply_filters( 'the_title', $item->title, $item->ID ) . $args->link_after;
        $item_output .= '</a>';
        $item_output .= $args->after;
    
        /**
         * Filter a menu item's starting output.
         *
         * The menu item's starting output only includes $args->before, the opening <a>,
         * the menu item's title, the closing </a>, and $args->after. Currently, there is
         * no filter for modifying the opening and closing <li> for a menu item.
         *
         * @since 3.0.0
         *
         * @param string $item_output The menu item's starting HTML output.
         * @param object $item        Menu item data object.
         * @param int    $depth       Depth of menu item. Used for padding.
         * @param array  $args        An array of arguments. @see wp_nav_menu()
         */
        $output .= apply_filters( 'walker_nav_menu_start_el', $item_output, $item, $depth, $args );
    }
    

$args is not an array, it is one of those sloppy objects, created with type casting in the function wp_nav_menu(): $args = (object) $args;.

Now what? You cannot change the signatures in Walker_Nav_Menu, because that is a child class of Walker (one of the many reasons why inheritance is bad concept). Changing the child class signatures would raise E_STRICT notices. You cannot just pass an array, because that would break many third-party walkers. When you introduce new objects, you have to fix the classes that are using them at first. And there are probably many cases like this one.

1
  • The taxonomy object wouldn't need all these specialized properties. It would be enough to create the class, add the fields names and put some php doc in there. As for the menu walker, no need to change the signature: I would never expect that. The php doc it's enough in this case. At least for the IDE I'm using (phpStorm by the way), it would be enough to have a good php doc and classes with at least fields. By the way is not for the autocomplete that I'd like to have these classes documented (though it helps), but simply to have a place where to look for properties or anything else. Jan 19 '14 at 10:39

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.