feat(faustwp): add an opt-in versioned document store with conflict detection by josephfusco · Pull Request #2674 · wpengine/faustjs

josephfusco · 2026-10-20T13:36:45Z

Adds an opt-in document store to FaustWP. Apps save JSON documents in collections over REST, and a write based on an old version gets a 409 instead of silently overwriting.

sequenceDiagram
  participant App as Your app
  participant WP as FaustWP
  participant DB as Table
  App->>WP: PUT, version 3
  WP->>DB: UPDATE if version 3
  alt updated
    WP-->>App: 200, version 4
  else someone saved first
    WP-->>App: 409, current doc
  end

Method	Route (`faust/v1/collections/{collection}/documents`)	Does
`GET`	`/{id}`	Read a document
`PUT`	`/{id}`	Create (version `0`) or update (current version)
`DELETE`	`/{id}?version=N`	Delete the current version
`GET`	`?limit=&cursor=`	List newest first
`POST`		Add with a generated ID

Plugin: the routes above, the wp_faust_documents table (created when enabled, dropped on uninstall), faust_document_saved/faust_document_deleted actions and a read-only Tools → Faust Documents screen.
Docs: a "Store app data with conflict detection" section in the write-data guide.
Example: examples/next/document-store with a Team notes page (two tabs, conflict and merge) and a Waitlist page (add, list, remove).

It's off unless the faust_enable_document_store filter returns true, and on WordPress 7.0, 10 concurrent creates and 10 concurrent PUTs over HTTP each produced exactly one success and nine 409s. The PHPStan memory bump and configurable Docker ports could move to their own PR.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: Assisting with designing and implementing the document store and its table, writing the PHPUnit tests and docs, and testing the routes and concurrent writes in a local WordPress.

…etection

PHPStan already peaks at about 990 MB on canary, so any new code pushes it past the 1 GB limit and the lint job crashes.

…t store example

…tore example

…p waits for MySQL

…ample

…ument store README

…n port

…block

Documents move from a private post type with one meta row to wp_faustwp_documents, with a unique key on collection, owner and slug. Creates rely on the unique key instead of cleaning up duplicate posts, updates are a single conditional UPDATE on the version, and uninstall drops the table.

…le with its site

…comments

Routes move to faustwp/v1/collections/<collection>/documents/<id>, responses use collection and id instead of slug, and the table column is renamed to document_id. This matches the collection and document terms used by Firestore, Appwrite and PocketBase.

…ve/delete actions Adds GET and POST on a collection (cursor-paginated list, and create with a generated ID), DELETE on a document with a required version, created and modified timestamps on every document, and faustwp_document_saved and faustwp_document_deleted actions.

…t actions

…ments

…, table and capabilities The REST namespace is faust/v1, the table is wp_faust_documents, and hooks, capabilities, options and error codes start with faust_. The plugin's existing faustwp_ hooks and faustwp/v1 routes are unchanged.

Copilot

🟡 Changes recommended

Reused versions allow stale clients to overwrite or delete recreated documents, undermining the core conflict-detection guarantee.

8 open issues

What changed in this PR

Adds an opt-in document store to FaustWP, providing REST-based app data persistence with version checks for conflicting writes.

Changes:

Adds document storage, REST endpoints, capability checks, lifecycle cleanup, and a read-only admin screen.
Adds integration tests and usage documentation.
Adds a Next.js example demonstrating shared notes, conflict merging, and waitlist management.

File	Description
plugins/faustwp/uninstall.php	Removes document tables on uninstall.
plugins/faustwp/tests/integration/DocumentStoreTests.php	Tests storage, REST access, and conflicts.
plugins/faustwp/tests/integration/DocumentAdminTests.php	Tests admin access and rendering.
plugins/faustwp/includes/documents/functions.php	Implements storage and version checks.
plugins/faustwp/includes/documents/callbacks.php	Registers REST routes and lifecycle hooks.
plugins/faustwp/includes/documents/admin.php	Adds read-only document inspection.
plugins/faustwp/faustwp.php	Loads document-store modules.
plugins/faustwp/docker-compose.yml	Makes development ports configurable.
plugins/faustwp/composer.json	Raises PHPStan’s memory limit.
plugins/faustwp/.phpcs.xml.dist	Allows the new hook prefix.
examples/next/document-store/styles/globals.css	Styles example forms and conflicts.
examples/next/document-store/scripts/stop-wordpress.sh	Stops the example’s WordPress environment.
examples/next/document-store/scripts/setup-wordpress.sh	Sets up WordPress and service credentials.
examples/next/document-store/README.md	Documents setup and example workflows.
examples/next/document-store/pages/waitlist.js	Demonstrates adding, listing, and deleting documents.
examples/next/document-store/pages/index.js	Demonstrates shared editing and conflict recovery.
examples/next/document-store/pages/api/collections/[collection]/documents/index.js	Proxies collection requests.
examples/next/document-store/pages/api/collections/[collection]/documents/[id].js	Proxies individual document requests.
examples/next/document-store/pages/_app.js	Loads shared styles.
examples/next/document-store/package.json	Defines example dependencies and scripts.
examples/next/document-store/mu-plugins/enable-document-store.php	Enables the store locally.
examples/next/document-store/lib/wordpress.js	Forwards authenticated requests to WordPress.
examples/next/document-store/lib/mergeDocuments.test.mjs	Tests three-way merging.
examples/next/document-store/lib/mergeDocuments.mjs	Implements merging and conflict resolution.
examples/next/document-store/docker-compose.override.yml	Configures the local example environment.
examples/next/document-store/.env.local.sample	Documents connection and credential settings.
docs/how-to/write-data-to-wordpress/index.md	Documents document-store APIs and usage.
.gitignore	Excludes the example’s package lockfile.

_{Review effort: Balanced}

+			return { ok: false };
+		}
+
+		const theirs = { ...json.data.document, data: withDefaults(json.data.document?.data) };


+	async function load(cursor) {
+		const query = cursor ? `&cursor=${cursor}` : '';
+		const { status, json } = await request('GET', `${COLLECTION_URL}?limit=${PAGE_SIZE}${query}`);
+		if (status !== 200) {
+			setMessage(`Could not load (${status}): ${json.message}`);
+			return;
+		}
+		setSignups(cursor ? [...signups, ...json.documents] : json.documents);
+		setNextCursor(json.next_cursor);
+		setMessage(json.documents.length || cursor ? '' : 'No signups yet.');
+	}


+			'collection'   => $collection,
+			'owner_id'     => 0,
+			'document_id'  => $id,
+			'version'      => 1,


…s from the route Deleting a document now keeps its row as a tombstone with a bumped version, and creating it again continues from there, so a client holding a version from before the delete gets a 409 instead of overwriting the new document. Collection names and document IDs are read from the route only, since WordPress lets body and query parameters take precedence, and the route patterns are case-sensitive even though WordPress matches routes case-insensitively.

Keep the database between stop and setup, merge "__proto__" fields as fields, keep the version when a conflict comes from a deleted document, lock the form while a save is in flight, and block adding and removing while the waitlist is loading.

josephfusco added 5 commits October 20, 2026 09:36

feat(faustwp): add an opt-in versioned document store with conflict d…

b9d8bfd

…etection

fix(faustwp): return empty objects in documents as objects

ffe318f

test(faustwp): cover concurrent creates in the document store

835d32c

docs: show the full conflict response for document writes

0fbc7cc

ci(faustwp): give PHPStan 2 GB of memory

138c61e

PHPStan already peaks at about 990 MB on canary, so any new code pushes it past the 1 GB limit and the lint job crashes.

josephfusco marked this pull request as ready for review October 20, 2026 13:47

josephfusco requested review from a team and colinmurphy as code owners October 20, 2026 13:47

josephfusco added 12 commits October 20, 2026 10:11

docs(examples): add a document store example that runs WordPress locally

630bca7

docs(examples): show WordPress errors that aren't JSON in the documen…

ad9248a

…t store example

docs(examples): explain how to work on the plugin with the document s…

13dd94e

…tore example

fix(examples): hide the expected errors while the document store setu…

8528b1a

…p waits for MySQL

feat(faustwp): record when and by whom each document was last saved

3d7ec21

feat(faustwp): list stored documents under Tools → Faust Documents

53a0a1c

feat(examples): add a three-way merge helper to the document store ex…

3ab72b9

…ample

feat(examples): merge concurrent edits in the document store example

39b9a89

docs(examples): describe merging and field-level conflicts in the doc…

57587c2

…ument store README

fix(examples): label conflicting fields with their form labels

64ac670

fix(examples): point the document store example's WordPress at its ow…

e284813

…n port

fix(faustwp): show document JSON without per-line code backgrounds

6bcbcb2

This was referenced Oct 22, 2026

RFC: Use WordPress as your app's data store wpengine/hwptoolkit#817

Open

feat(faustwp): versioned document store with conflict detection #2562

Closed

josephfusco added [Type] Feature A new feature within an existing module [Area] WordPress Plugin Issues for the Faust.js WordPress plugin Needs Discussion Anything that needs a discussion/agreement labels Oct 20, 2026

josephfusco marked this pull request as draft October 20, 2026 15:07

josephfusco added 4 commits October 20, 2026 11:09

docs(faustwp): mention the Tools screen in the document post type doc…

84d5414

…block

perf(faustwp): list documents without a slug lookup per row

fe4f36a

fix(faustwp): retry a failed documents table install and drop the tab…

3456726

…le with its site

josephfusco added 7 commits October 20, 2026 11:23

docs(faustwp): clarify the documents schema version and shared owner …

087677c

…comments

docs: describe listing, adding and deleting documents and the documen…

178c0fc

…t actions

feat(examples): add a waitlist page that adds, lists and removes docu…

0510d71

…ments

fix(faustwp): never report a 1970 creation date after a racing delete

3a9d0ef

josephfusco marked this pull request as ready for review October 20, 2026 16:12

josephfusco requested a balanced review from Copilot October 20, 2026 16:33

Copilot started reviewing on behalf of josephfusco October 20, 2026 16:33

View session

Copilot AI reviewed Oct 20, 2026

View reviewed changes

josephfusco added 2 commits October 20, 2026 12:45

josephfusco marked this pull request as draft October 20, 2026 17:18

josephfusco closed this Oct 21, 2026

Navigation Menu

Repository navigation

feat(faustwp): add an opt-in versioned document store with conflict detection - #2674

feat(faustwp): add an opt-in versioned document store with conflict detection#2674
josephfusco wants to merge 30 commits into
canaryfrom
feat/2562-document-store

josephfusco commented Oct 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

josephfusco commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

josephfusco commented Oct 20, 2026 •

edited

Loading