WordPress objects class reference

Question

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.

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).

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.

Related Posts:

Leave a Comment Cancel reply