Hi BuddyPress Contributors!

Using the WordPress Rewrite API to replace our Legacy URL parser is a challenge we’ve been trying to achieve for 8 years.

It’s a pretty massive and complex change because BuddyPress plugins/themes and even BuddyPress Core 😬 got used to directly write URLs by adding chunks after a directory, a single member item or a single group item permalink.

Today, our Legacy URL parser is analyzing these URL chunks to globally set variables (eg:  buddypress()->current_action) we can check using specific functions (eg: bp_current_action()) to decide how the plugin should behave.

As it’s working mostly fine, we’ve been postponing this change for a while which is making it harder today to actually migrate to the WordPress Rewrite API. As I often write when announcing a release candidate on our official website:

“Release Candidate” means that we believe the new version is ready for release, but with more than 200,000 active installs, hundreds of BuddyPress plugins and Thousands of WordPress themes, it’s possible something was missed. BuddyPress ?.0.0 is slated for release on Month dd, YYYY and we need your help to get there.

Not to mention the potential customizations advanced users can do using specific constants, specific WordPress configurations, or by adding custom code into the mu-plugins directory or inside a bp-custom.php file.

To safely make this change: we need to have enough confidence into the backward compatibility mechanism we’ll put in place. There’s no secret: the only way to reach this level of confidence is to test, test and test again. The more we are to test and the sooner we do these tests during the development cycle, the better it is for end users, plugin developers, theme designers, BP support team, BP development team: anticipating is less painful than healing!

Your contribution is the key to the success of our challenge.

Why migrating? isn’t the Legacy URL parser doing a good job?

It does! But we believe using the WP Rewrite API will improve users BuddyPress experience making it possible to directly use the plugin without having to change the permalink structure if the site is using plain permalinks and making it a piece of cake to customize URL slugs. Moreover, we think following WordPress best practices in this area is important for our project and will help us increase our “forward compatibility” with the WordPress Full Site Editing feature.

BP Rewrites is a “Feature as a plugin” 

We think using the “feature as a plugin” mode can:

1. make things easier for you (actually us all!) to do this huge amount of testing,
2. accelerate the development of the code needed to achieve this “WP Rewrites” migration.

1. Once the team will be happy about our improvements on the feature, we’ll make BP Rewrites available from the WordPress.org Plugins directory. To have it running on your site, you’ll simply need to install & activate it like any other plugin. As soon as you deactivate BP Rewrites, it puts everything back to the state it was before its activation.

2. Working on the 9.0.0 release mainly from the BP Blocks GitHub repository showed us it was accelerating our development process. Let’s hope it will be the same for BP Rewrites. We haven’t received more contributions to BP Blocks from GitHub users, but at the very list we make this possible and everyone’s very welcome to contribute to code!

You can already help us with tests & code!

If you’re comfortable with using GitHub and can easily put up a local development environment, or install the BuddyPress one (it requires Docker) or have already one in place, feel free to start contributing to BP Rewrites 😍.

Please take a few minutes to read these contributor guidelines to quickly get started.

What happens once BP Rewrites is activated?

As soon as you activate BP Rewrites, BuddyPress is using the WordPress Rewrite API, you have no other installation step to achieve. The Legacy directory pages are automatically migrated as specific buddypress custom post type items (let’s call it “BuddyPress directory” post type) used to maintain backward compatibility and make it possible to revert to the BP Legacy URL parser simply by deactivating the BP Rewrites plugin.

If you included BuddyPress pages into a WordPress menu, the menu will automatically be updated to use the “BuddyPress directory” post type.

With BP Rewrites, there’s no need to associate BP Directories with WordPress Pages anymore, as a result the BuddyPress Pages settings administration screen is replaced by the BuddyPress URLs settings administration screen.

Customizing slugs is a piece of cake!

If you go to this new Settings > BuddyPress > URLs administration screen you’ll be able to customize the BuddyPress URL slugs very easily. In the following example I translated the default BuddyPress slugs by their french meaning.

Under the hood changes

To maintain backward compatibility we are still setting global variables (eg:  buddypress()->current_action), so using the specific functions (eg: bp_current_action()) to decide about the behavior of your plugin/theme/custom code can still be done. The only difference is you need to wait a bit longer during the WordPress loading page process to use these functions.

The BP Legacy URL parser is making them available at the 'bp_init' hook (which is very early!) while the BP Rewrite URL parser is now making them available once the WP Query has been parsed: at the 'bp_parse_query' hook. The same “delay” applies to the BuddyPress Components navigation set up, the BuddyPress canonical stack set up and the BuddyPress document title set up.

What still needs to be done?

• At the risk of being very redundant, we all have to test, test and test again! 
• We also need to decide about how we can deal with the bad habit we all took when writing BuddyPress URLs into our code base: rather than directly writing URLs by adding chunks after a directory, a single member item or a single group item permalink, we need to introduce Core functions to make sure the custom slugs will be taken in account everywhere. If you look at the code inside the BP Rewrites  src/bp-{component-id}/bp-{component-id}-template.php  files, you’ll see there’s a huge work in front of us, and I’m pretty sure the first alpha version of BP Rewrites missed some “Legacy built” URLs.
• We’ll probably need to deprecate a lot of functions to achieve the previous point.
• We need to write PHP Unit Tests !!!
• We need to document how Plugins/Themes/Custom codes can use our BP Rewrite API.
• I’m probably missing some points, so don’t hesitate to add your thoughts in comments 👌

Thanks in advance for your contributions 😍

#alpha, #release, #rewrites