How to use return in my custom function instead of echo

Question

I'm creating a function in functions.php with a custom hook, and from what I've read somewhere, it's good practice to return instead of use echo in a WordPress function? Correct me if I'm wrong.

Anyway, so with echo, my function works, but breaks everything else. With return, the function is no longer outputting anything, but nothing's broken. I tried to use this question as a reference to fix mine.

Here's what I have:

function display_collections_menu(){
/* Get WooCommerce's product categories which is custom taxonomy */
  $prod_cat_args = array(
      'taxonomy'     => 'product_cat', //woocommerce
      'orderby'      => 'name',
      'empty'        => 0
    );

    $woo_categories = get_categories( $prod_cat_args );

    $woo_menu = '';

    $woo_menu.= '<ul class="menu-collections">';

    /* For each first level category, get the image, name, and link */
    foreach ( $woo_categories as $woo_cat ) {

        if( $woo_cat->category_parent == 0 ) {
          $woo_cat_id = $woo_cat->term_id; //category ID
          $woo_img_id = get_woocommerce_term_meta( $woo_cat_id, 'thumbnail_id', true ); //category image ID
          $woo_parent_image = wp_get_attachment_url( $woo_img_id ); //category image url
          $woo_cat_slug = $woo_cat->slug; //category slug for classes
          $woo_cat_name = $woo_cat->name; //category name for link

          /* return the image/link/name */
          $orw_woo_menu.= '<li class="menu-product menu-item menu-item-object-' . $woo_cat_slug . ' ">
          <a href="' . get_term_link( $woo_cat_slug, 'product_cat' ) . '" class="menu-product-link">
          <img src="' . $woo_parent_image . '" alt=" ' . $woo_cat_name . ' " class="menu-product-thumb" />
          <p class="menu-product-name">' . $woo_cat_name . '</p></a></li>';
        } 

    }//end of $woo_categories foreach

    $woo_menu.= '</ul>';

    return $woo_menu;   
}
add_action('woo_collections_menu', 'display_collections_menu');

It'll work if instead of using return and a variable, I just echo out the values, but it breaks things. Am I using return wrong?

---

Updated with an attempt Privateer's solution - still doesn't work:

function display_collections_menu( $input = '' ){
/* Get WooCommerce's product categories which is custom taxonomy */
  $prod_cat_args = array(
      'taxonomy'     => 'product_cat', //woocommerce
      'orderby'      => 'name',
      'empty'        => 0
    );

    $woo_categories = get_categories( $prod_cat_args );

    $woo_menu = '';

    $woo_menu.= '<ul class="menu-collections">';

    /* For each first level category, get the image, name, and link */
    foreach ( $woo_categories as $woo_cat ) {

        if( $woo_cat->category_parent == 0 ) {
          $woo_cat_id = $woo_cat->term_id; //category ID
          $woo_img_id = get_woocommerce_term_meta( $woo_cat_id, 'thumbnail_id', true ); //category image ID
          $woo_parent_image = wp_get_attachment_url( $woo_img_id ); //category image url
          $woo_cat_slug = $woo_cat->slug; //category slug for classes
          $woo_cat_name = $woo_cat->name; //category name for link

          /* return the image/link/name */
          $orw_woo_menu.= '<li class="menu-product menu-item menu-item-object-' . $woo_cat_slug . ' ">
          <a href="' . get_term_link( $woo_cat_slug, 'product_cat' ) . '" class="menu-product-link">
          <img src="' . $woo_parent_image . '" alt=" ' . $woo_cat_name . ' " class="menu-product-thumb" />
          <p class="menu-product-name">' . $woo_cat_name . '</p></a></li>';
        } 

    }//end of $woo_categories foreach

    $woo_menu.= '</ul>';

    return $woo_menu;   
}
add_filter('collections_menu', 'display_collections_menu', 10, 1);
$html_block = apply_filters('collections_menu', $input_html);

And then this in a template:

<?php echo $html_block; ?>

Am I still doing this wrong?

Answer 1

If you use do_action( 'woo_collections_menu' ); in the template, then your function must echo its value. Otherwise, you are returning the data into a black hole, nothing is outputting what you're returning.

If you use a filter, then you should return the value. The point of a filter is to take a value, filter that value through a function, then do something with the result. In the context of your template, using apply_filters would be a bit strange, because your menu has no value until you construct it. So in the template it would look like:

echo apply_filters( 'collections_menu', '' );

Which is just potentially confusing and unnecessary. That empty string could be a default menu or something, but putting that in the template is probably not the wisest choice.

However, a filter would make sense within the function itself, to allow someone to change the output.

function display_collections_menu(){
    $default_menu = 'my complete menu markup here';
    return apply_filters( 'collections_menu', $default_menu );
}

Then in the template, you could just output the function directly:

echo display_collections_menu();

and someone can add their own filter to modify output if they'd like. Another helpful inclusion could be a filter on the arguments that you fetch terms with, so someone can change menu output without having to reproduce the whole function.

But going back to your original code, adding do_action( 'woo_collections_menu' ); and then echoing menu output directly in the function should also work.

Answer 2

From my understanding of actions (as opposed to filters), an action simply does something and stops processing. No return value is actually made use of.

You might change your code to be a filter by accepting an argument (say the html to append to) and then make a call like the following where you want to grab the code:

$html_block = apply_filters('woo_collections_menu', $input_html);

To do this, you might change your function definition:

function display_collections_menu( $input = '' ){
 #code here
}
add_filter('woo_collections_menu', 'display_collections_menu', 10, 1);

That would then put our output into the variable $html_block for use as you see fit.

Answer 3

I still couldn't figure out how to return $woo_menu; with my first example code, but I realized things don't break if I keep the rest of the structure as far as the variable goes and just echo once at the very end. This seems to work for me. Whether this is good practice or not, leave me a comment, but for now, this is the solution I'm using.

Thanks.

function display_collections_menu(){
/* Get WooCommerce's product categories which is custom taxonomy */
  $prod_cat_args = array(
      'taxonomy'     => 'product_cat', //woocommerce
      'orderby'      => 'name',
      'empty'        => 0
    );

    $woo_categories = get_categories( $prod_cat_args );

    $woo_menu = '';

    $woo_menu.= '<ul class="menu-collections">';

    /* For each first level category, get the image, name, and link */
    foreach ( $woo_categories as $woo_cat ) {

        if( $woo_cat->category_parent == 0 ) {
          $woo_cat_id = $woo_cat->term_id; //category ID
          $woo_img_id = get_woocommerce_term_meta( $woo_cat_id, 'thumbnail_id', true ); //category image ID
          $woo_parent_image = wp_get_attachment_url( $woo_img_id ); //category image url
          $woo_cat_slug = $woo_cat->slug; //category slug for classes
          $woo_cat_name = $woo_cat->name; //category name for link

          /* return the image/link/name */
          $orw_woo_menu.= '<li class="menu-product menu-item menu-item-object-' . $woo_cat_slug . ' ">
          <a href="' . get_term_link( $woo_cat_slug, 'product_cat' ) . '" class="menu-product-link">
          <img src="' . $woo_parent_image . '" alt=" ' . $woo_cat_name . ' " class="menu-product-thumb" />
          <p class="menu-product-name">' . $woo_cat_name . '</p></a></li>';
        } 

    }//end of $woo_categories foreach

    $woo_menu.= '</ul>';

    echo $woo_menu; //ECHO at the very end instead of return works for me  
}
add_action('woo_collections_menu', 'display_collections_menu');