IxDF Developer Docs

Appearance

Upgrading PHP ​

Checklist before update ​

  • Our codebase doesn’t use functionality removed in a version we are going to update to.
  • Tests should be passed on a new PHP version.
  • Make sure all dependencies are ready to update (e.g. composer why-not php 8.1).
  • Make sure all required PHP modules support a new version. Most of them are specified on composer.json, but not all of them.
    • Check a list of installed PHP modules for the current version of php-cli by running php -m.
    • Check a list o installed PHP modules for the current version of php-fpm by running executing phpinfo().
    • NewRelic is often a roadblocker, but this is an optional module. We can run the application without it. Should we wait for NewRelic agent support or not — the decision depends on different factors.

Prepare new config files for PHP ​

We keep our current configuration as a reference in this repository in the /infrastructure/php directory. Here we find two folders: staging and production, representing each environment. Within these folders we find copies of the configuration-files we need to change on our servers. There are two main use-cases, the cli/php.ini for the CLI context and fpm for frontend usage. When we install a new php version a new set of configuration files is provided, simply use locate php.ini to find the correct folder on the server.

Task: Transfer current configuration into new environment ​

If the old version is X.y, you want to copy the cli and fpm configuration folders via scp into your local environment into the folder X.z. Now we can use your favorite tool to compare X.y and X.z, PhpStorms Compare with... tool is one great choice to do that. Now it's very easy to pinpoint the different settings and adjust the new configuration to match the old. We may added comments to clarify a certain setting, so transferring them into the new config is encouraged. Once the settings match, we can scp our adjusted configuration files back to the server so they will take effect. We add and commit the new X.z to the repo into he infrastructure/php folder to ensure the configuration is documented.

Always keep actual server config and documentation in syn ​

It is very easy to change settings on the server and not document it in the way described above. For the next upgrade these undocumented changes will be lost, so we always need to ensure the documented settings are the same as the actual settings used on the server.

Checklist after update ​

We start to update our staging environment to grasp the impact of the changes. We want to update one of the dev-0x server to use the new version.

CI & automated test ​

We update the minimal php-version for composer, upgrade the dependencies, and let the CI run all checks. The goal is to make the build green, here we will learn about the most effects connected the upgrade.

Manual Testing ​

With an upgraded dev-0x instance we want to test all common features Guests, Members and Admins are going to perform. We need to ensure error_reporting(E_ALL) is set, otherwise we may miss something crucial.

  • In Incognito mode are we visiting all pages a Guest can visit
  • As a authenticated Member we visit all pages and perform all important actions (choose a course, answer a quiz, upgrade membership, ...)
  • As an Admin we try to access all Classic Admin Panel and Nova Panel pages and do the common actions (filter data, create resources, impersonate, ...)

Error Logs ​

When testing, we always keep an eye on our error_logs; they usually reveal the most information. When the steps above are done we want to switch the cli settings for develop to use the new version. The first point of failure is when the CI tries to deploy to develop server. We want to trigger a deployment to develop first, since it may blocks our team members to deploy important changes to the production environment if it fails. Only when this is clear, we want to keep this setting on for a day to give the automated jobs running during the night a chance to reveal other problems. When all these tests don't produce problems we can go ahead and update the production environment with confidence

Common problems/ Lessons learned ​

  • Early adaption often results in broken dependencies. One or more of the used composer dependencies or part of the Laravel core may not support the newest version yet. When this is the case we want to notify the project and/or provide a PR to publish the required changes if reasonable. When this is not possible (repo not maintained or similar), we may want to fork it and depend on our version or refactor it out of our codebase if possible.
  • Check New relic again before releasing to production ... it's very easy to overlook and may not properly catch in the review process above