Make WordPress Core

Opened 20 months ago

Closed 20 months ago

Last modified 13 months ago

#38162 closed enhancement (fixed)

Remove paged.php from the theme template hierarchy

Reported by: johnbillion Owned by: johnbillion
Milestone: 4.7 Priority: low
Severity: minor Version:
Component: Themes Keywords: has-patch
Focuses: template Cc:


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

Attachments (2)

160.diff (2.0 KB) - added by ryankienstra 20 months ago.
38162.patch (2.8 KB) - added by johnbillion 20 months ago.

Download all attachments as: .zip

Change History (19)

#1 @lukecavanagh
20 months ago


I can not say I have ever used.


Last edited 20 months ago by lukecavanagh (previous) (diff)

20 months ago

#2 @ryankienstra
20 months ago

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.

#3 @johnbillion
20 months ago

  • Keywords has-patch needs-testing added; needs-patch removed
  • Owner set to johnbillion
  • Status changed from new to reviewing

#4 @jcastaneda
20 months ago

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

This ticket was mentioned in Slack in #core by chriscct7. View the logs.

20 months ago

#6 @chriscct7
20 months ago

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.

#7 @johnbillion
20 months ago

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

#8 @jorbin
20 months ago

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

#9 @johnbillion
20 months ago

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.

This ticket was mentioned in Slack in #core by jeffpaul. View the logs.

20 months ago

#11 @johnbillion
20 months ago

  • Priority changed from normal to low

#12 @helen
20 months ago

  • Keywords 2nd-opinion removed

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

20 months ago

#13 @johnbillion
20 months ago

  • Keywords needs-testing removed
  • Status changed from reviewing to accepted

#14 @johnbillion
20 months ago

  • Resolution set to fixed
  • Status changed from accepted to closed

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

#15 @luciandavidescu
13 months ago

  • Severity changed from normal to minor
  • Type changed from enhancement to defect (bug)
  • Version set to 4.7.4

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.

Last edited 13 months ago by luciandavidescu (previous) (diff)

#16 @johnbillion
13 months ago

  • Type changed from defect (bug) to enhancement
  • Version 4.7.4 deleted

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.

#17 @luciandavidescu
13 months ago

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.

Note: See TracTickets for help on using tickets.