Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 120 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
name: CI

# Runs on every pull request, and on main after merge. Deliberately not tied to
# tags: release.yml only fires on a v*.*.* tag, which is far too late to learn
# that the coding standards or tests were broken.
on:
push:
branches:
- main
pull_request:

# A new push to a branch makes the in-flight run for that branch pointless.
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read

jobs:
php-lint:
name: PHP syntax (8.0) and coding standards
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v4

# The oldest PHP the plugin supports (Requires PHP in plugin.php,
# and the live server).
- uses: shivammathur/setup-php@v2
with:
php-version: '8.0'
coverage: none

- name: Cache Composer packages
uses: actions/cache@v4
with:
path: ~/.cache/composer/files
key: composer-${{ hashFiles('composer.lock') }}
restore-keys: composer-

# PHPUnit 12 requires PHP 8.3, so the platform check is relaxed
# here; PHPUnit is installed but only ever run in the tests job.
# phpcs and WPCS support PHP 8.0.
- name: Install PHP dependencies
run: composer install --no-interaction --prefer-dist --ignore-platform-req=php

- name: Validate composer.json
run: composer validate --no-check-publish

# Catches syntax PHP 8.0 cannot parse, which PHPCS does not.
- name: Check PHP 8.0 syntax
run: |
for file in plugin.php uninstall.php lib/functions/*.php; do
php -l "$file" || exit 1
done

- name: Check coding standards
run: composer lint

tests:
name: PHPUnit and node:test
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v4

# PHPUnit 12's minimum.
- uses: shivammathur/setup-php@v2
with:
php-version: '8.3'
coverage: none

- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'

- name: Cache Composer packages
uses: actions/cache@v4
with:
path: ~/.cache/composer/files
key: composer-${{ hashFiles('composer.lock') }}
restore-keys: composer-

- name: Install PHP dependencies
run: composer install --no-interaction --prefer-dist

- name: Install Node dependencies
run: npm ci

- name: Run tests
run: npm test

js:
name: package.json and formatting
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v4

- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'

- name: Install Node dependencies
run: npm ci

- name: Lint package.json
run: npm run lint:pkg-json

# wp-scripts format rewrites files in place and offers no --check
# mode, so run it and fail if the tree moved. It is the same
# command lint-staged runs on commit, so the hook and CI cannot
# disagree about what "formatted" means.
- name: Check formatting
run: |
npm run format
git diff --exit-code
1 change: 1 addition & 0 deletions .husky/pre-commit
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
npx lint-staged
11 changes: 11 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Written by ACF whenever a field group or post type is saved in the admin.
# Reformatting them would be undone on the next save and fail the CI check.
acf-json/

# Generated by commit-and-tag-version.
CHANGELOG.md

# Dependencies and build output.
node_modules/
vendor/
*.zip
41 changes: 22 additions & 19 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,28 +12,31 @@ A site-specific WordPress plugin for jasonchafin.com. It holds functionality tha

Neither `vendor/` nor `node_modules/` is committed. Run `composer install` and `npm install` first.

- PHP lint: `composer lint`, and auto-fix with `composer lint-fix`. There is no `phpcs.xml`, so pass the standard and paths yourself: `vendor/bin/phpcs --standard=WordPress plugin.php uninstall.php lib/`.
- Tests:
- JS/config checks: `npm run test:unit` (Node's built-in `node:test`, files in `tests/*.test.js`). Run one file with `node --test tests/<name>.test.js`.
- PHP: `composer test` or `npm run test:php` (PHPUnit, files in `tests/php/`). Run one test with `vendor/bin/phpunit --filter <name>`.
- The PHP tests run without WordPress. `tests/php/bootstrap.php` stubs only the WP functions the loaded feature files call, and records the calls. A new feature file under test needs its WP calls stubbed there and a `require_once` added.
- `npm test` still runs `lint-staged`, which has no config.
- Release zip: `npm run zip`. It packages only the `files` list in `package.json` into a `jc-core-functionality/` root folder. Run `composer install --no-dev` first, or dev dependencies end up in `vendor/` in the zip.
- Release: `npm run release` (commit-and-tag-version). It bumps `package.json`, `package-lock.json` and the `Version:` header in `plugin.php` (via `wp-plugin-version-updater.js`), updates `CHANGELOG.md` from Conventional Commits, and tags `vX.Y.Z`. Pushing the tag triggers `.github/workflows/release.yml`, which runs `composer install --no-dev` and `plugin-zip`, then attaches `jc-core-functionality.zip` to a GitHub release.
- Release candidates: `npm run release -- --prerelease rc` tags `vX.Y.Z-rc.N`. The workflow publishes `-rc` tags as GitHub prereleases. PUC reads `/releases/latest`, which skips prereleases, so installed sites never see RCs. To test an RC on staging, install its zip by hand. If an RC is ever published without the prerelease flag, every site with the updater is offered it.
- PHP lint: `composer lint` (ruleset in `phpcs.xml.dist`: WordPress standard, `jc` prefix, `jc-core-functionality` text domain, `tests/` excluded). Auto-fix with `composer lint-fix`. Lint one file with `vendor/bin/phpcs <file>`.
- Format: `npm run format` (wp-scripts/Prettier). `acf-json/` and `CHANGELOG.md` are excluded in `.prettierignore` because tools write them.
- Tests:
- JS/config checks: `npm run test:unit` (Node's built-in `node:test`, files in `tests/*.test.js`). Run one file with `node --test tests/<name>.test.js`.
- PHP: `composer test` or `npm run test:php` (PHPUnit, files in `tests/php/`). Run one test with `vendor/bin/phpunit --filter <name>`.
- The PHP tests run without WordPress. `tests/php/bootstrap.php` stubs only the WP functions the loaded feature files call, and records the calls. A new feature file under test needs its WP calls stubbed there and a `require_once` added.
- `npm test` runs both suites.
- PHPUnit 12 needs PHP 8.3, but the plugin supports 8.0 (`Requires PHP`). Keep plugin code 8.0-compatible; CI checks it with `php -l` on 8.0.
- Hooks and CI: `npm install` sets up a husky pre-commit hook that runs lint-staged (PHPCS on staged PHP, `wp-scripts format` on staged JS/JSON/YAML/Markdown). `.github/workflows/ci.yml` runs on every PR: PHP 8.0 syntax and PHPCS, tests on PHP 8.3, `lint:pkg-json` and a formatting check.
- Release zip: `npm run zip`. It packages only the `files` list in `package.json` into a `jc-core-functionality/` root folder. Run `composer install --no-dev` first, or dev dependencies end up in `vendor/` in the zip.
- Release: `npm run release` (commit-and-tag-version). It bumps `package.json`, `package-lock.json` and the `Version:` header in `plugin.php` (via `wp-plugin-version-updater.js`), updates `CHANGELOG.md` from Conventional Commits, and tags `vX.Y.Z`. Pushing the tag triggers `.github/workflows/release.yml`, which runs `composer install --no-dev` and `plugin-zip`, then attaches `jc-core-functionality.zip` to a GitHub release.
- Release candidates: `npm run release -- --prerelease rc` tags `vX.Y.Z-rc.N`. The workflow publishes `-rc` tags as GitHub prereleases. PUC reads `/releases/latest`, which skips prereleases, so installed sites never see RCs. To test an RC on staging, install its zip by hand. If an RC is ever published without the prerelease flag, every site with the updater is offered it.

## Architecture

- `plugin.php` is the only bootstrap. It defines `JC_DIR`, registers the update checker (below), adds a Settings link on the Plugins screen, and `include_once`s each file in `lib/functions/`. A new feature file needs its own include line added there. Nothing is namespaced or class-based: everything is global functions with a `jc_` prefix, hooked at file load.
- **Post types and custom fields live in `acf-json/`, not in PHP.** `general.php` redirects ACF's JSON load/save point to `JC_DIR . '/acf-json'` (and removes the theme's default load path). The `person` (People) and `quote` (Quotes) CPTs and their field groups are created by ACF from these JSON files. Edit them in the ACF admin UI so the JSON is rewritten, rather than by hand.
- Code depends on these ACF-defined objects by name. The `[quotes]` shortcode (`shortcodes.php`) queries post type `quote`. `general.php` registers the `subtitle` post meta for REST, and that name matches the ACF "Posts" field group.
- Block Bindings sources are registered in `general.php`: `jc/copyright` and `jc/user-data` (args `key` = `name|description|avatar` and `userId`). The settings page in `settings.php` is a static info page that documents features. Update it when you add user-facing features.
- **Updates come from GitHub releases** through plugin-update-checker (PUC), a Composer runtime dependency loaded from `vendor/`. It runs only in admin, cron and WP-CLI, and installs only the `jc-core-functionality.zip` release asset. The slug `jc-core-functionality` must match in `plugin.php`, `uninstall.php` (PUC's option, transient and cron names), `package.json` `name` and the release workflow. `tests/update-checker-config.test.js` enforces this.
- `uninstall.php` removes only PUC's data. By policy, `person` and `quote` content is never deleted.
- `gtm.php` hard-codes GTM container `GTM-WNP9BDSD`. `security-headers.php` builds a nonce-based CSP (`jc_csp_directives()`, filterable through `jc_csp_directives`) and sends it as Report-Only until `jc_csp_report_only` returns false. Admin and the Customizer preview are excluded. `csp-report.php` adds the `/wp-json/jc/v1/csp-report` endpoint, which logs violations as `[jc-csp]` lines in the PHP error log. Scripts must be printed through the script API to get the nonce; `tests/code-standards.test.js` rejects raw `<script>` tags in PHP. A new third-party host needs adding to the right directive in `jc_csp_directives()`, not to a single string.
- `plugin.php` is the only bootstrap. It defines `JC_DIR`, registers the update checker (below), adds a Settings link on the Plugins screen, and `include_once`s each file in `lib/functions/`. A new feature file needs its own include line added there. Nothing is namespaced or class-based: everything is global functions with a `jc_` prefix, hooked at file load.
- **Post types and custom fields live in `acf-json/`, not in PHP.** `general.php` redirects ACF's JSON load/save point to `JC_DIR . '/acf-json'`, and deliberately removes the theme's default load path, so the plugin is the only source of the content model. The `person` (People) and `quote` (Quotes) CPTs and their field groups are created by ACF from these JSON files. Edit them in the ACF admin UI so the JSON is rewritten, rather than by hand.
- Code depends on these ACF-defined objects by name. The `[quotes]` shortcode (`shortcodes.php`) queries post type `quote`. `general.php` registers the `subtitle` post meta for REST, and that name matches the ACF "Posts" field group.
- Block Bindings sources are registered in `general.php`: `jc/copyright` and `jc/user-data` (args `key` = `name|description|avatar` and `userId`). The settings page in `settings.php` is a static info page that documents features. Update it when you add user-facing features.
- **Updates come from GitHub releases** through plugin-update-checker (PUC), a Composer runtime dependency loaded from `vendor/`. It runs only in admin, cron and WP-CLI, and installs only the `jc-core-functionality.zip` release asset. The slug `jc-core-functionality` must match in `plugin.php`, `uninstall.php` (PUC's option, transient and cron names), `package.json` `name` and the release workflow. `tests/update-checker-config.test.js` enforces this.
- `uninstall.php` removes only PUC's data. By policy, `person` and `quote` content is never deleted.
- `gtm.php` loads GTM container `GTM-WNP9BDSD` by default (override with a `JC_GTM_ID` constant or the `jc_gtm_container_id` filter; `''` or an invalid ID disables it), and skips users with `manage_options`. `security-headers.php` builds a nonce-based CSP (`jc_csp_directives()`, filterable through `jc_csp_directives`) and sends it as Report-Only until `jc_csp_report_only` returns false. Admin and the Customizer preview are excluded. `csp-report.php` adds the `/wp-json/jc/v1/csp-report` endpoint, which logs violations as `[jc-csp]` lines in the PHP error log. Scripts must be printed through the script API to get the nonce; `tests/code-standards.test.js` rejects raw `<script>` tags in PHP. A new third-party host needs adding to the right directive in `jc_csp_directives()`, not to a single string.

## Gotchas

- The release zip is built from the `files` list in `package.json`. A new top-level directory won't ship unless it's added there.
- If `vendor/` is missing from the zip, the updater does nothing and shows no error, because of the `file_exists()` guard.
- Every PHP file starts with an `ABSPATH` guard, every translation call uses the `jc-core-functionality` text domain, and dates use `wp_date()`, not `date()`. `tests/code-standards.test.js` enforces all three, so a new feature file needs the guard.
- The release zip is built from the `files` list in `package.json`. A new top-level directory won't ship unless it's added there.
- If `vendor/` is missing from the zip, the updater does nothing and shows no error, because of the `file_exists()` guard.
- Every PHP file starts with an `ABSPATH` guard, every translation call uses the `jc-core-functionality` text domain, and dates use `wp_date()`, not `date()`. `tests/code-standards.test.js` enforces all three, so a new feature file needs the guard.
42 changes: 26 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Custom functionality for the [Jason Chafin](https://jasonchafin.com) WordPress s

## Requirements

- [Advanced Custom Fields Pro](https://www.advancedcustomfields.com/pro/), declared with `Requires Plugins`. WordPress won't activate this plugin without it.
- [Advanced Custom Fields Pro](https://www.advancedcustomfields.com/pro/), declared with `Requires Plugins`. WordPress won't activate this plugin without it.

## Installation

Expand All @@ -26,19 +26,19 @@ Once it's installed, updates come from this repository's GitHub releases through

Defined as ACF JSON in `acf-json/`, which the plugin registers as ACF's load and save path:

- **People** (`person`), with a Contact Info field group: name, title, phone, email, website, address, bio and photo.
- **Quotes** (`quote`).
- **Posts** get a `subtitle` field. It's also registered as post meta and exposed in the REST API.
- **People** (`person`), with a Contact Info field group: name, title, phone, email, website, address, bio and photo.
- **Quotes** (`quote`).
- **Posts** get a `subtitle` field. It's also registered as post meta and exposed in the REST API.

### Shortcode

- `[quotes]` shows one random quote title from the Quotes post type.
- `[quotes]` shows one random quote title from the Quotes post type.

### Block bindings

| Source | Arguments | Value |
| --- | --- | --- |
| `jc/copyright` | none | `© <current year>` in the site's timezone |
| Source | Arguments | Value |
| -------------- | --------------------------------------------------- | ------------------------------------------- |
| `jc/copyright` | none | `© <current year>` in the site's timezone |
| `jc/user-data` | `key` (`name`, `description` or `avatar`), `userId` | The user's display name, bio, or avatar URL |

Example:
Expand All @@ -51,15 +51,23 @@ Example:

### Site-wide

- **Google Tag Manager:** container snippets in `<head>` and right after `<body>`.
- **Security headers** on front-end responses: `Referrer-Policy`, `X-Content-Type-Options`, `X-Frame-Options`, `Permissions-Policy` and a Content Security Policy (see below).
- **XML-RPC disabled:** all methods are removed and the RSD link is taken out of `<head>`, to block brute-force login attempts through `/xmlrpc.php`.
- **Google Tag Manager:** container snippets in `<head>` and right after `<body>`. They're not printed for administrators (`manage_options`), so your own visits stay out of analytics. The container defaults to the live site's. Change it or turn it off in `wp-config.php`:

```php
define( 'JC_GTM_ID', 'GTM-XXXXXXX' ); // a different container
define( 'JC_GTM_ID', '' ); // no GTM, e.g. on staging
```

The `jc_gtm_container_id` filter does the same. Anything that isn't a valid `GTM-…` ID turns GTM off.

- **Security headers** on front-end responses: `Referrer-Policy`, `X-Content-Type-Options`, `X-Frame-Options`, `Permissions-Policy` and a Content Security Policy (see below).
- **XML-RPC disabled:** all methods are removed and the RSD link is taken out of `<head>`, to block brute-force login attempts through `/xmlrpc.php`.

## Content Security Policy

Scripts are trusted by a nonce that changes on every request, not by a host list. WordPress adds the nonce to every script printed through its script API (enqueued scripts, inline scripts, the import map and speculation rules). `'strict-dynamic'` extends that trust to the scripts they load, such as GTM and GA4. Styles still allow `'unsafe-inline'`, because block styles are printed inline.

**The policy currently ships as `Content-Security-Policy-Report-Only`.** Browsers report what it *would* block without blocking it. In the meantime a minimal policy is enforced (`object-src 'none'; base-uri 'self'; frame-ancestors 'self'`).
**The policy currently ships as `Content-Security-Policy-Report-Only`.** Browsers report what it _would_ block without blocking it. In the meantime a minimal policy is enforced (`object-src 'none'; base-uri 'self'; frame-ancestors 'self'`).

Reports are sent to `/wp-json/jc/v1/csp-report` and written to the PHP error log, one JSON line each, prefixed `[jc-csp]`:

Expand Down Expand Up @@ -95,14 +103,16 @@ Deleting the plugin removes only the update checker's stored data. **People and
## Development

```sh
composer install && npm install
composer install && npm install # npm install also sets up the pre-commit hook

composer test # PHPUnit (tests/php/)
npm run test:unit # node:test (tests/*.test.js)
npm test # node:test (tests/*.test.js), then PHPUnit (tests/php/)
composer lint # PHPCS, WordPress Coding Standards (phpcs.xml.dist)
composer lint-fix # auto-fix what PHPCS can
npm run format # wp-scripts format for JS, JSON, YAML and Markdown
npm run release # bump version, update CHANGELOG.md, tag
```

Pushing a `vX.Y.Z` tag builds the release zip and publishes it as a GitHub release. See [ROADMAP.md](ROADMAP.md) for planned work.
A pre-commit hook (husky + lint-staged) runs PHPCS on staged PHP and `wp-scripts format` on staged JS, JSON, YAML and Markdown. CI runs on every pull request: PHP 8.0 syntax and coding standards, the test suites on PHP 8.3 (PHPUnit 12's minimum), and a formatting check. Pushing a `vX.Y.Z` tag builds the release zip and publishes it as a GitHub release. See [ROADMAP.md](ROADMAP.md) for planned work.

## License

Expand Down
Loading
Loading