This week in addition to a bunch of bug fixes, we've also been doing a spot of housekeeping in our code. The following is quite technically heavy so if you're a non-developer, shield your eyes and read the less boring bits.
PHP:
/** @var \XF\Entity\User $user **/
$user = \XF::em()->create('XF:User');
Our preference going forwards is using class strings:
PHP:
$user = \XF::em()->create(\XF\Entity\User::class);
Because PHP natively understands these special strings, the issues with type hinting are no more, and doing things like renames of classes or moving classes becomes a much more trivial exercise.
Throughout the core XF code now, starting with RC3, we have replaced the majority of these legacy class short names with native class strings.
PHP:
use XF\Entity\User;
...
$user = \XF::em()->create(User::class);
So, now, across the code base, and through the use of automated tools such as PHP CS Fixer, we are simplifying these class names, similar to the example above.
PHP:
$userRepo = \XF::repository(\XF\Repository\User::class);
$user = \XF::em()->create(\XF\Entity\User::class);
How do you simplify both of these when the simplified version of both classes would be User::class?
Well, you can't, not really. One option would have been aliasing the import, e.g.
PHP:
use XF\Entity\User as UserEntity;
use XF\Repository\User as UserRepository;
...
$userRepo = \XF::repository(UserRepository::class);
$user = \XF::em()->create(UserEntity::class);
We didn't like this. It would have been difficult to maintain consistently or by using automated tools. So, of course, we decided to do something much more drastic:
PHP:
use XF\Entity\User;
use XF\Repository\UserRepository;
$userRepo = \XF::repository(UserRepository::class);
$user = \XF::em()->create(User::class);
Yup, we've renamed the majority of our classes. We decided to leave Entity classes alone as these do usually canonically refer to an actual thing, so a user entity having a name of User seemed to be appropriate (and this is a similar pattern to other PHP frameworks). But many other classes have now been renamed. Finder classes have a suffix of Finder. Repository classes have a suffix of Repository. Controller classes have a suffix of Controller. Controller plugin classes have a suffix of Plugin. Service classes have a suffix of Service. And the majority of our content type handler classes have a suffix of Handler. That's not an exhaustive list, but you get the idea.
Not only that, but if you wished to rename your own classes in your own add-ons in a similar way, you will be able to do so and we will take care of the class aliasing for you automatically. If you wanted to maintain compatibility in your add-ons with earlier versions of XenForo then keeping the legacy short names will still work, even if you rename your classes.
We cannot completely guarantee there won't be any compatibility issues so we encourage you all to take your time before upgrading to Release Candidate 3. If you are running XF 2.3 on a production site, we recommend doing a test upgrade first.
More specific details regarding bugs fixed in this release can be found in the resolved bugs forum.
This is pre-release software. It is not officially supported.
We do not recommend running it in production.
Please remember that this is pre-release software. It contains known bugs and incomplete functionality. We do not recommend running pre-release software in a production environment, and support is limited at this time to questions here on the community forums.
Add-ons and custom styles may be broken after upgrading to 2.3. You must test your add-ons thoroughly or look for updates. Be especially careful with add-ons that cover similar features to ones that are added to 2.3; these may conflict with the core XenForo data. If data conflicts are found, they will need to be resolved in a new add-on release or by removing the add-on before upgrading to 2.3.
If you choose to run pre-release software, it is your responsibility to ensure that you make a backup of your data. We recommend you do this before attempting an upgrade. If in doubt, always do a test upgrade on a copy of your production data.
All customers with active licenses may now download the new version from the customer area.
Alongside the release of XenForo 2.3.0 Release Candidate 3, we are also releasing updated versions of each of our official add-ons:
Please remember that this is pre-release software. It contains known bugs and incomplete functionality. We do not recommend or support running pre-release software in a production environment. Support for pre-releases are limited to questions here on the community forums.
Source: xenForo
Much wider usage for class strings
As a reminder, XenForo 2.3 brings with it support for using native PHP class strings. For example, originally we used "class short names" to point to certain classes. While these were easy to write, it makes refactoring classes difficult, and you need these PHP doc comments to hint to code editors what object is ultimately returned in the code:PHP:
/** @var \XF\Entity\User $user **/
$user = \XF::em()->create('XF:User');
Our preference going forwards is using class strings:
PHP:
$user = \XF::em()->create(\XF\Entity\User::class);
Because PHP natively understands these special strings, the issues with type hinting are no more, and doing things like renames of classes or moving classes becomes a much more trivial exercise.
Throughout the core XF code now, starting with RC3, we have replaced the majority of these legacy class short names with native class strings.
Class imports / simplifying class names
In actual fact, our much stronger preference going forwards is we use simplified class names, rather than fully qualified class names. That looks like this:PHP:
use XF\Entity\User;
...
$user = \XF::em()->create(User::class);
So, now, across the code base, and through the use of automated tools such as PHP CS Fixer, we are simplifying these class names, similar to the example above.
Renaming classes
Let's look at another example:PHP:
$userRepo = \XF::repository(\XF\Repository\User::class);
$user = \XF::em()->create(\XF\Entity\User::class);
How do you simplify both of these when the simplified version of both classes would be User::class?
Well, you can't, not really. One option would have been aliasing the import, e.g.
PHP:
use XF\Entity\User as UserEntity;
use XF\Repository\User as UserRepository;
...
$userRepo = \XF::repository(UserRepository::class);
$user = \XF::em()->create(UserEntity::class);
We didn't like this. It would have been difficult to maintain consistently or by using automated tools. So, of course, we decided to do something much more drastic:
PHP:
use XF\Entity\User;
use XF\Repository\UserRepository;
$userRepo = \XF::repository(UserRepository::class);
$user = \XF::em()->create(User::class);
Yup, we've renamed the majority of our classes. We decided to leave Entity classes alone as these do usually canonically refer to an actual thing, so a user entity having a name of User seemed to be appropriate (and this is a similar pattern to other PHP frameworks). But many other classes have now been renamed. Finder classes have a suffix of Finder. Repository classes have a suffix of Repository. Controller classes have a suffix of Controller. Controller plugin classes have a suffix of Plugin. Service classes have a suffix of Service. And the majority of our content type handler classes have a suffix of Handler. That's not an exhaustive list, but you get the idea.
Yikes! What about backwards compatibility?
We've taken care of that. We have developed an aliasing system which should handle all of these class names in a sane and backwards compatible manner. Whether your code is currently peppered with legacy strings, e.g. XF:User or you have already moved to using class strings, e.g. \XF\Repository\User::class, these will be automatically aliased to the new class e.g. \XF\Repository\UserRepository::class. Existing add-ons and class extensions will continue to work as normal.Not only that, but if you wished to rename your own classes in your own add-ons in a similar way, you will be able to do so and we will take care of the class aliasing for you automatically. If you wanted to maintain compatibility in your add-ons with earlier versions of XenForo then keeping the legacy short names will still work, even if you rename your classes.
Other changes
We have also made some other wide ranging changes across the code as a result of automatically running PHP CS Fixer. On the whole this doesn't change much, but if you're the type of person who has your XF files in a GitHub repo, you will see a lot of changes, but these are mostly just trying to make the overall code base a little easier to read, follow and overall more consistent.We cannot completely guarantee there won't be any compatibility issues so we encourage you all to take your time before upgrading to Release Candidate 3. If you are running XF 2.3 on a production site, we recommend doing a test upgrade first.
More specific details regarding bugs fixed in this release can be found in the resolved bugs forum.
This is pre-release software. It is not officially supported.
We do not recommend running it in production.
Please remember that this is pre-release software. It contains known bugs and incomplete functionality. We do not recommend running pre-release software in a production environment, and support is limited at this time to questions here on the community forums.
Add-ons and custom styles may be broken after upgrading to 2.3. You must test your add-ons thoroughly or look for updates. Be especially careful with add-ons that cover similar features to ones that are added to 2.3; these may conflict with the core XenForo data. If data conflicts are found, they will need to be resolved in a new add-on release or by removing the add-on before upgrading to 2.3.
If you choose to run pre-release software, it is your responsibility to ensure that you make a backup of your data. We recommend you do this before attempting an upgrade. If in doubt, always do a test upgrade on a copy of your production data.
All customers with active licenses may now download the new version from the customer area.
Download XenForo 2.3.0 Release Candidate 3
From the licensed customer area
Alongside the release of XenForo 2.3.0 Release Candidate 3, we are also releasing updated versions of each of our official add-ons:
- XenForo Media Gallery 2.3.0 Release Candidate 3
- XenForo Resource Manager 2.3.0 Release Candidate 3
- XenForo Enhanced Search 2.3.0 Release Candidate 3
Download official add-ons
From the licensed customer area
Requirements
The following are minimum requirements:- PHP 7.2 or newer
- MySQL 5.7 and newer
- All of the add-ons listed here require XenForo 2.3.
- Enhanced Search requires at least Elasticsearch 7.2
Installation and upgrade instructions
Full details for how to install and upgrade XenForo can be found in the XenForo manual. One-click upgrades from XF 2.2 are possible, but you must uncheck the "Only check for stable upgrades" option in Options > Basic board information. Once the XF 2.3 upgrade has been complete, the official add-ons should be upgraded as well.Please remember that this is pre-release software. It contains known bugs and incomplete functionality. We do not recommend or support running pre-release software in a production environment. Support for pre-releases are limited to questions here on the community forums.
Source: xenForo