Introduce get_canonical_url function

[joostdevalk]

Short version

We need a function that allows consistent retrieving and filtering of the canonical URL. I'm proposing creating a get_canonical_url function to do just that.

Explanation

With the advent of more and more different ways to deliver content, we need to make sure the canonical URL on all these different manifestations of content is correct. Right now, all the plugins out there, for instance ​the AMP plugin here, the ​the Instant Articles plugin here and core's own post oEmbed functionality, all in some way use get_permalink to get the canonical. The ​point of a canonical URL is that it can point to the canonical version and that this does not necessarily have to be the representation in the WP database. Thus you need to be able to filter it.

I'm attaching a patch that introduces get_canonical_url and uses this in core's rel_canonical function, which is used on both the normal output of posts and pages as well as on oEmbed iframes.

[joostdevalk]

First patch

[bjornjohansen]

There are quite a few plugins out there that modify the permalink, e.g. analytics-plugins that add tracking codes to the URL to let publishers know that the visitor came via a feed.

But in some instances, like with the Instant Articles plugin mentioned in the ticket explanation, it is critical to get a clean canonical URL. A get_canonical_url() would be very useful, so we can be assured that we provide the actual canonical URL and not some permalink that has been tampered with.

I’m very much +1 on this.

[markjaquith]

So the main difference is that this integrates post paging and comments paging?

[joostdevalk]

Replying to markjaquith:

So the main difference is that this integrates post paging and comments paging?

No, that code was there already, just got moved as otherwise this wouldn't work. I'd say the main difference is that we have a specific function and filter for the canonical, because it's conceptually different from the rather generic get_permalink.

[joemcgill]

This may also be a good place to enforce a canonical scheme for sites. Related: #30581

[joostdevalk]

Replying to joemcgill:

This may also be a good place to enforce a canonical scheme for sites. Related: #30581

If that gets dev approval I'll happily code a patch.

[jipmoors]

Fixed apply_filters and added tests

[jipmoors]

Bit unsure what name to give the test file, so if there is a better name or place for it please let me know.

[ocean90]

@joostdevalk, @jipmoors: Thanks for your patches. 36168.patch​ is a refresh and includes following changes:

• Name of function should start with wp_: wp_get_canonical_url()
• Removes the default argument for get_permalink()
• Docs tweaks
• Tests: Use shared test fixture
• Tests: Use WP_UnitTestCase::go_to() and WP_UnitTestCase::set_permalink_structure()
• Tests: Move test class to the /link/ directory

Let me know what you think.

[DrewAPicture]

36168.diff​ improves 36168.patch​ by adding a changelog entry to the DocBlock for rel_canonical() and other minor docs tweaks.

[ocean90]

In 37685:

Canonical: Introduce wp_get_canonical_url().

wp_get_canonical_url() encapsulates the URL logic of rel_canonical() to provide a consistent way to retrieve the canonical URL for a post.
The new filter get_canonical_url allows to customize the canonical URL.

Props joostdevalk, jipmoors, DrewAPicture, ocean90.
Fixes #36168.