Custom page class (UserPage) not used for $user API variable when usePageClasses is enabled

[adrianbj]

The $user API variable is instantiated as a plain ProcessWire\User instead of the custom UserPage class, even when $config->usePageClasses = true and site/classes/UserPage.php exists and correctly extends User.

Current behavior

get_class($user) returns ProcessWire\User in templates. Calling any custom method defined in UserPage throws:

WireException: Method User::hasDisabledAccount does not exist or is not callable in this context

However, class_exists('ProcessWire\UserPage') returns true at the same point in execution, confirming the class is autoloadable.

$pages->get($user->id) also returns a plain User (page instance cache returns the same object). Only $pages->getFresh($user->id) correctly resolves to the custom page class.

Expected behavior

$user should be an instance of UserPage when usePageClasses is enabled and the class exists in site/classes/.

Analysis

The issue appears to be in the page class resolution/caching chain during bootstrap:

1. Users::__construct() calls setPageClass('User')
2. PagesType::getPageClass() copies 'User' onto the user template's pageClass property (because the template's own pageClass is empty)
3. Templates::getPageClass() is called — Stage 1 resolves 'User' to ProcessWire\User
4. Stage 3 (convention-based auto-detection) should then find UserPage and override — but the final cached result is still ProcessWire\User

Once cached in Templates::$pageClassNames[$templateId], all subsequent loads (including $pages->get()) return plain User objects for the user template.

I suspect this may be related to the bootstrap refactor in 2b17d114 (splitting __construct() into __construct() + boot()) which changed initialization order.

  // Before: everything in constructor
  $wire = new ProcessWire($config);

  // After: two-phase boot
  $wire = new ProcessWire($config, '/', false);  // false = don't boot yet
  $wire->boot($config);

This reordering likely causes the user template's pageClass to be resolved and cached before the usePageClasses auto-detection has fully initialized — so it caches User instead of UserPage, and Stage 3 never
gets a chance to override it.

Reproduction

1. Enable $config->usePageClasses = true in site/config.php
2. Create site/classes/UserPage.php:

<?php namespace ProcessWire;
class UserPage extends User {
    public function hello(): string {
        return 'world';
    }
}

3. Log in as a front-end user
4. In any template: echo get_class($user); → outputs ProcessWire\User
5. echo $user->hello(); → throws WireException

Workaround

Reload $user via getFresh() in site/init.php:

$_u = $this->wire('user');
if ($_u->isLoggedIn() && !($_u instanceof UserPage)) {
    $_reloaded = $this->wire('pages')->getFresh($_u->id);
    if ($_reloaded instanceof UserPage) {
        $this->wire('user', $_reloaded);
    }
    unset($_reloaded);
}
unset($_u);

[adrianbj]

Hey @ryancramerdesign - was testing completely automated Claude issue creation there, but I do think it's summed up everything and it did help me with that temporary workaround which is doing the trick.

In case it helps, this is what I was getting without the workaround. I have a hasDisabledAccount() method in my /site/classes/UserPage.php

Not again… WireException: Method User::hasDisabledAccount does not exist or is not callable in this context in wire/core/Wire.php:555

#0 wire/core/Page.php (1556): Wire->___callUnknown('...', Array)
#1 wire/core/Wire.php (411): Page->___callUnknown('...', Array)
#2 wire/core/WireHooks.php (1020): Wire->_callMethod('...', Array)
#3 wire/core/Wire.php (476): WireHooks->runHooks(Object(User), '...', Array)
#4 wire/core/Wire.php (479): Wire->__call('...', Array)
#5 site/templates/account.php (39): Wire->__call('...', Array)
#6 wire/core/TemplateFile.php (328): require('...')
#7 wire/core/Wire.php (405): TemplateFile->___render()
#8 wire/core/WireHooks.php (1020): Wire->_callMethod('...', Array)
#9 wire/core/Wire.php (476): WireHooks->runHooks(Object(TemplateFile), '...', Array)
#10 wire/modules/PageRender.module (547): Wire->__call('...', Array)
#11 wire/core/Page.php (3106): PageRender->render(Object(Page), Array)
#12 wire/core/Wire.php (408): Page->___renderPage(Array)
#13 wire/core/WireHooks.php (1020): Wire->_callMethod('...', Array)
#14 wire/core/Wire.php (476): WireHooks->runHooks(Object(Page), '...', Array)
#15 wire/core/Page.php (3051): Wire->__call('...', Array)
#16 wire/core/Wire.php (405): Page->___render()
#17 wire/core/WireHooks.php (1020): Wire->_callMethod('...', Array)
#18 wire/core/Wire.php (476): WireHooks->runHooks(Object(Page), '...', Array)
#19 wire/modules/Process/ProcessPageView.module (195): Wire->__call('...', Array)
#20 wire/modules/Process/ProcessPageView.module (116): ProcessPageView->renderPage(Object(Page), Object(PagesRequest))
#21 wire/core/Wire.php (408): ProcessPageView->___execute(true)
#22 wire/core/WireHooks.php (1020): Wire->_callMethod('...', Array)
#23 wire/core/Wire.php (476): WireHooks->runHooks(Object(ProcessPageView), '...', Array)
#24 index.php (58): Wire->__call('...', Array)
#25 {main}

Let me know if you need anything else.

[ryancramerdesign]

@adrianbj So far I can't seem to duplicate it. Mine is always coming through as UserPage. I created a /site/classes/UserPage.php that extends User, then set config.usePageClasses=true; in site/config.php. Then added this line to site/templates/admin.php:

$wire->message($user->className());

Also tried this in site/templates/home.php

die($user->className()); 

Both report UserPage. You mentioned the changes around construct/boot in ProcessWire.php. So I'm wondering if your index.php is the latest? It shouldn't matter, but was curious, just in case.

[adrianbj]

Thanks @ryancramerdesign - index.php is the latest.

Things that might be contributing is that I am using a custom user page/template. I have the standard user template obviously but also have a "person" template. So, I do have a separate PersonPage.php class file:

namespace ProcessWire;

/**
 * Despite a Person not being a service user, we have to extend from User to overcome
 * a bug in PW core.
 */

class PersonPage extends User
{
}

as well as the base UserPage.php class which has the hasDisabledAccount() method as noted in the OP. I see the error when loading a page on the frontend when logged in as a frontend user with the normal user template.

[adrianbj]

@ryancramerdesign - the problem goes away as soon as I remove my: $config->userTemplateIDs =

It changes from:

to:

so definitely the same UsePage class, but the class isn't being applied.

  $config->userTemplateIDs = [3, 58]; // 'user' and 'person' templates                                                                                                                                           
  $config->usersPageIDs = [29, 1038];                                                                                                                                                                              

And in site/classes/ I have separate custom classes for each:

  // UserPage.php                                                                                                                                                                                                  
  class UserPage extends User { ... }                                                                                                                                                                            
                                                                                                                                                                                                                   
  // PersonPage.php
  class PersonPage extends User { }                                                                                                                                                                                

So the standard single-template setup won't reproduce it.

Claude suspects the multiple userTemplateIDs changes the order/caching in Users::__construct() → setPageClass('User') → Templates::getPageClass(), and the convention-based auto-detection (UserPage.php) never gets a chance to override the cached result for one or both templates.

[ryancramerdesign]

@adrianbj I was able to duplicate the issue here by a custom user template and class that isn't UserPage. I've pushed a fix for that. Does it also fix it there? The only thing though is that it looks to me like this issue has always been there, and it sounds like it used to work correctly for you before the addition of the ProcessWire::boot() method? I just wanted to confirm that non UserPage custom user classes were working for you before? If so, I'd still want to better understand why in order to make sure my fix the right one. Thanks.

[adrianbj]

Hey @ryancramerdesign — I am honestly not sure at this point what caused it to start - I have different PW versions and different versions of my site but Claude just identified a very simple PW core change that fixes it for me.

The getLoadOptions() fix didn't resolve the issue, but apparently the problem is upstream in PagesType::getPageClass():

  public function getPageClass() {                                                                                                                                                                                 
      if($this->template) {                                                                                                                                                                                        
          if($this->pageClass && !$this->template->pageClass) {                                                                                                                                                  
              $this->template->pageClass = $this->pageClass;  // <-- this line
          }                                                                                                                                                                                                        
          return $this->template->getPageClass(true);
      }                                                                                                                                                                                                            
      ...                                                                                                                                                                                                        
  }

When usePageClasses is enabled, this pushes 'User' onto the template's pageClass property before Template::getPageClass(true) runs its convention-based auto-detection. Since pageClass is now set, the convention lookup (which would find UserPage.php) is skipped, and the result is cached as ProcessWire\User permanently.

The getLoadOptions() fix doesn't help because it calls parent::getLoadOptions() → getPageClass() first, which already poisons the template's cached pageClass. Unsetting it from the returned options array is too late.
The fix that works is a one-line change in PagesType::getPageClass(): (adding && !$this->wire()->config->usePageClasses)

if($this->pageClass && !$this->template->pageClass && !$this->wire()->config->usePageClasses) {                                                                                                                  
    $this->template->pageClass = $this->pageClass;                                                                                                                                                             
}

When usePageClasses is enabled, this skips the forced assignment and lets Template::getPageClass(true) do its convention-based lookup, which correctly resolves UserPage. When usePageClasses is disabled (the default), behaviour is unchanged.

Tested and working with multiple userTemplateIDs and separate custom classes (UserPage, PersonPage, ContactPage).

[adrianbj]

Hi @ryancramerdesign - even with that fix (which solves my missing class method errors) I am seeing differing behavior between the latest PW dev version and one that is early 3.0.257.

I have a team page branch with the person template and on both installs all users get PersonPage, but on the newer dev version, the one superuser in that branch shows as User instead of UserPage