fix: warn and fallback for unsupported PHP versions

[AaronFeledy]

Summary

Fixes #347 — users with php_version: 7.1 (or other EOL PHP versions) in their pantheon.yml get a cryptic Docker error:

appserver Error manifest for devwithlando/pantheon-appserver:7.1-5 not found: manifest unknown

This happens because generation 5 images only exist for PHP 8.0+. Older PHP versions (5.x, 7.x) only had images up to generation 4.

Changes

lib/utils.js — In getPantheonConfig():

• Defines SUPPORTED_PHP_VERSIONS (8.0, 8.1, 8.2, 8.3, 8.4)
• After determining generation, checks if the PHP version has a gen5 image
• If not, warns the user and falls back to generation 4 so they can still build with their configured PHP version

builders/pantheon-php.js — Safety net:

• Second-line check before constructing the Docker image tag
• Falls back to gen4 if the builder is invoked without going through getPantheonConfig

Warning output

⚠️  WARNING: PHP 7.1 does not have a generation 5 image.
   Falling back to the generation 4 image (devwithlando/pantheon-appserver:7.1-4).
   Consider updating php_version in your pantheon.yml to a supported version: 8.0, 8.1, 8.2, 8.3, 8.4

Testing

• Lint passes clean
• No test files modified — this is a runtime guard + user-facing warning

---

Note

Medium Risk
Changes how PHP runtime generation and Docker image tags are selected, which can alter the runtime image used for existing projects and may mask misconfigurations despite the added warning.

Overview
Prevents cryptic Docker pull failures when php_version is set to an older/EOL PHP by detecting unsupported PHP+gen5 combinations and falling back to gen4 images. getPantheonConfig now defines supported gen5 PHP versions, uses a shared default PHP version constant, and emits a user-facing warning when it switches generations.

Adds a second safety check in the pantheon-php builder to silently downgrade generation to 4 if an unsupported PHP version is requested, updates example verification commands to use @@tx_isolation for MariaDB compatibility, and bumps @lando/php to 1.12.0.

^{Written by Cursor Bugbot for commit 7ba970e. This will update automatically on new commits. Configure here.}

[netlify]

❌ Deploy Preview for lando-pantheon failed. Why did it fail? →

Name	Link
🔨 Latest commit	7ba970e
🔍 Latest deploy log	https://app.netlify.com/projects/lando-pantheon/deploys/69c1a61ed5c3f70009dfe1f5

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

Bugbot Autofix prepared fixes for all 3 issues found in the latest run.

• ✅ Fixed: Fallback to generation 4 instead of PHP 8.3 fails
  • Changed fallback logic to set data.php to DEFAULT_PHP_VERSION ('8.3') instead of changing data.generation to '4', ensuring the image tag uses 8.3-5 which exists on Docker Hub.
• ✅ Fixed: Duplicated PHP version lists risk going out of sync
  • Exported SUPPORTED_PHP_VERSIONS from utils.js and updated pantheon-php.js to use utils.SUPPORTED_PHP_VERSIONS, eliminating the duplicate constant.
• ✅ Fixed: YAML-parsed PHP 8.0 incorrectly flagged as unsupported
  • Added normalization in getPantheonConfig to convert '8' to '8.0' and '7' to '7.0' before the version check, preventing false positives when js-yaml parses 8.0 as the number 8.

Or push these changes by commenting:

@cursor push 09d1df49e0

Preview (09d1df49e0)

diff --git a/builders/pantheon-php.js b/builders/pantheon-php.js
--- a/builders/pantheon-php.js
+++ b/builders/pantheon-php.js
@@ -5,9 +5,6 @@
 const LandoPhp = require('@lando/php/builders/php.js');
 const utils = require('./../lib/utils.js');
 
-// PHP versions that have generation 5 images; older versions top out at generation 4
-const SUPPORTED_PHP_VERSIONS_GEN5 = ['8.0', '8.1', '8.2', '8.3', '8.4'];
-
 // Builder
 module.exports = {
   name: 'pantheon-php',
@@ -25,7 +22,7 @@
       if (options.php === '8' || options.php === 8) options.php = '8.0';
 
       // Safety check: fall back to generation 4 if the php+generation combo has no image
-      if (options.generation === '5' && !SUPPORTED_PHP_VERSIONS_GEN5.includes(String(options.php))) {
+      if (options.generation === '5' && !utils.SUPPORTED_PHP_VERSIONS.includes(String(options.php))) {
         options.generation = '4';
       }
 

diff --git a/lib/utils.js b/lib/utils.js
--- a/lib/utils.js
+++ b/lib/utils.js
@@ -218,6 +218,8 @@
 const SUPPORTED_PHP_VERSIONS = ['8.0', '8.1', '8.2', '8.3', '8.4'];
 const DEFAULT_PHP_VERSION = '8.3';
 
+exports.SUPPORTED_PHP_VERSIONS = SUPPORTED_PHP_VERSIONS;
+
 exports.getPantheonConfig = (files = ['pantheon.upstream.yml', 'pantheon.yml']) => _(files)
   .filter(file => fs.existsSync(file))
   .map(file => yaml.load(fs.readFileSync(file)))
@@ -225,6 +227,9 @@
   .thru(data => {
     // Set the php version
     data.php = _.toString(_.get(data, 'php_version', DEFAULT_PHP_VERSION));
+    // Normalize because 7.0/8.0 right away gets handled strangely by js-yaml
+    if (data.php === '7') data.php = '7.0';
+    if (data.php === '8') data.php = '8.0';
     // Set the webroot
     data.webroot = (_.get(data, 'web_docroot', false)) ? 'web' : '.';
     // Set the drush version
@@ -234,14 +239,14 @@
     // @DEPRECATED: Pantheon php_runtime_generation: 1 is deprecated and will be removed April 2026.
     const phpRuntimeGen = _.get(data, 'php_runtime_generation', 2);
     data.generation = phpRuntimeGen === 1 ? '4' : '5';
-    // Warn and fall back to generation 4 if the configured PHP version has no generation 5 image
+    // Warn and fall back to PHP 8.3 if the configured PHP version has no generation 5 image
     if (data.generation === '5' && !SUPPORTED_PHP_VERSIONS.includes(data.php)) {
       console.warn([
         `\n⚠️  WARNING: PHP ${data.php} does not have a generation 5 image.`,
-        `   Falling back to the generation 4 image (devwithlando/pantheon-appserver:${data.php}-4).`,
+        `   Falling back to PHP ${DEFAULT_PHP_VERSION} for this build.`,
         `   Consider updating php_version in your pantheon.yml to a supported version: ${SUPPORTED_PHP_VERSIONS.join(', ')}\n`,
       ].join('\n'));
-      data.generation = '4';
+      data.php = DEFAULT_PHP_VERSION;
     }
     // Set the tika version if specified in pantheon.yml
     const tikaVersion = _.get(data, 'tika_version');

[cursor]

Fallback to generation 4 instead of PHP 8.3 fails

High Severity

When an unsupported PHP version (e.g. 7.1) is detected with generation 5, the code falls back to generation 4 while keeping the old PHP version. However, generation 4 images likely don't exist on Docker Hub either, so the user would still get a manifest unknown Docker error — just with tag 7.1-4 instead of 7.1-5. The PR description states the intent is to fall back to PHP 8.3 (via the defined but unused-in-fallback DEFAULT_PHP_VERSION constant), which would actually resolve the issue since gen 5 images for 8.3 exist.

Additional Locations (1)

• builders/pantheon-php.js#L27-L30

 

[cursor]

Duplicated PHP version lists risk going out of sync

Medium Severity

The supported PHP version list is hardcoded identically in both SUPPORTED_PHP_VERSIONS_GEN5 in builders/pantheon-php.js and SUPPORTED_PHP_VERSIONS in lib/utils.js. Since utils is already imported in the builder file, exporting the constant from utils and reusing it would prevent the two lists from drifting apart when a new PHP version is added.

Additional Locations (1)

• lib/utils.js#L217-L218

 

[cursor]

YAML-parsed PHP 8.0 incorrectly flagged as unsupported

High Severity

When php_version: 8.0 appears in pantheon.yml, js-yaml parses it as the number 8 (since 8.0 === 8 in JS). _.toString(8) produces '8', which doesn't match '8.0' in SUPPORTED_PHP_VERSIONS. This causes the version check to incorrectly flag PHP 8.0 as unsupported, emit a spurious warning, and change generation to '4'. The builder normalizes '8' → '8.0' on lines 24–25, but that happens too late — getPantheonConfig has already altered the generation. PHP 8.0 is a valid, supported version and this would break users who have it configured.