Add role display name to WP_Role object

[jdgrimes]

Roles have both a name (slug) and display_name. The display_name is saved to the database in an untranslated form, and should be translated with translate_user_role() before display.

I would have thought that you could get the display name of a role by first calling get_role() to retrieve the WP_Role object, and then accessing a property or method. However, the WP_Role objects are constructed only with the name and capabilities of the role. It is therefore not possible to retrieve the display_name directly from the WP_Role object.

Instead, to retrieve the display_name for a role, you have to call WP_Roles::get_names(), which returns an array of (untraslated) role display names (not the slug names).

I am proposing that we introduce a way to get the display name directly from the WP_Role object. Possibly we could offer two properties: display_name with the translated display name, and raw_display_name with the raw display name (in case it would actually be useful for anything). I would never have known that the role display names needed special treatment for translation if I hadn't done this digging, so it would probably be helpful to newbies if the translated names were exposed in the API by default, instead of untranslated. (Related: #20764)

In the process, maybe it would be possible to clear up the difference between the name and the name, at least in the docs. Perhaps that deserves its own ticket. It really is confusing in the code though, so much so that I've had to double-check which name (the display or the slug) was the one passed to WP_Role. Both of them are just referred to as the name in much of the code.

This goes all the way back to [2703] when the role classes were introduced.

[andizer]

Added the two suggested methods to WP_Role class

[andizer]

I just added a patch. I hope I did implement the two suggested methods well.

[jdgrimes]

Replying to andizer:

I just added a patch. I hope I did implement the two suggested methods well.

I think that $this->name is just the slug, and translate_user_role() needs to be passed the display_name (which isn't on the WP_Role object). So we also need to change things so that WP_Role is constructed with the display name too, or else have WP_Role retrieve it from WP_Roles::get_names(). (It's all very confusing, I know!)

[johnjamesjacoby]

In order for this to work in 4.7 and on, it will likely need to be via a magic getter.

If the translated string is set as a property of the class, it wouldn't get updated if the locale changes.

There is also some conflation between what $name means compared to the $role_id. I'm not sure any other named variable we could use later would be any better, but clearing this up would be nice.

---

I think all we can do is pass in the non-translated role name to the __construct() method, and magically pass it through translate_user_role() every time it's requested.

The non-translated role name is always saved in the database in English, and there is no guarantee that custom roles will match the same way the core roles do. bbPress, for example, uses a bbp_ namespace on the role ID's, even though the names saved in the database do not include it.

[garrett-eclipse]

Related - #43885