what is the difference between get_header_image() and header_image() in wordpress

Question

in the process of self learning from the official wordpress theme developement handbook
this page shows how to create headers and two different functions were used:

• get_header_image()
• header_image()

both return a string, which is the image URL.
is this just another confusing redundency ? or is there an actual difference between the two.

Answer 1

Semantic

dis·play

Make a prominent exhibition of (something) in a place where it can be easily seen.

the palace used to display a series of Flemish tapestries.

re·trieve

get or bring (something) back; regain possession of.

I was sent to retrieve the balls from his garden

---

How

While header_image() will echo out the header image URL, get_header_image() will not.

<?php

header_image();

get_header_image();

header_image() is a wrapper for get_header_image(). Mainly used on the front-end, the role is to escape and echo out get_header_image().

<?php

/**
 * Displays header image URL.
 *
 * @link https://developer.wordpress.org/reference/functions/header_image/
 */
function header_image() {
    $image = get_header_image();
 
    if ( $image ) {
        echo esc_url( $image );
    }
}

A practical use case of get_header_image() would be inside a function.

WordPress use that get_ ... distinction for most of it's default functions, eg:

• get_the_title() and the_title().
• get_the_post_thumbnail() and the_post_thumbnail().
• get_the_content() and the_content(). ... etc.

Answer 2

I found the answer.
Someone posted it then deleted it quickly, but just for the sake of benefiting everyone who is looking for an answer:
header_image() will echo the URL without the need of using the php echo. While get_header_image() will also return the image URL but it doesn't echo it. You have to use the php echo for it.
NB: this isn't mentioned in the official documentation, unless am blind I challenge anyone to show me where it says echo in the official page, or where this distinction is explained.