WordPress.org
Get WordPress

Make WordPress Core

Changeset 38928


Ignore:
Timestamp:
10/25/2016 09:25:25 PM (8 years ago)
Author:
ocean90
Message:

General: Introduce a wp_list_sort() helper function, v2.

In addition to wp_list_filter() for filtering a list of objects, and wp_list_pluck() for plucking a certain field out of each object in a list, this new function can be used for sorting a list of objects by specific fields. These functions are now all contained within the new WP_List_Util() class and wp_list_sort() is used in various parts of core for sorting lists.

This was previously committed in [38859] but got reverted in [38862] and [38863]. To fix the previous issues, wp_list_sort() supports now an additional argument to preserve array keys via uasort().

Props flixos90, DrewAPicture, jorbin.
Fixes #37128.

Location:
trunk
Files:
2 added
10 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/category-template.php

    r38863 r38928  
    9898     */
    9999    return apply_filters( 'get_the_categories', $categories, $id );
    100 }
    101 
    102 /**
    103  * Sort categories by name.
    104  *
    105  * Used by usort() as a callback, should not be used directly. Can actually be
    106  * used to sort any term object.
    107  *
    108  * @since 2.3.0
    109  * @access private
    110  *
    111  * @param object $a
    112  * @param object $b
    113  * @return int
    114  */
    115 function _usort_terms_by_name( $a, $b ) {
    116     return strcmp( $a->name, $b->name );
    117 }
    118 
    119 /**
    120  * Sort categories by ID.
    121  *
    122  * Used by usort() as a callback, should not be used directly. Can actually be
    123  * used to sort any term object.
    124  *
    125  * @since 2.3.0
    126  * @access private
    127  *
    128  * @param object $a
    129  * @param object $b
    130  * @return int
    131  */
    132 function _usort_terms_by_ID( $a, $b ) {
    133     if ( $a->term_id > $b->term_id )
    134         return 1;
    135     elseif ( $a->term_id < $b->term_id )
    136         return -1;
    137     else
    138         return 0;
    139100}
    140101

  • trunk/src/wp-includes/class-wp-customize-manager.php

    r38906 r38928  
    25062506     *
    25072507     * @since 3.4.0
     2508     * @deprecated 4.7.0 Use wp_list_sort()
    25082509     *
    25092510     * @param WP_Customize_Panel|WP_Customize_Section|WP_Customize_Control $a Object A.
    … …  
    25122513     */
    25132514    protected function _cmp_priority( $a, $b ) {
     2515        _deprecated_function( __METHOD__, '4.7.0', 'wp_list_sort' );
     2516
    25142517        if ( $a->priority === $b->priority ) {
    25152518            return $a->instance_number - $b->instance_number;
    … …  
    25312534
    25322535        $controls = array();
    2533         uasort( $this->controls, array( $this, '_cmp_priority' ) );
     2536        $this->controls = wp_list_sort( $this->controls, array(
     2537            'priority'        => 'ASC',
     2538            'instance_number' => 'ASC',
     2539        ), 'ASC', true );
    25342540
    25352541        foreach ( $this->controls as $id => $control ) {
    … …  
    25442550
    25452551        // Prepare sections.
    2546         uasort( $this->sections, array( $this, '_cmp_priority' ) );
     2552        $this->sections = wp_list_sort( $this->sections, array(
     2553            'priority'        => 'ASC',
     2554            'instance_number' => 'ASC',
     2555        ), 'ASC', true );
    25472556        $sections = array();
    25482557
    … …  
    25522561            }
    25532562
    2554             usort( $section->controls, array( $this, '_cmp_priority' ) );
     2563
     2564            $section->controls = wp_list_sort( $section->controls, array(
     2565                'priority'        => 'ASC',
     2566                'instance_number' => 'ASC',
     2567            ) );
    25552568
    25562569            if ( ! $section->panel ) {
    … …  
    25672580
    25682581        // Prepare panels.
    2569         uasort( $this->panels, array( $this, '_cmp_priority' ) );
     2582        $this->panels = wp_list_sort( $this->panels, array(
     2583            'priority'        => 'ASC',
     2584            'instance_number' => 'ASC',
     2585        ), 'ASC', true );
    25702586        $panels = array();
    25712587
    … …  
    25752591            }
    25762592
    2577             uasort( $panel->sections, array( $this, '_cmp_priority' ) );
     2593            $panel->sections = wp_list_sort( $panel->sections, array(
     2594                'priority'        => 'ASC',
     2595                'instance_number' => 'ASC',
     2596            ), 'ASC', true );
    25782597            $panels[ $panel->id ] = $panel;
    25792598        }
    … …  
    25822601        // Sort panels and top-level sections together.
    25832602        $this->containers = array_merge( $this->panels, $this->sections );
    2584         uasort( $this->containers, array( $this, '_cmp_priority' ) );
     2603        $this->containers = wp_list_sort( $this->containers, array(
     2604            'priority'        => 'ASC',
     2605            'instance_number' => 'ASC',
     2606        ), 'ASC', true );
    25852607    }
    25862608

  • trunk/src/wp-includes/customize/class-wp-customize-nav-menu-item-setting.php

    r38863 r38928  
    533533
    534534        if ( ARRAY_A === $args['output'] ) {
    535             $GLOBALS['_menu_item_sort_prop'] = $args['output_key'];
    536             usort( $items, '_sort_nav_menu_items' );
     535            $items = wp_list_sort( $items, array(
     536                $args['output_key'] => 'ASC',
     537            ) );
    537538            $i = 1;
    538539

  • trunk/src/wp-includes/customize/class-wp-customize-nav-menu-setting.php

    r38863 r38928  
    288288        // Make sure the menu objects get re-sorted after an update/insert.
    289289        if ( ! $is_delete && ! empty( $args['orderby'] ) ) {
    290             $this->_current_menus_sort_orderby = $args['orderby'];
    291             usort( $menus, array( $this, '_sort_menus_by_orderby' ) );
     290            $menus = wp_list_sort( $menus, array(
     291                $args['orderby'] => 'ASC',
     292            ) );
    292293        }
    293294        // @todo add support for $args['hide_empty'] === true
    … …  
    314315     *
    315316     * @since 4.3.0
     317     * @deprecated 4.7.0 Use wp_list_sort()
    316318     * @access protected
     319     *
    317320     * @param object $menu1
    318321     * @param object $menu2
    … …  
    322325     */
    323326    protected function _sort_menus_by_orderby( $menu1, $menu2 ) {
     327        _deprecated_function( __METHOD__, '4.7.0', 'wp_list_sort' );
     328
    324329        $key = $this->_current_menus_sort_orderby;
    325330        return strcmp( $menu1->$key, $menu2->$key );

  • trunk/src/wp-includes/deprecated.php

    r38863 r38928  
    37993799    return preg_replace( '%&\s*\{[^}]*(\}\s*;?|$)%', '', $string );
    38003800}
     3801
     3802/**
     3803 * Sort categories by ID.
     3804 *
     3805 * Used by usort() as a callback, should not be used directly. Can actually be
     3806 * used to sort any term object.
     3807 *
     3808 * @since 2.3.0
     3809 * @deprecated 4.7.0 Use wp_list_sort()
     3810 * @access private
     3811 *
     3812 * @param object $a
     3813 * @param object $b
     3814 * @return int
     3815 */
     3816function _usort_terms_by_ID( $a, $b ) {
     3817    _deprecated_function( __FUNCTION__, '4.7.0', 'wp_list_sort' );
     3818
     3819    if ( $a->term_id > $b->term_id )
     3820        return 1;
     3821    elseif ( $a->term_id < $b->term_id )
     3822        return -1;
     3823    else
     3824        return 0;
     3825}
     3826
     3827/**
     3828 * Sort categories by name.
     3829 *
     3830 * Used by usort() as a callback, should not be used directly. Can actually be
     3831 * used to sort any term object.
     3832 *
     3833 * @since 2.3.0
     3834 * @deprecated 4.7.0 Use wp_list_sort()
     3835 * @access private
     3836 *
     3837 * @param object $a
     3838 * @param object $b
     3839 * @return int
     3840 */
     3841function _usort_terms_by_name( $a, $b ) {
     3842    _deprecated_function( __FUNCTION__, '4.7.0', 'wp_list_sort' );
     3843
     3844    return strcmp( $a->name, $b->name );
     3845}
     3846
     3847/**
     3848 * Sort menu items by the desired key.
     3849 *
     3850 * @since 3.0.0
     3851 * @deprecated 4.7.0 Use wp_list_sort()
     3852 * @access private
     3853 *
     3854 * @global string $_menu_item_sort_prop
     3855 *
     3856 * @param object $a The first object to compare
     3857 * @param object $b The second object to compare
     3858 * @return int -1, 0, or 1 if $a is considered to be respectively less than, equal to, or greater than $b.
     3859 */
     3860function _sort_nav_menu_items( $a, $b ) {
     3861    global $_menu_item_sort_prop;
     3862
     3863    _deprecated_function( __FUNCTION__, '4.7.0', 'wp_list_sort' );
     3864
     3865    if ( empty( $_menu_item_sort_prop ) )
     3866        return 0;
     3867
     3868    if ( ! isset( $a->$_menu_item_sort_prop ) || ! isset( $b->$_menu_item_sort_prop ) )
     3869        return 0;
     3870
     3871    $_a = (int) $a->$_menu_item_sort_prop;
     3872    $_b = (int) $b->$_menu_item_sort_prop;
     3873
     3874    if ( $a->$_menu_item_sort_prop == $b->$_menu_item_sort_prop )
     3875        return 0;
     3876    elseif ( $_a == $a->$_menu_item_sort_prop && $_b == $b->$_menu_item_sort_prop )
     3877        return $_a < $_b ? -1 : 1;
     3878    else
     3879        return strcmp( $a->$_menu_item_sort_prop, $b->$_menu_item_sort_prop );
     3880}

  • trunk/src/wp-includes/functions.php

    r38884 r38928  
    34903490 *
    34913491 * @since 3.0.0
     3492 * @since 4.7.0 Uses WP_List_Util class.
    34923493 *
    34933494 * @param array       $list     An array of objects to filter
    … …  
    35033504 */
    35043505function wp_filter_object_list( $list, $args = array(), $operator = 'and', $field = false ) {
    3505     if ( ! is_array( $list ) )
     3506    if ( ! is_array( $list ) ) {
    35063507        return array();
    3507 
    3508     $list = wp_list_filter( $list, $args, $operator );
    3509 
    3510     if ( $field )
    3511         $list = wp_list_pluck( $list, $field );
    3512 
    3513     return $list;
     3508    }
     3509
     3510    $util = new WP_List_Util( $list );
     3511
     3512    $util->filter( $args, $operator );
     3513
     3514    if ( $field ) {
     3515        $util->pluck( $field );
     3516    }
     3517
     3518    return $util->get_output();
    35143519}
    35153520
    … …  
    35183523 *
    35193524 * @since 3.1.0
     3525 * @since 4.7.0 Uses WP_List_Util class.
    35203526 *
    35213527 * @param array  $list     An array of objects to filter.
    … …  
    35293535 */
    35303536function wp_list_filter( $list, $args = array(), $operator = 'AND' ) {
    3531     if ( ! is_array( $list ) )
     3537    if ( ! is_array( $list ) ) {
    35323538        return array();
    3533 
    3534     if ( empty( $args ) )
    3535         return $list;
    3536 
    3537     $operator = strtoupper( $operator );
    3538     $count = count( $args );
    3539     $filtered = array();
    3540 
    3541     foreach ( $list as $key => $obj ) {
    3542         $to_match = (array) $obj;
    3543 
    3544         $matched = 0;
    3545         foreach ( $args as $m_key => $m_value ) {
    3546             if ( array_key_exists( $m_key, $to_match ) && $m_value == $to_match[ $m_key ] )
    3547                 $matched++;
    3548         }
    3549 
    3550         if ( ( 'AND' == $operator && $matched == $count )
    3551           || ( 'OR' == $operator && $matched > 0 )
    3552           || ( 'NOT' == $operator && 0 == $matched ) ) {
    3553             $filtered[$key] = $obj;
    3554         }
    3555     }
    3556 
    3557     return $filtered;
     3539    }
     3540
     3541    $util = new WP_List_Util( $list );
     3542    return $util->filter( $args, $operator );
    35583543}
    35593544
    … …  
    35663551 * @since 3.1.0
    35673552 * @since 4.0.0 $index_key parameter added.
     3553 * @since 4.7.0 Uses WP_List_Util class.
    35683554 *
    35693555 * @param array      $list      List of objects or arrays
    … …  
    35763562 */
    35773563function wp_list_pluck( $list, $field, $index_key = null ) {
    3578     if ( ! $index_key ) {
    3579         /*
    3580          * This is simple. Could at some point wrap array_column()
    3581          * if we knew we had an array of arrays.
    3582          */
    3583         foreach ( $list as $key => $value ) {
    3584             if ( is_object( $value ) ) {
    3585                 $list[ $key ] = $value->$field;
    3586             } else {
    3587                 $list[ $key ] = $value[ $field ];
    3588             }
    3589         }
    3590         return $list;
    3591     }
    3592 
    3593     /*
    3594      * When index_key is not set for a particular item, push the value
    3595      * to the end of the stack. This is how array_column() behaves.
    3596      */
    3597     $newlist = array();
    3598     foreach ( $list as $value ) {
    3599         if ( is_object( $value ) ) {
    3600             if ( isset( $value->$index_key ) ) {
    3601                 $newlist[ $value->$index_key ] = $value->$field;
    3602             } else {
    3603                 $newlist[] = $value->$field;
    3604             }
    3605         } else {
    3606             if ( isset( $value[ $index_key ] ) ) {
    3607                 $newlist[ $value[ $index_key ] ] = $value[ $field ];
    3608             } else {
    3609                 $newlist[] = $value[ $field ];
    3610             }
    3611         }
    3612     }
    3613 
    3614     return $newlist;
     3564    $util = new WP_List_Util( $list );
     3565    return $util->pluck( $field, $index_key );
     3566}
     3567
     3568/**
     3569 * Sorts a list of objects, based on one or more orderby arguments.
     3570 *
     3571 * @since 4.7.0
     3572 *
     3573 * @param array        $list          An array of objects to filter.
     3574 * @param string|array $orderby       Optional. Either the field name to order by or an array
     3575 *                                    of multiple orderby fields as $orderby => $order.
     3576 * @param string       $order         Optional. Either 'ASC' or 'DESC'. Only used if $orderby
     3577 *                                    is a string.
     3578 * @param bool         $preserve_keys Optional. Whether to preserve keys. Default false.
     3579 * @return array The sorted array.
     3580 */
     3581function wp_list_sort( $list, $orderby = array(), $order = 'ASC', $preserve_keys = false ) {
     3582    if ( ! is_array( $list ) ) {
     3583        return array();
     3584    }
     3585
     3586    $util = new WP_List_Util( $list );
     3587    return $util->sort( $orderby, $order, $preserve_keys );
    36153588}
    36163589

  • trunk/src/wp-includes/link-template.php

    r38863 r38928  
    170170            $cats = get_the_category($post->ID);
    171171            if ( $cats ) {
    172                 usort($cats, '_usort_terms_by_ID'); // order by ID
     172                $cats = wp_list_sort( $cats, array(
     173                    'term_id' => 'ASC',
     174                ) );
    173175
    174176                /**

  • trunk/src/wp-includes/nav-menu.php

    r38863 r38928  
    559559
    560560/**
    561  * Sort menu items by the desired key.
    562  *
    563  * @since 3.0.0
    564  * @access private
    565  *
    566  * @global string $_menu_item_sort_prop
    567  *
    568  * @param object $a The first object to compare
    569  * @param object $b The second object to compare
    570  * @return int -1, 0, or 1 if $a is considered to be respectively less than, equal to, or greater than $b.
    571  */
    572 function _sort_nav_menu_items( $a, $b ) {
    573     global $_menu_item_sort_prop;
    574 
    575     if ( empty( $_menu_item_sort_prop ) )
    576         return 0;
    577 
    578     if ( ! isset( $a->$_menu_item_sort_prop ) || ! isset( $b->$_menu_item_sort_prop ) )
    579         return 0;
    580 
    581     $_a = (int) $a->$_menu_item_sort_prop;
    582     $_b = (int) $b->$_menu_item_sort_prop;
    583 
    584     if ( $a->$_menu_item_sort_prop == $b->$_menu_item_sort_prop )
    585         return 0;
    586     elseif ( $_a == $a->$_menu_item_sort_prop && $_b == $b->$_menu_item_sort_prop )
    587         return $_a < $_b ? -1 : 1;
    588     else
    589         return strcmp( $a->$_menu_item_sort_prop, $b->$_menu_item_sort_prop );
    590 }
    591 
    592 /**
    593561 * Return if a menu item is valid.
    594562 *
    … …  
    683651
    684652    if ( ARRAY_A == $args['output'] ) {
    685         $GLOBALS['_menu_item_sort_prop'] = $args['output_key'];
    686         usort($items, '_sort_nav_menu_items');
     653        $items = wp_list_sort( $items, array(
     654            $args['output_key'] => 'ASC',
     655        ) );
    687656        $i = 1;
    688657        foreach ( $items as $k => $item ) {
    … …  
    777746                $menu_item->type_label = __( 'Post Type Archive' );
    778747                $post_content = wp_trim_words( $menu_item->post_content, 200 );
    779                 $post_type_description = '' == $post_content ? $post_type_description : $post_content; 
     748                $post_type_description = '' == $post_content ? $post_type_description : $post_content;
    780749                $menu_item->url = get_post_type_archive_link( $menu_item->object );
    781750            } elseif ( 'taxonomy' == $menu_item->type ) {

  • trunk/src/wp-settings.php

    r38899 r38928  
    9090// Load early WordPress files.
    9191require( ABSPATH . WPINC . '/compat.php' );
     92require( ABSPATH . WPINC . '/class-wp-list-util.php' );
    9293require( ABSPATH . WPINC . '/functions.php' );
    9394require( ABSPATH . WPINC . '/class-wp-matchesmapregex.php' );

  • trunk/tests/phpunit/tests/customize/manager.php

    r38858 r38928  
    18631863        return $this->filtered_device_list();
    18641864    }
     1865
     1866    /**
     1867     * @ticket 37128
     1868     */
     1869    function test_prepare_controls_wp_list_sort_controls() {
     1870        wp_set_current_user( self::$admin_user_id );
     1871
     1872        $controls = array( 'foo' => 2, 'bar' => 4, 'foobar' => 3, 'key' => 1 );
     1873        $controls_sorted = array( 'key', 'foo', 'foobar', 'bar' );
     1874
     1875        $this->manager->add_section( 'foosection', array() );
     1876
     1877        foreach ( $controls as $control_id => $priority ) {
     1878            $this->manager->add_setting( $control_id );
     1879            $this->manager->add_control( $control_id, array(
     1880                'priority' => $priority,
     1881                'section'  => 'foosection',
     1882            ) );
     1883        }
     1884
     1885        $this->manager->prepare_controls();
     1886
     1887        $result = $this->manager->controls();
     1888        $this->assertEquals( $controls_sorted, array_keys( $result ) );
     1889    }
     1890
     1891    /**
     1892     * @ticket 37128
     1893     */
     1894    function test_prepare_controls_wp_list_sort_sections() {
     1895        wp_set_current_user( self::$admin_user_id );
     1896
     1897        $sections = array( 'foo' => 2, 'bar' => 4, 'foobar' => 3, 'key' => 1 );
     1898        $sections_sorted = array( 'key', 'foo', 'foobar', 'bar' );
     1899
     1900        foreach ( $sections as $section_id => $priority ) {
     1901            $this->manager->add_section( $section_id, array(
     1902                'priority' => $priority,
     1903            ) );
     1904        }
     1905
     1906        $this->manager->prepare_controls();
     1907
     1908        $result = $this->manager->sections();
     1909        $this->assertEquals( $sections_sorted, array_keys( $result ) );
     1910    }
     1911
     1912    /**
     1913     * @ticket 37128
     1914     */
     1915    function test_prepare_controls_wp_list_sort_panels() {
     1916        wp_set_current_user( self::$admin_user_id );
     1917
     1918        $panels = array( 'foo' => 2, 'bar' => 4, 'foobar' => 3, 'key' => 1 );
     1919        $panels_sorted = array( 'key', 'foo', 'foobar', 'bar' );
     1920
     1921        foreach ( $panels as $panel_id => $priority ) {
     1922            $this->manager->add_panel( $panel_id, array(
     1923                'priority' => $priority,
     1924            ) );
     1925        }
     1926
     1927        $this->manager->prepare_controls();
     1928
     1929        $result = $this->manager->panels();
     1930        $this->assertEquals( $panels_sorted, array_keys( $result ) );
     1931    }
    18651932}
    18661933
Note: See TracChangeset for help on using the changeset viewer.