feat(headless-documents): add a versioned document store plugin

.changeset/headless-documents-initial.md

@@ -0,0 +1,5 @@
+---
+"@wpengine/headless-documents-wordpress-plugin": minor
+---
+
+feat: initial release of Headless Documents, a versioned JSON document store with REST routes that reject stale writes with a 409.

.github/dependabot.yaml

@@ -10,6 +10,14 @@ updates:
         update-types: ["version-update:semver-major"]
 
   # composer (plugins)
+  - package-ecosystem: "composer"
+    directory: "/plugins/headless-documents"
+    schedule:
+      interval: "weekly"
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
+
   - package-ecosystem: "composer"
     directory: "/plugins/hwp-cli"
     schedule:
@@ -51,6 +59,14 @@ updates:
         update-types: ["version-update:semver-major"]
 
   # docker (Dockerfiles)
+  - package-ecosystem: "docker"
+    directory: "/plugins/headless-documents/.docker"
+    schedule:
+      interval: "weekly"
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
+
   - package-ecosystem: "docker"
     directory: "/plugins/hwp-previews/.docker"
     schedule:
@@ -68,6 +84,14 @@ updates:
         update-types: ["version-update:semver-major"]
 
   # docker (docker-compose)
+  - package-ecosystem: "docker"
+    directory: "/plugins/headless-documents"
+    schedule:
+      interval: "weekly"
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
+
   - package-ecosystem: "docker"
     directory: "/plugins/hwp-previews"
     schedule:

docs/index.md

@@ -14,6 +14,7 @@ The toolkit includes several WordPress plugins to enhance the headless experienc
 | Plugin | Description |
 |--------|-------------|
 | [wpgraphql-logging](../plugins/wpgraphql-logging/) | Logging for WPGraphQL requests with granular lifecycle events and Monolog integration. |
+| [headless-documents](../plugins/headless-documents/) | Store your app's JSON documents in WordPress over REST, with versioned writes that reject stale updates. |
 | [hwp-previews](../plugins/hwp-previews/) | Headless Previews solution for WordPress: fully configurable preview URLs via the settings page which is framework agnostic. |
 
 ## Examples

llms.txt

@@ -6,6 +6,7 @@
 
 WordPress plugins for the Headless WordPress Toolkit. Each plugin is paired with an NPM package.
 
+- [Headless Documents](https://github.com/wpengine/hwptoolkit/blob/main/plugins/headless-documents/README.md)
 - [HWP CLI Plugin](https://github.com/wpengine/hwptoolkit/blob/main/plugins/hwp-cli/README.md)
 - [HWP Previews](https://github.com/wpengine/hwptoolkit/blob/main/plugins/hwp-previews/README.md)
 - [WPGraphQL Debug Extensions](https://github.com/wpengine/hwptoolkit/blob/main/plugins/wpgraphql-debug-extensions/README.md)

plugins/README.md

@@ -6,6 +6,7 @@ WordPress plugins for the Headless WordPress Toolkit. Each plugin is paired with
 
 | Plugin | Description |
 |--------|-------------|
+| [headless-documents](./headless-documents/README.md) | Store your app's JSON documents in WordPress over REST, with versioned writes that reject stale updates. |
 | [hwp-previews](./hwp-previews/README.md) | Headless Previews solution for WordPress: fully configurable preview URLs via the settings page which is framework agnostic. |
 | [wpgraphql-webhooks](./wpgraphql-webhooks/README.md) | Extends WPGraphQL to support webhook subscriptions and dispatching for headless WordPress environments. |
 | [wpgraphql-logging](./wpgraphql-logging/README.md) | Logging for WPGraphQL requests with granular lifecycle events and Monolog integration. |

plugins/headless-documents/.distignore

@@ -0,0 +1,36 @@
+/.devcontainer
+/.git
+/.github
+/.idea
+/.log
+/.vscode
+/.wordpress-org
+/bin
+/docker
+/docker-output
+/docs
+/img
+/phpstan
+/plugin-build
+/tests
+
+.coveralls.yml
+.distignore
+.dockerignore
+.DS_Store
+.env
+.env.dist
+.gitattributes
+.gitignore
+.phpcs.xml
+.phpcs.xml.dist
+.travis.yml
+CHANGELOG.md
+codeception.dist.yml
+codeception.yml
+composer.json
+composer.lock
+docker-compose.yml
+phpstan.neon.dist
+README.md
+schema.graphql

plugins/headless-documents/.docker/.env.ci

@@ -0,0 +1,59 @@
+PLUGIN_SLUG=headless-documents
+
+# Configure these to match your existing testing environment or the one you want to create with Docker.
+## Usually, these values should match the ones in the `wp-config.php` file.
+## If using Local by Flywheel, you can `open AdminerEvo` and find the values in the URL: `http://localhost:{DB_PORT}/?username={DB_USER}&db={DB_NAME}`
+## NOTE: Codeception may modify or the database during testing. If you want to preserve your local data, create a new database and use that for the `DB_NAME`.
+DB_NAME=wordpress
+DB_HOST=mysql
+DB_USER=root
+DB_PASSWORD=password
+DB_PORT=3306
+
+# The local path to the WordPress root directory, the one containing the wp-load.php file.
+## This can be a relative path from the directory that contains the codeception.yml file, or an absolute path.
+## If you are using Local by Flywheel, you can find the path in the Local by Flywheel app under the site's settings.
+WORDPRESS_ROOT_DIR="/var/www/html"
+
+# This table prefix used by the WordPress site, and in Acceptance tests.
+WORDPRESS_TABLE_PREFIX=wp_
+
+# The URL and domain of the WordPress site, and in Acceptance tests.
+## If the port is in use, you can change it to a different port.
+WORDPRESS_URL=http://localhost
+WORDPRESS_DOMAIN=localhost
+WORDPRESS_ADMIN_PATH=/wp-admin
+
+# The username and password of the administrator user of the WordPress site, and in Acceptance tests.
+WORDPRESS_ADMIN_USER=admin
+WORDPRESS_ADMIN_PASSWORD=password
+WORDPRESS_ADMIN_EMAIL=admin@example.com
+
+# Tests will require a MySQL database to run.
+# Do not use a database that contains important data!
+WORDPRESS_DB_HOST=${DB_HOST}
+WORDPRESS_DB_USER=${DB_USER}
+WORDPRESS_DB_PASSWORD=${DB_PASSWORD}
+WORDPRESS_DB_NAME=${DB_NAME}
+WORDPRESS_DB_PORT=${DB_PORT}
+
+# WPUnit tests will use these variables instead.
+# By default this is the same as WordPress
+TEST_DB_HOST=${WORDPRESS_DB_HOST}
+TEST_DB_USER=${WORDPRESS_DB_USER}
+TEST_DB_PASSWORD=${WORDPRESS_DB_PASSWORD}
+TEST_DB_NAME=${WORDPRESS_DB_NAME}
+TEST_DB_PORT=${WORDPRESS_DB_PORT}
+# The Integration suite will use this table prefix for the WordPress tables.
+TEST_TABLE_PREFIX=test_
+
+# The DSN used by Acceptance tests.
+TEST_DB_DSN="mysql:host=${TEST_DB_HOST};port=${TEST_DB_PORT};dbname=${TEST_DB_NAME}"
+
+# The following variables are used to determine test behavior.
+
+# Include 3rd party plugins (e.g. WooCommerce) in the tests.
+# Skips recreating the database before running the tests.
+SKIP_DB_CREATE=false
+# Skips configuring the WordPress installation
+SKIP_WP_SETUP=false

plugins/headless-documents/.docker/Dockerfile

@@ -0,0 +1,84 @@
+###############################################################################
+# Pre-configured WordPress Installation w/ Headless Documents Plugin
+# For testing only, use in production not recommended. #
+###############################################################################
+
+# Use build args to get the right wordpress + php image
+ARG WP_VERSION
+ARG PHP_VERSION
+
+FROM wordpress:${WP_VERSION:-6.9}-php${PHP_VERSION:-8.2}
+
+# Needed to specify the build args again after the FROM command.
+ARG WP_VERSION
+ARG PHP_VERSION
+
+# Save the build args for use by the runtime environment
+ENV WP_VERSION=${WP_VERSION}
+ENV PHP_VERSION=${PHP_VERSION}
+
+SHELL [ "/bin/bash", "-c" ]
+
+# Install required packages
+RUN apt-get update && \
+    apt-get -y install \
+    git \
+    ssh \
+    tar \
+    gzip \
+    mariadb-client \
+    net-tools
+
+# Needed for Codeception WPDB test integration.
+RUN docker-php-ext-install pdo pdo_mysql
+
+# Install XDebug 3
+RUN if [[ $PHP_VERSION == 7* ]]; then pecl install xdebug-3.1.5; else pecl install xdebug; fi \
+    && mkdir -p /usr/local/etc/php/conf.d/disabled \
+    && echo "zend_extension=xdebug" > /usr/local/etc/php/conf.d/disabled/docker-php-ext-xdebug.ini \
+    && echo "xdebug.mode=develop,debug,coverage" >> /usr/local/etc/php/conf.d/disabled/docker-php-ext-xdebug.ini \
+    && echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/disabled/docker-php-ext-xdebug.ini \
+    && echo "xdebug.client_host=host.docker.internal" >> /usr/local/etc/php/conf.d/disabled/docker-php-ext-xdebug.ini \
+    && echo "xdebug.client_port=9003" >> /usr/local/etc/php/conf.d/disabled/docker-php-ext-xdebug.ini \
+    && echo "xdebug.max_nesting_level=512" >> /usr/local/etc/php/conf.d/disabled/docker-php-ext-xdebug.ini \
+    ;
+
+# Set xdebug configuration off by default. Set USING_XDEBUG=1 in the runtime environment to enable it.
+ENV USING_XDEBUG=0
+
+# Install PCOV
+# This is needed for Codeception / PHPUnit to track code coverage
+RUN apt-get install zip unzip -y \
+    && pecl install pcov
+
+# Install Dockerize
+ENV DOCKERIZE_VERSION=v0.7.0
+RUN curl -L -O https://github.com/jwilder/dockerize/releases/download/$DOCKERIZE_VERSION/dockerize-linux-amd64-$DOCKERIZE_VERSION.tar.gz \
+    && tar -C /usr/local/bin -xzvf dockerize-linux-amd64-$DOCKERIZE_VERSION.tar.gz \
+    && rm dockerize-linux-amd64-$DOCKERIZE_VERSION.tar.gz
+
+# Install composer
+COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer
+RUN chmod +x /usr/local/bin/composer
+
+# Install WP-CLI (pinned to latest stable to avoid nightly incompatibilities)
+ENV WP_CLI_VERSION=2.12.0
+RUN curl -L -O https://github.com/wp-cli/wp-cli/releases/download/v${WP_CLI_VERSION}/wp-cli-${WP_CLI_VERSION}.phar \
+    && chmod +x wp-cli-${WP_CLI_VERSION}.phar \
+    && mv wp-cli-${WP_CLI_VERSION}.phar /usr/local/bin/wp
+
+# Install nvm, Node.js, and npm
+ENV NVM_DIR=/usr/local/nvm
+ENV NODE_VERSION=20
+
+RUN mkdir -p $NVM_DIR
+RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash \
+    && . $NVM_DIR/nvm.sh \
+    && nvm install $NODE_VERSION \
+    && nvm use $NODE_VERSION \
+    && nvm alias default $NODE_VERSION \
+    && npm install -g npm
+
+# Setup the container for testing
+COPY init-docker.sh /usr/local/bin/
+RUN chmod +x /usr/local/bin/init-docker.sh

plugins/headless-documents/.docker/init-docker.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# Exit if any command fails.
+set -e
+
+# Wait for the database
+dockerize -wait tcp://"${WORDPRESS_DB_HOST}":3306 -timeout 1m
+
+# Get the current user
+
+cd "$WORDPRESS_ROOT_DIR/wp-content/plugins/$PLUGIN_SLUG"
+
+# Load NVM
+source $NVM_DIR/nvm.sh
+nvm use $NODE_VERSION
+
+# Setup the test environment
+chmod +x ./bin/install-test-env.sh
+
+bash -c "./bin/install-test-env.sh"
+
+echo "Setting permissions"
+chmod -R 777 "$WORDPRESS_ROOT_DIR/wp-content/plugins/$PLUGIN_SLUG"
+
+# Go back to the root directory
+cd "$WORDPRESS_ROOT_DIR"

plugins/headless-documents/.editorconfig

@@ -0,0 +1,18 @@
+# This file is for unifying the coding style for different editors and IDEs
+# editorconfig.org
+
+# WordPress Coding Standards
+# https://make.wordpress.org/core/handbook/coding-standards/
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = tab
+
+
+[*.md]
+trim_trailing_whitespace = false

plugins/headless-documents/.env.dist

@@ -0,0 +1,65 @@
+PLUGIN_SLUG=headless-documents
+
+# Configure these to match your existing testing environment or the one you want to create with Docker.
+## Usually, these values should match the ones in the `wp-config.php` file.
+## If using Local by Flywheel, you can `open AdminerEvo` and find the values in the URL: `http://localhost:{DB_PORT}/?username={DB_USER}&db={DB_NAME}`
+## NOTE: Codeception may modify or the database during testing. If you want to preserve your local data, create a new database and use that for the `DB_NAME`.
+DB_NAME=wordpress
+# localhost creates issues with wp config create command
+DB_HOST=127.0.0.1
+DB_USER=root
+DB_PASSWORD=password
+DB_PORT=3306
+
+# The local path to the WordPress root directory, the one containing the wp-load.php file.
+## This can be a relative path from the directory that contains the codeception.yml file, or an absolute path.
+## If you are using Local by Flywheel, you can find the path in the Local by Flywheel app under the site's settings.
+WORDPRESS_ROOT_DIR="/tmp/wordpress"
+
+# This table prefix used by the WordPress site, and in Acceptance tests.
+WORDPRESS_TABLE_PREFIX=wp_
+
+# The URL and domain of the WordPress site, and in Acceptance tests.
+## If the port is in use, you can change it to a different port.
+WORDPRESS_URL=http://localhost
+WORDPRESS_DOMAIN=localhost
+WORDPRESS_ADMIN_PATH=/wp-admin
+
+# The username and password of the administrator user of the WordPress site, and in Acceptance tests.
+WORDPRESS_ADMIN_USER=admin
+WORDPRESS_ADMIN_PASSWORD=password
+WORDPRESS_ADMIN_EMAIL=admin@example.com
+
+# Tests will require a MySQL database to run.
+# Do not use a database that contains important data!
+WORDPRESS_DB_HOST=${DB_HOST}
+WORDPRESS_DB_USER=${DB_USER}
+WORDPRESS_DB_PASSWORD=${DB_PASSWORD}
+WORDPRESS_DB_NAME=${DB_NAME}
+WORDPRESS_DB_PORT=${DB_PORT}
+
+# WPUnit tests will use these variables instead.
+# By default this is the same as WordPress
+TEST_DB_HOST=${WORDPRESS_DB_HOST}
+TEST_DB_USER=${WORDPRESS_DB_USER}
+TEST_DB_PASSWORD=${WORDPRESS_DB_PASSWORD}
+TEST_DB_NAME=${WORDPRESS_DB_NAME}
+TEST_DB_PORT=${WORDPRESS_DB_PORT}
+# The Integration suite will use this table prefix for the WordPress tables.
+TEST_TABLE_PREFIX=test_
+
+# The DSN used by Acceptance tests.
+TEST_DB_DSN="mysql:host=${TEST_DB_HOST};port=${TEST_DB_PORT};dbname=${TEST_DB_NAME}"
+
+# The following variables are used to determine test behavior.
+
+# Include 3rd party plugins (e.g. WooCommerce) in the tests.
+INCLUDE_EXTENSIONS=true
+# Skips recreating the database before running the tests.
+SKIP_DB_CREATE=false
+# Skips configuring the WordPress installation
+SKIP_WP_SETUP=false
+# Skips cleanup after the test suite run.
+SKIP_TESTS_CLEANUP=true
+# The default Codeception suite to run.
+SUITES=wpunit