Local dev environment, lint tooling, and manual release pipeline

.wp-env.json

@@ -0,0 +1,15 @@
+{
+	"core": null,
+	"plugins": [ "." ],
+	"config": {
+		"WP_DEBUG": true,
+		"WP_DEBUG_LOG": true,
+		"WPCACHEHOME": "/var/www/html/wp-content/plugins/wp-super-cache/"
+	},
+	"mappings": {
+		"wp-content/plugins/wp-super-cache": ".",
+		"wp-content/mu-plugins": "./tests/dev/mu-plugins"
+	},
+	"testsEnvironment": false,
+	"phpVersion": "8.1"
+}

Makefile

@@ -0,0 +1,50 @@
+.DEFAULT_GOAL := help
+
+PLUGIN_NAME := wp-super-cache
+WP_ENV := COMPOSE_PROJECT_NAME=$(PLUGIN_NAME) npx @wordpress/env
+
+## Development environment
+install: ## Install PHP (Composer) and JS (npm) dependencies
+	composer install
+	npm install
+
+up: ## Start WordPress in Docker (http://localhost:8888, admin/password)
+	$(WP_ENV) start
+
+down: ## Stop the WordPress containers
+	$(WP_ENV) stop
+
+destroy: ## Remove the WordPress containers and database
+	$(WP_ENV) destroy
+
+logs: ## Tail the WordPress container logs
+	$(WP_ENV) logs
+
+cli: ## Open a shell inside the WordPress container
+	$(WP_ENV) run cli bash
+
+wp: ## Run an arbitrary wp-cli command, e.g. `make wp CMD="plugin list"`
+	$(WP_ENV) run cli wp $(CMD)
+
+## Test content
+seed: ## Create 100 randomly named posts and 100 pages for cache testing
+	$(WP_ENV) run cli wp eval-file wp-content/plugins/wp-super-cache/tests/dev/seed.php
+
+unseed: ## Delete content created by `make seed`
+	$(WP_ENV) run cli wp eval-file wp-content/plugins/wp-super-cache/tests/dev/unseed.php
+
+## Lint
+lint: ## Run PHP CodeSniffer
+	composer lint
+
+lint-all: ## Run PHP CodeSniffer on all files
+	composer phpcs
+
+lint-fix: ## Auto-fix PHP CodeSniffer issues
+	composer lint-fix
+
+## Help
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: install up down destroy logs cli wp seed unseed lint lint-all lint-fix help

README.md

@@ -39,8 +39,35 @@ changelog/                Individual changelog entries (Jetpack Changelogger for
 
 - PHP 7.4+
 - [Composer](https://getcomposer.org/)
+- Node.js 20+ and Docker (only needed for the Makefile / wp-env workflow)
 
-### Installation
+### Quick start with the Makefile
+
+A `Makefile` is provided to spin up a disposable WordPress site in Docker (via [`@wordpress/env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/)) with the plugin pre-mounted. Run `make help` to see every target.
+
+```bash
+make install     # composer install + npm install
+make up          # start WordPress at http://localhost:8888 (admin / password)
+make seed        # create 100 random posts + 100 random pages for cache testing
+# ... hack on the plugin; files are live-mounted into the container ...
+make unseed      # delete only the content created by `make seed`
+make down        # stop containers
+make destroy     # stop and wipe the database
+```
+
+Other useful targets:
+
+| Target | Purpose |
+|--------|---------|
+| `make cli` | Open a shell inside the WordPress container |
+| `make wp CMD="super-cache status"` | Run an arbitrary `wp-cli` command |
+| `make logs` | Tail the WordPress container logs |
+| `make lint` / `make lint-fix` | Run / auto-fix PHPCS on changed PHP files |
+| `make lint-all` | Run PHPCS on the full codebase |
+
+The seed script tags every item it creates with `_wpsc_seed=1` post meta, so `make unseed` only removes content it generated — it will not touch posts or pages you created by hand.
+
+### Manual installation
 
 ```bash
 composer install
@@ -59,8 +86,11 @@ composer test-coverage
 ### Linting
 
 ```bash
-# PHPCS (WordPress/Jetpack coding standards)
-vendor/bin/phpcs
+# Changed PHP files only (matches CI)
+make lint
+
+# Full-tree PHPCS (WordPress/Jetpack coding standards)
+make lint-all
 ```
 
 ### Static analysis

composer.json

@@ -19,6 +19,18 @@
 		]
 	},
 	"scripts": {
+		"phpcs": [
+			"./tools/phpcs-wrapper.sh --standard=.phpcs.xml.dist ."
+		],
+		"phpcbf": [
+			"./tools/phpcbf-wrapper.sh --standard=.phpcs.xml.dist ."
+		],
+		"lint": [
+			"./tools/run-phpcs-changed.sh"
+		],
+		"lint-fix": [
+			"./tools/run-phpcbf-changed.sh"
+		],
 		"phpunit": [
 			"phpunit-select-config phpunit.#.xml.dist --colors=always"
 		],

tests/dev/mu-plugins/wpsc-loopback-fix.php

@@ -0,0 +1,56 @@
+<?php
+/**
+ * Plugin Name: WP Super Cache dev loopback fix
+ *
+ * The @wordpress/env container exposes WordPress on port 80 internally but
+ * is mapped to http://localhost:8888 on the host. WordPress therefore stores
+ * its site URL as http://localhost:8888, and any PHP code doing a loopback
+ * HTTP request (WP Super Cache preloader, WP-Cron, REST self-calls, etc.)
+ * will try to reach :8888 inside the container — where nothing is listening.
+ *
+ * This mu-plugin intercepts outgoing HTTP requests aimed at the host-side
+ * URL and retries them against the docker-compose service hostname, so
+ * loopback works the same way in Docker as it does on a normal host — both
+ * when PHP runs inside the `wordpress` container (cron, preloader) and
+ * when wp-cli triggers loopback from the separate `cli` container.
+ *
+ * @package WP_Super_Cache
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	return;
+}
+
+add_filter(
+	'pre_http_request',
+	function ( $preempt, $args, $url ) {
+		static $rewriting = false;
+
+		if ( $rewriting || ! is_string( $url ) ) {
+			return $preempt;
+		}
+
+		$host_url = 'http://localhost:8888';
+		if ( strncasecmp( $url, $host_url, strlen( $host_url ) ) !== 0 ) {
+			return $preempt;
+		}
+
+		// Route the request to the internal docker service (port 80) but
+		// preserve the Host header so WordPress does not canonical-redirect
+		// back to http://localhost:8888.
+		$rewritten = 'http://wordpress' . substr( $url, strlen( $host_url ) );
+
+		if ( ! isset( $args['headers'] ) || ! is_array( $args['headers'] ) ) {
+			$args['headers'] = array();
+		}
+		$args['headers']['Host'] = 'localhost:8888';
+
+		$rewriting = true;
+		$response  = wp_remote_request( $rewritten, $args );
+		$rewriting = false;
+
+		return $response;
+	},
+	10,
+	3
+);

tests/dev/seed.php

@@ -0,0 +1,61 @@
+<?php
+/**
+ * Seed a local development site with randomly-named posts and pages so that
+ * caching behavior (preload, garbage collection, mod_rewrite) can be exercised
+ * against a realistic volume of content.
+ *
+ * Intended to be executed via `wp eval-file` inside the `make up` environment.
+ * Every item is tagged with post_meta `_wpsc_seed=1` so `tests/dev/unseed.php`
+ * can remove the seeded content without touching anything else.
+ *
+ * @package WP_Super_Cache
+ */
+
+if ( ! defined( 'WP_CLI' ) || ! WP_CLI ) {
+	exit( 1 );
+}
+
+$count = 100;
+
+function wpsc_seed_random_title( $prefix ) {
+	$words = array( 'alpha', 'bravo', 'charlie', 'delta', 'echo', 'foxtrot', 'golf', 'hotel', 'india', 'juliet', 'kilo', 'lima', 'mike', 'november', 'oscar', 'papa', 'quebec', 'romeo', 'sierra', 'tango', 'uniform', 'victor', 'whiskey', 'xray', 'yankee', 'zulu' );
+	shuffle( $words );
+	return $prefix . ': ' . ucfirst( $words[0] ) . ' ' . ucfirst( $words[1] ) . ' ' . substr( md5( (string) wp_rand() ), 0, 6 );
+}
+
+function wpsc_seed_random_body() {
+	$body = '';
+	for ( $p = 0; $p < 5; $p++ ) {
+		$body .= '<p>' . str_repeat( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. ', wp_rand( 3, 8 ) ) . "</p>\n\n";
+	}
+	return $body;
+}
+
+$created = array(
+	'post' => 0,
+	'page' => 0,
+);
+
+foreach ( array( 'post', 'page' ) as $content_type ) {
+	for ( $i = 0; $i < $count; $i++ ) {
+		$inserted_post_id = wp_insert_post(
+			array(
+				'post_title'   => wpsc_seed_random_title( ucfirst( $content_type ) ),
+				'post_content' => wpsc_seed_random_body(),
+				'post_status'  => 'publish',
+				'post_type'    => $content_type,
+			),
+			true
+		);
+
+		if ( is_wp_error( $inserted_post_id ) ) {
+			WP_CLI::warning( sprintf( 'Failed to insert %s: %s', $content_type, $inserted_post_id->get_error_message() ) );
+			continue;
+		}
+
+		update_post_meta( $inserted_post_id, '_wpsc_seed', 1 );
+		++$created[ $content_type ];
+	}
+}
+
+WP_CLI::success( sprintf( 'Seeded %d posts and %d pages.', $created['post'], $created['page'] ) );

tests/dev/unseed.php

@@ -0,0 +1,31 @@
+<?php
+/**
+ * Remove content created by tests/dev/seed.php. Safe to run repeatedly —
+ * deletes only posts/pages that carry the `_wpsc_seed=1` meta key.
+ *
+ * @package WP_Super_Cache
+ */
+
+if ( ! defined( 'WP_CLI' ) || ! WP_CLI ) {
+	exit( 1 );
+}
+
+$ids = get_posts(
+	array(
+		'post_type'      => array( 'post', 'page' ),
+		'post_status'    => 'any',
+		'posts_per_page' => -1,
+		'fields'         => 'ids',
+		'meta_key'       => '_wpsc_seed',
+		'meta_value'     => 1,
+	)
+);
+
+$deleted = 0;
+foreach ( $ids as $post_to_delete_id ) {
+	if ( wp_delete_post( $post_to_delete_id, true ) ) {
+		++$deleted;
+	}
+}
+
+WP_CLI::success( sprintf( 'Deleted %d seeded posts/pages.', $deleted ) );

tools/phpcbf-wrapper.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+exec php -d error_reporting='E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED' "$ROOT_DIR/vendor/bin/phpcbf" "$@"

tools/phpcs-wrapper.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+exec php -d error_reporting='E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED' "$ROOT_DIR/vendor/bin/phpcs" "$@"

tools/run-phpcbf-changed.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PHPCBF_WRAPPER="$ROOT_DIR/tools/phpcbf-wrapper.sh"
+STANDARD="$ROOT_DIR/.phpcs.xml.dist"
+
+dedupe_files() {
+	awk 'NF && !seen[$0]++'
+}
+
+collect_files() {
+	local cmd=("$@")
+	"${cmd[@]}" | dedupe_files
+}
+
+base_ref=""
+if git rev-parse --verify origin/trunk >/dev/null 2>&1; then
+	base_ref="origin/trunk"
+elif git rev-parse --verify trunk >/dev/null 2>&1; then
+	base_ref="trunk"
+fi
+
+files="$(
+	{
+		if [ -n "$base_ref" ]; then
+			merge_base="$(git merge-base HEAD "$base_ref")"
+			git diff --name-only --diff-filter=ACMR "$merge_base"...HEAD -- '*.php'
+		fi
+		git diff --cached --name-only --diff-filter=ACMR -- '*.php'
+		git diff --name-only --diff-filter=ACMR -- '*.php'
+		git ls-files --others --exclude-standard -- '*.php'
+	} | dedupe_files
+)"
+
+if [ -z "$files" ]; then
+	echo "No changed PHP files found, skipping PHPCBF."
+	exit 0
+fi
+
+mapfile -t file_list <<<"$files"
+
+echo "Running PHPCBF on changed PHP files..."
+"$PHPCBF_WRAPPER" --standard="$STANDARD" "${file_list[@]}"