3.3.8 (develop to uat)

.github/workflows/ci.yml

@@ -96,6 +96,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version-file: '.nvmrc'
+          cache: 'npm'
 
       - name: Cache Composer
         uses: actions/cache@v4
@@ -105,35 +106,40 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-composer-unit-
 
-      # This job only needs vendor/bin/phpunit (from Composer) and the wp-env
-      # CLI. A full `npm ci` pulls ~2,200 packages and has taken anywhere from
-      # 36s to 7 minutes on hosted runners; @wordpress/env alone is ~400
-      # packages and installs in ~30s. It is installed into a scratch prefix
-      # outside the repo so npm does not reconcile against package-lock.json
-      # and pull the whole tree anyway. The version is read from the lockfile
-      # so it cannot drift from what developers run locally.
-      - name: Install Composer dependencies
-        run: composer install --no-interaction --no-progress
-
-      - name: Install wp-env
-        run: |
-          version=$(node -p "require('./package-lock.json').packages['node_modules/@wordpress/env'].version")
-          echo "Installing @wordpress/env@$version"
-          npm install --prefix "$RUNNER_TEMP/wp-env" --no-audit --no-fund "@wordpress/env@$version"
-          echo "$RUNNER_TEMP/wp-env/node_modules/.bin" >> "$GITHUB_PATH"
+      # This job only needs vendor/bin/phpunit and the wp-env CLI, so it used to
+      # install @wordpress/env on its own into a scratch prefix rather than run
+      # a full `npm ci`. That install resolved dependency ranges fresh against
+      # npm instead of obeying package-lock.json, which made the job depend on
+      # whatever upstream had published that day: a broken @wp-playground/cli
+      # release, pulled in transitively by @wordpress/env, failed every run
+      # while the lockfile-based jobs were unaffected.
+      #
+      # `npm ci` installs the locked tree, so the job can no longer break
+      # because of a third-party release. The postinstall hook runs
+      # `patch-package && composer install`, which is what provides
+      # vendor/bin/phpunit, so this single step covers both toolchains.
+      #
+      # Deliberately not `--ignore-scripts`, for the same reason as the e2e
+      # job below: besides skipping the Composer install, that flag made this
+      # step take 1m30s instead of ~36s from a cold cache.
+      - name: Install dependencies
+        run: npm ci
 
       # The wp-env sources directory is deliberately not cached. A restored
       # ~/.wp-env carries the previous run's install state, which skipped the
       # plugin's activation hook and left the relationships table missing.
+      # .wp-env.ci.json omits the HTTPS URLs and the proxy lifecycle script
+      # that .wp-env.json uses for local development. Runners have no local CA
+      # and no proxy container, so they serve the site over plain HTTP.
       - name: Start wp-env
-        run: wp-env start
+        run: npx wp-env start --config .wp-env.ci.json
 
       - name: Run unit tests
-        run: wp-env run tests-cli --env-cwd="wp-content/plugins/$(basename "$PWD")" vendor/bin/phpunit
+        run: npx wp-env run tests-cli --config .wp-env.ci.json --env-cwd="wp-content/plugins/$(basename "$PWD")" vendor/bin/phpunit
 
       - name: Stop wp-env
         if: always()
-        run: wp-env stop
+        run: npx wp-env stop --config .wp-env.ci.json
 
   e2e:
     name: E2E (Playwright)
@@ -192,7 +198,7 @@ jobs:
         env:
           PLAYWRIGHT_CACHE_HIT: ${{ steps.playwright-cache.outputs.cache-hit }}
         run: |
-          npm run env:start > wp-env-start.log 2>&1 &
+          npx wp-env start --config .wp-env.ci.json > wp-env-start.log 2>&1 &
           wp_env_pid=$!
 
           if [ "$PLAYWRIGHT_CACHE_HIT" = "true" ]; then
@@ -215,14 +221,18 @@ jobs:
             exit 1
           fi
 
+      # Runners have no local CA and no HTTPS proxy, so the suite talks to
+      # wp-env's published port directly over plain HTTP. WP_BASE_URL is the
+      # single switch for this; see tests/e2e/playwright.config.js.
       - name: Run E2E tests
         env:
           CLOUDINARY_E2E_URL: ${{ secrets.CLOUDINARY_E2E_URL }}
+          WP_BASE_URL: http://localhost:8889
         run: npm run test:e2e
 
       - name: Stop wp-env
         if: always()
-        run: npm run env:stop
+        run: npx wp-env stop --config .wp-env.ci.json
 
       - name: Upload Playwright artifacts
         if: failure()

.gitignore

@@ -46,6 +46,9 @@ coverage/html/
 # wp-env personal overrides
 .wp-env.override.json
 
+# Locally generated TLS certificates and CA for the wp-env HTTPS proxy
+/.wp-env/certs/
+
 # IDE
 .vscode
 

.wp-env.ci.json

@@ -0,0 +1,26 @@
+{
+  "core": "WordPress/WordPress#7.1",
+  "phpVersion": "8.5",
+  "plugins": ["."],
+  "config": {
+    "WP_DEBUG": true,
+    "WP_DEBUG_LOG": true,
+    "SCRIPT_DEBUG": true
+  },
+  "mappings": {
+    "wp-content/mu-plugins": "./.wp-env/mu-plugins"
+  },
+  "lifecycleScripts": {
+    "afterStart": "./.wp-env/scripts/fix-loopback.sh"
+  },
+  "env": {
+    "tests": {
+      "phpVersion": "8.2",
+      "config": {
+        "WP_DEBUG": true,
+        "WP_DEBUG_LOG": true,
+        "SCRIPT_DEBUG": true
+      }
+    }
+  }
+}

.wp-env.json

@@ -5,21 +5,31 @@
   "config": {
     "WP_DEBUG": true,
     "WP_DEBUG_LOG": true,
-    "SCRIPT_DEBUG": true
+    "SCRIPT_DEBUG": true,
+    "WP_HOME": "https://cloudinary.local.wpenv.net",
+    "WP_SITEURL": "https://cloudinary.local.wpenv.net",
+    "FORCE_SSL_ADMIN": true,
+    "WP_CONTENT_URL": "https://cloudinary.local.wpenv.net/wp-content",
+    "WP_PLUGIN_URL": "https://cloudinary.local.wpenv.net/wp-content/plugins"
   },
   "mappings": {
     "wp-content/mu-plugins": "./.wp-env/mu-plugins"
   },
   "lifecycleScripts": {
-    "afterStart": "./.wp-env/scripts/fix-loopback.sh"
+    "afterStart": "./.wp-env/scripts/after-start.sh"
   },
   "env": {
     "tests": {
       "phpVersion": "8.2",
       "config": {
         "WP_DEBUG": true,
         "WP_DEBUG_LOG": true,
-        "SCRIPT_DEBUG": true
+        "SCRIPT_DEBUG": true,
+        "WP_HOME": "https://tests.cloudinary.local.wpenv.net",
+        "WP_SITEURL": "https://tests.cloudinary.local.wpenv.net",
+        "FORCE_SSL_ADMIN": true,
+        "WP_CONTENT_URL": "https://tests.cloudinary.local.wpenv.net/wp-content",
+        "WP_PLUGIN_URL": "https://tests.cloudinary.local.wpenv.net/wp-content/plugins"
       }
     }
   }

.wp-env/docker/mkcert/Dockerfile

@@ -0,0 +1,16 @@
+FROM golang:1.24-alpine
+
+# Set the version tag to build.
+ENV MKCERT_VERSION="v1.4.4"
+
+RUN apk add --no-cache git
+
+RUN git clone https://github.com/FiloSottile/mkcert /go/mkcert \
+	&& cd /go/mkcert \
+	&& git checkout "tags/$MKCERT_VERSION" -b "build/$MKCERT_VERSION" \
+	&& go build -ldflags "-X main.Version=$MKCERT_VERSION" -o /bin/mkcert
+
+# mkcert reads and writes its CA here. The compose file mounts the project's
+# certificate directory over it, so both the CA and the issued certificates
+# stay inside the repository instead of the developer's global mkcert store.
+WORKDIR /root/.local/share/mkcert

.wp-env/mu-plugins/https-proxy.php

@@ -0,0 +1,105 @@
+<?php
+/**
+ * HTTPS proxy awareness — local dev helper mu-plugin.
+ *
+ * The local environment terminates TLS in an nginx container that forwards to
+ * wp-env over plain HTTP (see .wp-env/proxy/). Apache therefore sees an HTTP
+ * request, and without this mu-plugin `is_ssl()` returns false even though the
+ * browser is on HTTPS. That mismatch causes an admin redirect loop with
+ * FORCE_SSL_ADMIN enabled, drops the `secure` flag from auth cookies, and makes
+ * the plugin's own scheme checks take the wrong branch:
+ *
+ *   - php/class-delivery.php builds delivery URLs from `is_ssl()`.
+ *   - php/class-media.php sets the cookie `secure` flag from `is_ssl()`.
+ *
+ * The fix is the standard reverse-proxy one: promote the forwarded scheme onto
+ * $_SERVER before WordPress reads it. On a real host this would live in
+ * wp-config.php, but wp-env generates that file and rewrites it on every start,
+ * so it goes here instead. mu-plugins load from wp-settings.php before
+ * wp_cookie_constants() and wp_ssl_constants() run, which is early enough for
+ * both to see the corrected value.
+ *
+ * Only trusted because the proxy is the sole route into these containers in
+ * local development. Never ship this pattern to production without pinning the
+ * trusted proxy address.
+ *
+ * @package Cloudinary
+ */
+
+defined( 'ABSPATH' ) || exit;
+
+if (
+	isset( $_SERVER['HTTP_X_FORWARDED_PROTO'] ) &&
+	'https' === strtolower( sanitize_text_field( wp_unslash( $_SERVER['HTTP_X_FORWARDED_PROTO'] ) ) )
+) {
+	$_SERVER['HTTPS'] = 'on';
+
+	// Keep SERVER_PORT consistent with the scheme. WordPress appends a non
+	// standard port to generated URLs, and the unforwarded 80 here would
+	// produce links such as https://example.test:80/.
+	if ( isset( $_SERVER['HTTP_X_FORWARDED_PORT'] ) ) {
+		$_SERVER['SERVER_PORT'] = absint( $_SERVER['HTTP_X_FORWARDED_PORT'] );
+	}
+}
+
+/**
+ * Removes the wp-env port from a site URL.
+ *
+ * The wp-env tool appends its published port to WP_HOME and WP_SITEURL when it
+ * writes wp-config.php, and there is no configuration option to prevent it.
+ * See postProcessConfig() in @wordpress/env/lib/config/post-process-config.js.
+ *
+ * The proxy serves the site on the standard HTTPS port, so the appended 8888 or
+ * 8889 is wrong: it leaks into redirects, canonical URLs, asset URLs and the
+ * cookie path. Stripping it here is the last chance to correct the value,
+ * because the constants are already defined by the time mu-plugins load.
+ *
+ * The port to remove is not hard-coded, because wp-env lets developers change
+ * it through WP_ENV_PORT or a "port" key in the config files. The origin is
+ * taken from WP_CONTENT_URL instead, which .wp-env.json defines as the intended
+ * public URL and which wp-env never rewrites. Any port on the incoming URL is
+ * then replaced with whatever that constant says, so a custom wp-env port is
+ * handled without this file knowing about it.
+ *
+ * This filter cannot fix asset URLs. wp_plugin_directory_constants() defines
+ * WP_CONTENT_URL and WP_PLUGIN_URL from get_option( 'siteurl' ) at
+ * wp-settings.php line 497, ten lines before mu-plugins load, so plugin CSS and
+ * JS would keep the port. Those two constants are therefore set explicitly in
+ * .wp-env.json, where wp-env leaves them alone because it only rewrites
+ * WP_HOME, WP_SITEURL and WP_TESTS_DOMAIN.
+ *
+ * @param string $url The home or site URL.
+ * @return string The URL with the wp-env port replaced by the public origin.
+ */
+function cld_strip_wp_env_port( $url ) {
+	if ( ! is_string( $url ) || ! defined( 'WP_CONTENT_URL' ) ) {
+		return $url;
+	}
+
+	$origin = wp_parse_url( WP_CONTENT_URL );
+
+	if ( empty( $origin['scheme'] ) || empty( $origin['host'] ) ) {
+		return $url;
+	}
+
+	$parts = wp_parse_url( $url );
+
+	// Only rewrite URLs that point at the same host, so an unrelated URL
+	// passing through these filters is left alone.
+	if ( empty( $parts['host'] ) || $parts['host'] !== $origin['host'] ) {
+		return $url;
+	}
+
+	$public = $origin['scheme'] . '://' . $origin['host'];
+
+	if ( ! empty( $origin['port'] ) ) {
+		$public .= ':' . $origin['port'];
+	}
+
+	$path = isset( $parts['path'] ) ? $parts['path'] : '';
+
+	return $public . $path;
+}
+
+add_filter( 'option_home', 'cld_strip_wp_env_port', 20 );
+add_filter( 'option_siteurl', 'cld_strip_wp_env_port', 20 );

.wp-env/proxy/docker-compose.yml

@@ -0,0 +1,45 @@
+# TLS proxy in front of the wp-env environment.
+#
+# Started and stopped by ../scripts/proxy-up.sh and ../scripts/proxy-down.sh,
+# which export the variables used below from ../scripts/config.sh. This is a
+# separate compose project from wp-env's own, so `wp-env destroy` cannot remove
+# it and `wp-env start` cannot overwrite it.
+
+services:
+  # Builds mkcert and issues the certificate, then exits. The proxy waits for a
+  # successful exit so it never starts without a certificate on disk.
+  mkcert:
+    build: ../docker/mkcert
+    volumes:
+      - ../certs:/root/.local/share/mkcert
+    # The working directory is the mounted certificate directory, so both the
+    # CA and the issued pair land in .wp-env/certs/. The wildcard covers the
+    # tests host name.
+    command:
+      - sh
+      - -c
+      - test -f "$$DEV_HOST.crt" || mkcert -cert-file "$$DEV_HOST.crt" -key-file "$$DEV_HOST.key" "$$DEV_HOST" "*.$$DEV_HOST"
+    environment:
+      DEV_HOST: ${DEV_HOST}
+
+  proxy:
+    image: nginx:1.29-alpine
+    depends_on:
+      mkcert:
+        condition: service_completed_successfully
+    ports:
+      - '${PROXY_HTTP_PORT}:${PROXY_HTTP_PORT}'
+      - '${PROXY_HTTPS_PORT}:${PROXY_HTTPS_PORT}'
+    volumes:
+      - ../certs:/etc/nginx/certs:ro
+      - ./nginx.conf.template:/etc/nginx/templates/default.conf.template:ro
+    environment:
+      DEV_HOST: ${DEV_HOST}
+      TESTS_HOST: ${TESTS_HOST}
+      PROXY_HTTP_PORT: ${PROXY_HTTP_PORT}
+      PROXY_HTTPS_PORT: ${PROXY_HTTPS_PORT}
+      WP_ENV_PORT: ${WP_ENV_PORT}
+      WP_ENV_TESTS_PORT: ${WP_ENV_TESTS_PORT}
+    extra_hosts:
+      - 'host.docker.internal:host-gateway'
+    restart: unless-stopped