WordPress.org

Make WordPress Core

Opened 6 years ago

Closed 5 years ago

Last modified 2 years ago

#24164 closed enhancement (fixed)

Deprecate `get_permalink()`

Reported by: ericmann Owned by: nacin
Milestone: 3.9 Priority: normal
Severity: normal Version: 3.5
Component: Permalinks Keywords: has-patch
Focuses: Cc:

Description

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

Attachments (5)

get_the_permalink.patch (46.9 KB) - added by ericmann 6 years ago.
Initial patch
get_the_permalink_alias.patch (44.1 KB) - added by itsananderson 6 years ago.
Alias get_permalink rather than deprecate it
24164.patch (1.1 KB) - added by ericmann 6 years ago.
Deprecate in docblocks only
24164-2.patch (46.8 KB) - added by ericmann 6 years ago.
Deprecate in docblocks, and replace all uses
24164.diff (760 bytes) - added by wonderboymusic 5 years ago.

Download all attachments as: .zip

Change History (36)

@ericmann
6 years ago

Initial patch

#1 @johnpbloch
6 years ago

  • Cc johnpbloch@… added

+1

#2 @itsananderson
6 years ago

  • Cc will@… added

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.

#3 follow-up: @nacin
6 years ago

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.

#4 @aniketpant
6 years ago

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.

#5 in reply to: ↑ 3 @ethitter
6 years ago

  • Cc erick@… added

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
6 years ago

Alias get_permalink rather than deprecate it

#6 follow-up: @itsananderson
6 years ago

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.

#7 in reply to: ↑ 6 @johnpbloch
6 years ago

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.

#8 @knutsp
6 years ago

Aliasing for a year, then deprecating.

#9 @travisnorthcutt
6 years ago

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.

#10 follow-up: @Viper007Bond
6 years ago

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.

#11 @travisnorthcutt
6 years ago

  • Cc travis@… added

#12 @sennza
6 years ago

  • Cc bronson@… added

#13 in reply to: ↑ 10 ; follow-up: @ericmann
6 years ago

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
6 years ago

Deprecate in docblocks only

#14 follow-up: @ethitter
6 years ago

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
6 years ago

Deprecate in docblocks, and replace all uses

#15 in reply to: ↑ 14 @ericmann
6 years ago

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

#16 in reply to: ↑ 13 @aaronholbrook
6 years ago

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.

#17 @SergeyBiryukov
6 years ago

  • Type changed from feature request to enhancement
  • Version changed from trunk to 3.5

#18 follow-up: @markoheijnen
6 years ago

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.

#19 in reply to: ↑ 18 @knutsp
6 years ago

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.

#20 @cais
6 years ago

  • Cc edward.caissie@… added

#21 @ericlewis
6 years ago

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.

#22 @ericlewis
6 years ago

  • Cc eric.andrew.lewis@… added

#23 @desrosj
6 years ago

  • Cc desrosj@… added

#24 @wonderboymusic
5 years ago

  • Milestone changed from Awaiting Review to 3.9

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

#25 @nacin
5 years ago

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.

#26 @nacin
5 years ago

  • Component changed from Template to Permalinks

@wonderboymusic
5 years ago

#27 @wonderboymusic
5 years ago

24164.diff just wraps get_permalink()

#28 @nacin
5 years ago

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.

#29 @nacin
5 years ago

  • Owner set to nacin
  • Resolution set to fixed
  • Status changed from new to closed

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.

#30 @Viper007Bond
5 years ago

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.

This ticket was mentioned in Slack in #docs by sergey. View the logs.


2 years ago

Note: See TracTickets for help on using tickets.