PHP (7.3) is dead. Long live PHP (> 7.3)

==tldr The short version

5.69 (due for release on 3 Jan) will be the last release that supports PHP7.3. If you need to use php7.3 beyond the next 6 months you might consider signing up for the ESR. That is also true if you use extensions that cannot be upgraded for Smarty3 within the next 6 months. Release 5.69 contains a lot of code change to contribution pages (including bug fixes) and we recommend you take some time to test it with your site/extensions You will need to pay special attention to the membership receipts as the core version of that has changed. 

== the long version

We have established now that we drop support for each php version a year after PHP drops support for it. We time this to co-incide with the ESR release so that anyone who needs a bit longer can sign up for the ESR to buy themselves another 6 months. In addition we have embarked on an effort to upgrade our Smarty library from version 2 to version 3 and in future to version 4 for performance and security reasons. Release 5.69 is expected to work with both Smarty 2 and Smarty3 but at some point we will hard-switch to version 3. This will likely be during the lifetime of the 5.69 ESR. 

Over the past few months we have been doing a big push (with special kudos going to Bradley from BrightMinded and to Dave D) to address the various challenges with the more recent php8.x versions. Anyone who has used turned on debugging with CiviCRM prior to 5.69 will know that as soon as you turn on debugging you see screeds of red all over the place. In some cases these warnings that come up in debug mode have leaked into the user experience. In others they have masked more serious bugs, or caused extension developers to ignore deprecation notices, so addressing them became a priority

In recent releases we have almost eliminated these red error messages and also done a lot of work to address the stricter requirements of php8.2. In 5.69 the focus has been on the online contribution & membership changes. This required a lot of code cleanup & we had to throw out a few widget spinners that were gumming up the works before we could make sense of some of the code. That code cleanup did enable us to address some long-standing bugs and include fixes relating to tax calculation and recurring memberships and other issues that we would not have been able to do without cleaning up our code. One of the specific blockers to fixing some of these things in the past was how they interacted with the membership receipt. Hence in 5.69 the membership receipt template has been re-written and you may need to re-do any customisations. 

About a month ago I put out a dev-digest asking the community to do some QA on 5.69 rc and  I wish to thank Peter Davis from Fuzion and Joe Murray from JMA Consulting who have both done some testing in response to that.

While our goal has been to fix things this release carries a higher than usual risk of regressions in this important code area.  Unfortunately this contribution page code is ALSO some of the oldest code and most fragile code in CiviCRM.

It is also code that extensions often interact with, often in ways that we can’t predict. I liken this to me having an agreement with you for you to use my workshop & giving you the key and access code & instructions (the contract). If I change the access code then I’m going to do a whole process around changing that contract - but let’s say you discover a widget spinner in the corner that I haven’t used for years. If I need to fix the wiring in my workshop then I’m going to throw out the widget spinner because why would I spend hours assessing/fixing/upgrading a widget spinner I don’t use. But, you might be pretty grumpy because unbeknownst to me you were using it. 

In CiviCRM terms this means that our supported apiv3 contract is unchanged in a decade and our apiv4 contact has been established for a number of years. If we change those contracts it would be in the context of a CiviCRM 6.0 release. With internal code we do make a pretty good effort to figure out if people are using our widget spinners and we do various things to warn developers (code deprecations, deprecation warnings) of our intent to throw them out. I would say we spent hundreds of hours a year on trying to reduce the impact on extension writers of us cleaning up parts of our code base that are not part of our supported api.

All this is to say dozens of hours have gone into trying to be careful with the widget spinners with this release - but only part of the responsibility of testing / supporting /maintaining extensions lies with core. Our primary focus is on the supported ways that extensions can interact with CiviCRM. Hence I am putting out this blog to give you a heads up that 5.69 is the time to test any custom code that interacts with online contribution pages and ideally to test your normal usage for regressions. One thing you can do as a site owner to keep your widget spinners safe is to make sure that you use extensions with unit tests and that those tests are run regularly (which is what we call continuous integration or CI). As always the earlier you test & identify issues the more avidly we will provide support for those issues.

Finally  - after cleaning up the shed we installed a few new tools. We have added some new functions to our support contract on the contribution page (and some other forms). These are all annotated with `@api` and include

`getLineItems()`

`setLineItems()`

`getPriceFieldMetadata()`

`isTest()`

`getContributionID()`

`getContributionValue()`  

`getContributionPageID()`

`getContributionPageValue()` 

`getPriceSetID()`

`getPriceSetValue()`

`