CiviCRM 5.26 and WordPress - Major Changes
There was recently changes to WordPress that is changing the way redirect_canonical works. You can view the details in our GitLab issue #49 , If you want further details you can see all of the WordPress issues related to how redirects are done. These changes are designed to better handle rel="canonical" in WP. For CiviCRM this means that any version of CiviCRM before 5.26 will not work once the WordPress changes are released. This 'breaking' change for CiviCRM is slated to be in WP 5.5. WP is due to release on August 11th We cannot stress this fact enough: if you update WordPress and do not update CiviCRM to 5.26 your front end pages will be broken.
The effect of the changes in WP will mean that any front end URL that has page=CiviCRM will have that removed from the URL and the page will most likely result in a "404 - Page not found" error. Since these WP changes break CiviCRM we had to come up with a fix. Thanks go to Christian Wach for writing the initial PR and Andrei Mondoc for improving upon it.
The CiviCRM changes that have been added to version 5.26 correct this by changing "page=CiviCRM" to "civiwp=CiviCRM" in the URL. Additionally, this will also handle redirects for existing URLs. New front end pages will use civiwp= on the front end and CiviCRM will not create URLS with page= in the URL on the front end any longer. In the WordPress admin /wp-admin/ URLs are unchanged.
For Example, If you have a donation page with a current URL of
https://example.org/civicrm?page=CiviCRM&q=civicrm%2Fcontribute%2Ftransact&reset=1&id=1
The page will display. Upon submission of the form the URL will change to
https://example.org/civicrm?civiwp=CiviCRM&q=civicrm%2Fcontribute%2Ftransact&_qf_Confirm_display=true&qfKey=xx
The end user won't see the change until they confirm the donation, but internally it works. If you create the page using a shortcode page as
https://example.org/donate
When the end user confirms the donation they will see a new URL
https://example.org/donate/?civiwp=CiviCRM&q=civicrm%2Fcontribute%2Ftransact&_qf_Confirm_display=true&qfKey=x
We've tested extensivley and are satisfied that these changes are the best way to move forward. The PRs themselves are:
With any change there is risk, as we cannot test every use case. We have tried to identify other areas that may be affected. We looked at:
- Recurring and One Time Contributions
- CiviMail
- Extensions that use a callback URL
Any callback with a payload (contribution data, tokens from a mailing, bounce notifications from a SMTP extension) risk being lost. This PR deals with that specifically and will help matters, but we recommend updating all callback URLs.
If possible you will want to add 307 redirects for Payment processors like PayPal that use IPNs. This Article has details on how to set up a redirect.
Payment processors like Stripe will detect that the call back URL needs updating. In testing we found that not only did I need to update the callback URL but it was also necessary to delete any old incorrect webhooks.
We also looked at Mailing Extensions such as Airmail, SES, and SparkPost While the PRs should handle the redirects we recommend updating the callbacks on this as well.
We could not test all extensions, so please review the extensions in use and make updates for any that have a callback using page=CiviCRM in the URL.
We've also found that if your site uses Cleaner URLs and these are used for callbacks, they should work. Cleaner URLs do not have page=CiviCRM in the URL so it is handled transparently. You still must update! However, the plus side is that your URLs won't change.
If you have time to test, please download the Release Candidate Any Issues or improvements can be logged in CiviCRM GitLab
Comments
Upon making the changes the URL in my admin panels also got affected so I had to restore. Please provide more details on this.
Hi Azeemiqbal, there is more documentation here: https://docs.civicrm.org/installation/en/latest/wordpress/#enable-clean-urls