Remove paged.php from the theme template hierarchy

[johnbillion]

The theme template hierarchy has support for a seldom-used template file called paged.php. This is intended as a template for paged archives but its implementation is almost useless, because it's the lowest priority template in the hierarchy before falling back to index.php. Here's the template hierarchy for a paged category archive:

1. category-uncategorized.php
2. category-1.php
3. category.php
4. archive.php
5. paged.php
6. index.php

If any other template file -- such as category.php or archive.php -- is in place, this will be chosen before paged.php. A theme with a paged.php template but without any kind of archive template is not a useful theme.

Let's remove paged.php from the hierarchy for simplicity.

A scan of the 4,000+ themes in the w.org theme directory reports not one single theme using a paged.php template. (Three themes are using a placeholder paged.php template in a subdirectory as part of a theme framework that uses a hierarchy identical to core.)

[lukecavanagh]

@johnbillion

I can not say I have ever used.

​https://codex.wordpress.org/Function_Reference/is_paged

[ryankienstra]

Request For Review

Hi @johnbillion,
Could you please review this patch, which takes paged.php out of the template heirarchy?

It deprecates get_paged_template(), which retrieved paged.php. It also removes the call of that function in ​wp-includes/template-loader.php. Perhaps it should be deleted instead, but it's a public function. It also removes the assertion test of the function in the PHPUnit tests.

[jcastaneda]

Just chiming in on this

(Three themes are using a placeholder paged.php template in a subdirectory as part of a theme framework that uses a hierarchy identical to core.)

Those three themes haven't been updated in over two years ( since May 4, 2014 ) and all from the same author as well. Adding up the installs for the three themes there are around 1300 active install in total.

Though @lukecavanagh if you run a query for is_paged() it would yield just about every theme. The more common one usage being in a breadcrumb. Even some core themes use. In ​Twenty Thirteen

[chriscct7]

Removing is_paged() seems a bit too dangerous as even an official core theme (2013) uses it. Removing the paged.php template could probably move forward. If there's a way of doing it, I'd be interested in seeing if the low usage isn't as low in Themeforest.

[johnbillion]

This has nothing to do with is_paged() -- just the paged.php template.

[jorbin]

What are the benefits to this? Sure it's highly unlikely to be used, but does that mean themes should be broken over it?

[johnbillion]

The benefit is reduced complexity and increased performance in the theme template hierarchy, and removal of a feature which -- as demonstrated above -- is almost completely useless.

If someone can show me a theme which is using a paged.php template in the way in which it was designed (eg. without any other archive template such as category.php or archive.php, I'd genuinely like to see it.

[helen]

I'm satisfied with the research and there's still time to find out if anything is broken, I'm for it.

[johnbillion]

In 38755:

Themes: Remove paged.php from the theme template hierarchy.

The position of this template within the hierarchy is of so little use that zero themes in the WordPress.org theme directory make use of it. It's second only to index.php in the hierarchy, meaning that any archive template such as category.php or archive.php will be chosen before it.

Fixes #38162
Props ryankienstra for initial patch

[luciandavidescu]

I just now discovered that my paged.php became useless months ago, as I saw my paginated archives popping back up on google. I was using it to place the noindex meta tag for pages 2 and on. By now I fixed my issue, but other people may keep trusting everything's fine when it's not.

It's more out there than just the themes in the repository; if you put out a documentation, it's cautious to expect that people might just use it.

[johnbillion]

Sorry you saw a problem as a result of this change, @luciandavidescu. The theme and plugin directories aren't the only place that themes and plugins exist, of course, but they are good indicators for the popularity of particular features.

Glad you got your problem sorted by other means.

[luciandavidescu]

I just hope I won't have to check for popularity before using a feature. To me it made sense being there, it did a job no other template does. Also, it's the kind of template one wouln't expect to necessarily find on a general-purpose theme, but that may be used nonetheless as a custom enhancement whenever the need arises.