Deprecate `get_permalink()`

[ericmann]

With the exception of get_permalink(), all in-loop template tags follow a simple pattern:

• the_author -> get_the_author
• the_content -> get_the_content
• the_title -> get_the_title

It's easy for developers to keep remember that the_{something} will echo a value while get_the_{something} will return it.

For the sake of consistency, get_permalink() should be deprecated and replaced with get_the_permalink().

[ericmann]

Initial patch

[johnpbloch]

+1

[itsananderson]

For what it's worth, get_permalink can be called outside the loop by passing a post ID, making the addition of "_the_" somewhat ambiguous.

get_permalink( $foo->ID ); // Implies that we're getting the permalink for $foo
get_the_permalink( $foo->ID ); // Here "_the_" is kinda misleading. Using $foo, not $post

Now, what if we made a new get_the_permalink, defined as:

function get_the_permalink() {
    global $post;
    return get_permalink( $post->ID );
}

I could see a similar argument for also doing this with other template tags. Have "get_the_title" call a "get_title" function, etc. This is, however, probably outside the scope of this ticket.

[nacin]

get_permalink() is used in probably the vast majority of themes and plugins, and is one of the most well-known functions. I'm not sure deprecating it is worth the standardization.

[aniketpant]

The idea is interesting as standardization is always a great thing, but there must be thousands of themes and plugins which use the function.

Deprecating get_premalink() is not even really a big move towards standardization.

[ethitter]

Replying to itsananderson:

For what it's worth, get_permalink can be called outside the loop by passing a post ID, making the addition of "_the_" somewhat ambiguous.

get_the_title() and get_the_guid() both accept an ID, so the use of the already doesn't indicate that an ID is or isn't accepted. The the_ and get_the_ conventions simply indicate that functions either echo or return the information they retrieve, and this ticket doesn't aim to change that.

Replying to nacin:

get_permalink() is used in probably the vast majority of themes and plugins, and is one of the most well-known functions. I'm not sure deprecating it is worth the standardization.

I've trained new WordPress developers at various employers, taught WordPress development classes, and presented at WordCamps about how Core is organized; this inconsistency is a continual point of confusion in all of these situations. After I finish explaining the conventions WordPress attempts to adhere to, I must then list a series of exceptions.

What's the harm in making the changes in ericmann's patch? No action or filter tags change, we're simply cleaning up the codebase to introduce greater consistency and make it easier for developers to learn WordPress.

For a site that doesn't have WP_DEBUG set to true, we're simply adding another action call to the hundreds (or thousands) that already fire for each request. For a site with WP_DEBUG set to true, we are adding to the noise generated by Core's _deprecated_*() and _doing_it_wrong() functions, but let's be honest, it's already pretty noisy in here.

[itsananderson]

Alias get_permalink rather than deprecate it

[itsananderson]

Replying to ethitter:

get_the_title() and get_the_guid() both accept an ID, so the use of the already doesn't indicate that an ID is or isn't accepted. The the_ and get_the_ conventions simply indicate that functions either echo or return the information they retrieve, and this ticket doesn't aim to change that.

I chose a bad example, since an ID is accepted by the title functions. the_content and get_the_content would be better examples. Still, not really relevant to this ticket.

I've added a modification of Eric's patch that aliases get_permalink rather than deprecating it. This way people can use the intuitive name, but legacy code won't break or throw deprecated notices.

[johnpbloch]

Replying to itsananderson:

I've added a modification of Eric's patch that aliases get_permalink rather than deprecating it. This way people can use the intuitive name, but legacy code won't break or throw deprecated notices.

It doesn't make sense to me to add get_the_permalink() without deprecating get_permalink(). It seems to me that doing so would only further fragment the codebase rather than simplify and standardize it. The discussion we need to have (and which Nacin has already started) is whether the benefits of replacing get_permalink() with get_the_permalink() outweigh the costs (the cost being that ~90% of plugins and 100% of themes would need to update the function; not to avoid breaking, but to avoid showing warnings when WP_DEBUG is enabled).

I personally think that the benefit does outweigh the cost.

[knutsp]

Aliasing for a year, then deprecating.

[travisnorthcutt]

I personally think that the benefit does outweigh the cost.

+1. It doesn't break anything, and it moves WordPress one tiny step closer to a clean codebase with consistent standards.

[Viper007Bond]

I think deprecating it only via the phpDoc would be the way to go (basically aliasing it). It is simply too widely used and would throw warnings over everyone's development environments for no reason other than a name change (nothing wrong with the current function other than that).

I'm for the alias/rename, but only a pseudo-deprecate of the current function.

[ericmann]

Replying to Viper007Bond:

I'm for the alias/rename, but only a pseudo-deprecate of the current function.

I can live with that. New patch introduces get_the_permalink() with the logic all moved to the appropriate place. get_permalink() becomes just an alias for the other function, and is deprecated in the PHPDoc block describing the function.

Those of us with IDEs will see the change in our code, but it won't liter PHP notices or break anything in the meantime.

[ericmann]

Deprecate in docblocks only

[ethitter]

The latest approach is a good compromise. Wouldn't it make sense to update all internal references now as well? We'd essentially take the first patch, less the _deprecated_function() call. That way, anyone reading through Core would see references to the right function.

[ericmann]

Deprecate in docblocks, and replace all uses

[ericmann]

Replying to ethitter:

The latest approach is a good compromise. Wouldn't it make sense to update all internal references now as well?

It would, but I've split this into two patches to in case anyone thinks a global replacement is too big at this stage.

• 24164.patch Is just the docblock deprecation
• 24164-2.patch Is both the docblock deprecation and a replacement of all internal uses of get_permalink()

[aaronholbrook]

Replying to ericmann:

Replying to Viper007Bond:

I'm for the alias/rename, but only a pseudo-deprecate of the current function.

I can live with that. New patch introduces get_the_permalink() with the logic all moved to the appropriate place. get_permalink() becomes just an alias for the other function, and is deprecated in the PHPDoc block describing the function.

Those of us with IDEs will see the change in our code, but it won't liter PHP notices or break anything in the meantime.

+1 I think this is the way to go. Like travisnorthcutt made note of, it would help clean the codebase which I think would be a good idea.

[markoheijnen]

I don't get why it should be deprecated. get_permalink() isn't a theme function so to me it shouldn't have to follow the pattern.
I use it a lot in plugins for all kinds of things and it has most of the time nothing to do with a theme.

[knutsp]

Replying to markoheijnen:

I don't get why it should be deprecated. get_permalink() isn't a theme function so to me it shouldn't have to follow the pattern.
I use it a lot in plugins for all kinds of things and it has most of the time nothing to do with a theme.

Even if this function may be used outside the loop, it's used in themes and templates, specifically when concatenating to build a html string/block for later printing, or for special processing.

As long as it's a "soft" deprecation and aliasing, I see no problems. The pro is making it a bit easier to learn basic WordPress functions. For us who have learned, there is no point.

[ericlewis]

Related: #9927

Hopefully the play here can trickle down to any other similar instances where there's a widely used function that isn't quite properly named.

[wonderboymusic]

I have typed get_the_permalink() many times. Let's do something here. I don't know that the rebooting of every instance is necessary though... maybe just add the alias...

[nacin]

I'm 85% of the way there on yes to sneaking in an alias. I think this is a rare situation where deprecating should be avoided.

[wonderboymusic]

24164.diff​ just wraps get_permalink()

[nacin]

I'm not one to half-ass it, so here's some empirical data.

the_* function	get_the_* function	get_* function
the_author	get_the_author
the_modified_author	get_the_modified_author
the_author_meta	get_the_author_meta
the_author_link	get_the_author_link
the_author_posts	get_the_author_posts
the_author_posts_link	no getter
the_category	get_the_category	get_category is separate
the_tags	get_the_tags	get_tags is separate
the_terms	get_the_terms	get_terms is separate
the_title_rss	get_the_title_rss
the_content_feed	get_the_content_feed
the_excerpt_rss	no getter
the_permalink_rss	no getter
the_category_rss	get_the_category_rss
the_date_xml	no getter
the_date	get_the_date (similar)
the_modified_date	get_the_modified_date
the_time	get_the_time
the_modified_time	get_the_modified_time
the_weekday	no getter
the_weekday_date	no getter
the_search_query	doesn't follow the pattern	get_search_query
the_generator	get_the_generator
the_permalink	doesn't follow the pattern	get_permalink
the_feed_link	doesn't follow the pattern	get_feed_link
the_shortlink	no getter*
the_title	get_the_title
the_title_attribute	no getter
the_guid	get_the_guid
the_content	get_the_content
the_excerpt	get_the_excerpt
the_meta	no getter
the_attachment_link	get_the_attachment_link (deprecated)
the_post_thumbnail	get_the_post_thumbnail
the_post	(special)	get_post is separate
the_comment	(special)	get_comment is separate
the_taxonomies	get_the_taxonomies
the_widget	no getter

Note * — wp_get_shortlink() is a lower level function.

There are 38 non-deprecated functions in wp-includes that start with the_*.

• Two are the_post() and the_comment(); those don't count for this.
• 23 have get_the_* equivalents, assuming you count the slightly different get_the_date() and the deprecated get_the_attachment_link().
• 10 have no getter. Of these, few compellingly deserve a getter. For example, even though the_title_attribute() is one of the rare ones with the ability to pass echo=> false, I could go for get_the_title_attribute(), given how often it is used in i18n construction.
• That leaves 3 getters that exist but don't follow the pattern: get_search_query(), get_feed_link(), and get_permalink().

While I could go for aliases for get_the_search_query() and get_the_title_attribute(), get_permalink() stands out as the only major oddball.

[nacin]

In 27409:

Introduce get_the_permalink() as an alias for get_permalink().

This better aligns it with other the_* and get_the_* function pairs.

props ericmann.
fixes #24164.

[Viper007Bond]

I still think it might be worth explicitly promoting get_the_permalink() over get_permalink() by swapping them. get_the_permalink() would have the code and get_permalink() would be the alias with a @deprecated tag (but without throwing a deprecated error).

I love that we have an alias now but we should have a canonical function that's encouraged to be used.