Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
fd63dbe
fix(encryptor): reject payloads shorter than the IV plus a full tag
aryanjasala Oct 1, 2026
c5b8340
test(encryptor): cover the fail-closed path when OpenSSL is missing
aryanjasala Oct 1, 2026
7f593d1
fix(transients): hash names past the 172-character transient limit
aryanjasala Oct 1, 2026
3210a02
test: cover the remaining Cache, Timer and legacy-core registrar paths
aryanjasala Oct 1, 2026
40335db
chore(phpstan): raise static analysis to level 6
aryanjasala Oct 1, 2026
8b01539
ci: run on Node 24, pin the docs action and stop persisting credentials
aryanjasala Oct 1, 2026
421494e
ci: rebuild Dependabot auto-merge on the pull_request pattern
aryanjasala Oct 1, 2026
5b166f1
build: trim the dist archive and complete the Packagist metadata
aryanjasala Oct 1, 2026
835e05a
docs: make the install instructions Packagist-first
aryanjasala Oct 1, 2026
8187acb
docs(changelog): complete the unreleased 2.0.0 entry
aryanjasala Oct 1, 2026
d426513
fix(sync-ai): prune only generated legacy files, and log the real path
aryanjasala Oct 1, 2026
2d1c3c6
build: alias dev-main as 2.x-dev
aryanjasala Oct 1, 2026
73219ad
build(deps-dev): patch the PHPCS toolchain security advisories
aryanjasala Oct 1, 2026
67d93c0
docs(maintainers): document the release procedure
aryanjasala Oct 1, 2026
261244f
docs: add a security policy for the public package
aryanjasala Oct 1, 2026
cb370b9
build(deps-dev): bump @wordpress/env to 11.16.0
aryanjasala Oct 1, 2026
3b376b8
fix(sync-ai): discover site-repo packages through the vendored framework
aryanjasala Oct 1, 2026
d256dff
test(asset-loader): cover a malformed manifest on the pre-6.8 fallback
aryanjasala Oct 1, 2026
cc487f0
fix(block): fall back to the block name when the build dir is missing
aryanjasala Oct 1, 2026
9e3ded1
build(deps-dev): update PHPStan, the WordPress stubs and wp-phpunit
aryanjasala Oct 1, 2026
755ccc3
ci: test WordPress 7.1 and correct the action version comments
aryanjasala Oct 1, 2026
ba80c92
ci(docs): bump actions/deploy-pages to v5.0.1
aryanjasala Oct 1, 2026
45f4162
docs(changelog): list the block and sync-ai fixes, correct the upgrad…
aryanjasala Oct 1, 2026
193caf3
docs: keep the package rename to the changelog
aryanjasala Oct 1, 2026
ec3c13e
docs(changelog): cut 2.0.0 and fold the rename into one entry
aryanjasala Oct 1, 2026
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
8 changes: 8 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,11 @@
/phpcs.xml.dist export-ignore
/phpstan.neon.dist export-ignore
/phpunit.xml.dist export-ignore
/composer.lock export-ignore
/docs export-ignore
/AGENTS.md export-ignore
/CONTRIBUTING.md export-ignore
/SECURITY.md export-ignore

# Ship on purpose: README.md and LICENSE.md, inc/, plus ai/ and
# bin/sync-ai-instructions.js, which consumers run from vendor/ via `npm run sync-ai`.
47 changes: 28 additions & 19 deletions .github/workflows/auto-merge.yml
Original file line number Diff line number Diff line change
@@ -1,33 +1,42 @@
name: Pull Requests auto-merge
name: Dependabot auto-merge

on:
workflow_run:
workflows: ["Test and Measure"]
types:
- completed
# GitHub's documented pattern: run on the Dependabot pull request itself (no
# workflow_run, no checkout), read the update type from Dependabot's metadata and
# enable auto-merge for minor and patch updates. Auto-merge then waits for every
# ruleset requirement, so the "Test and Measure" jobs must be required status
# checks for a red run to block the merge.
#
# Repository prerequisites (Settings): "Allow auto-merge" enabled, and the main
# ruleset's required reviews satisfiable for Dependabot pull requests.

on: pull_request

permissions:
pull-requests: write
contents: write
contents: read

concurrency:
group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch || github.run_id }}
group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
cancel-in-progress: true

jobs:
dependabot:
name: Dependabot PR auto-merge
runs-on: ubuntu-latest
if: ${{ github.actor == 'dependabot[bot]' }}
# The pull request author cannot be spoofed, unlike github.actor.
if: github.event.pull_request.user.login == 'dependabot[bot]'
permissions:
contents: write
pull-requests: write
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
- name: Fetch Dependabot metadata
id: metadata
uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0

- name: Approve and merge the PR
if: |
contains( github.event.workflow_run.head_commit.message, 'version-update:semver-minor' ) ||
contains( github.event.workflow_run.head_commit.message, 'version-update:semver-patch' )
run: gh pr merge "$PR_NUMBER" --auto --merge --delete-branch
- name: Enable auto-merge for minor and patch updates
if: >-
steps.metadata.outputs.update-type == 'version-update:semver-minor' ||
steps.metadata.outputs.update-type == 'version-update:semver-patch'
run: gh pr merge --auto --merge "$PR_URL"
env:
PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PR_URL: ${{ github.event.pull_request.html_url }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
8 changes: 5 additions & 3 deletions .github/workflows/documentation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ name: Documentation

on:
push:
# Temporary deployment test branch; remove after verification.
branches: [main]
paths:
- 'docs/**'
Expand Down Expand Up @@ -44,7 +43,10 @@ jobs:

- name: Build documentation
id: docs
uses: rtCamp/action-docusaurus-build@codex/documentation-workflow
# Pinned to a commit: the action's code only lives on the unmerged
# codex/documentation-workflow branch (rtCamp/action-docusaurus-build#1).
# Move to a release tag once that PR merges and is tagged.
uses: rtCamp/action-docusaurus-build@b671d6800c68a74da8913edb9321422fe8afaedc # codex/documentation-workflow, 2026-09-17
with:
site-title: ${{ vars.DOCS_SITE_TITLE }}
site-config: ${{ vars.DOCS_SITE_CONFIG }}
Expand Down Expand Up @@ -78,4 +80,4 @@ jobs:
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
26 changes: 17 additions & 9 deletions .github/workflows/test-measure.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,9 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Setup PHP
uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
Expand All @@ -34,7 +36,7 @@ jobs:

- name: Get Composer Cache Directory
id: composer-cache
run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"

- name: Configure Composer cache
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
Expand All @@ -58,7 +60,9 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Setup PHP
uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
Expand All @@ -68,7 +72,7 @@ jobs:

- name: Get Composer Cache Directory
id: composer-cache
run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"

- name: Configure Composer cache
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
Expand All @@ -91,7 +95,7 @@ jobs:
fail-fast: false
matrix:
php: ['8.2', '8.3', '8.4']
wp: ['6.5', '6.6', '6.7', '6.8', '6.9', '7.0']
wp: ['6.5', '6.6', '6.7', '6.8', '6.9', '7.0', '7.1']
exclude:
# WordPress added PHP 8.4 support in 6.7.
- { php: '8.4', wp: '6.5' }
Expand All @@ -101,12 +105,14 @@ jobs:
WP_ENV_CORE: WordPress/WordPress#${{ matrix.wp }}
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Setup Node
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: '20'
node-version: '24'

- name: Install Node dependencies
run: npm ci
Expand All @@ -127,12 +133,14 @@ jobs:
WP_ENV_PHP_VERSION: '8.3'
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Setup Node
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: '20'
node-version: '24'

- name: Install Node dependencies
run: npm ci
Expand Down
90 changes: 69 additions & 21 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,26 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please cut the 2.0.0 release heading before tagging, as docs/maintainers.md describes.

Suggested change
## [Unreleased]
## [Unreleased]
## [2.0.0] - 2026-10-01

Please also update the compare links at the bottom of the file, which are outside this diff:

[Unreleased]: https://github.com/rtCamp/wp-primitives/compare/v2.0.0...HEAD
[2.0.0]: https://github.com/rtCamp/wp-primitives/compare/v1.0.1...v2.0.0


## [2.0.0] - 2026-10-01

### Added

- `AbstractAbility` and `AbstractAbilityRegistrar`, base classes for the WordPress
6.9 Abilities API (#76). Abilities default to a fail-closed `manage_options`
permission check and opt in to REST or MCP exposure through `meta()`; a
registrar registers its category idempotently, so several registrars can share
one. Both are inert on WordPress older than 6.9.
- A protected `Encryptor::is_openssl_available()` seam, so the fail-closed
"OpenSSL missing" path of `encrypt()` and `decrypt()` is covered by tests.

### Security

- `Encryptor::decrypt()` now rejects any payload shorter than the IV plus a
full-length authentication tag. OpenSSL verifies a truncated GCM tag at its
truncated length, so a forged 13-byte payload (IV plus one tag byte, empty
ciphertext) decrypted to `''` for 1 in 256 tag values instead of failing.

### Fixed

- `Transients` now hashes a namespaced key longer than WordPress' 172-character
transient name limit to `h:<md5>`. Such names were truncated by the options
table, so the value was never found again on the next request (or, just past the
limit, its expiry was silently dropped). Keys within the limit are unchanged.
- `AbstractBlock` registers by block name when the build directory has no
`block.json` (a fresh clone, or before `npm run build`). It used to pass the
directory to `register_block_type()`, which raised a "Block type names must
contain a namespace prefix" notice on every request and registered nothing.
- `sync-ai` also finds packages in site repositories that commit only the root
instructions projection, by detecting packages that vendor
`rtcamp/wp-primitives`. Before, such repositories got "Nothing to do" and kept
the legacy root file after upgrading.
- `sync-ai` prunes only the legacy files it generated and logs the real path of
each file it removes.

### Changed

- **BREAKING: renamed the package from `rtcamp/wp-framework` to `rtcamp/wp-primitives`.**
The PHP namespace moves from `rtCamp\WPFramework\` to `rtCamp\WPPrimitives\`, the
repository moves to `rtCamp/wp-primitives`, and the AI rules file shipped to consumers
is renamed from `ai/framework-php.instructions.md` to `ai/primitives-php.instructions.md`
(synced into consumers as `.github/instructions/primitives-php.instructions.md`).
Consumers must move to a `^2.0` constraint; `^1.0` continues to resolve from the
existing `v1.0.0` / `v1.0.1` tags, which keep the old package name.

- **BREAKING: `AssetLoader::HANDLE_PREFIX` default changes from `wp-framework-` to
`wp-primitives-`.** Any consumer that did not override the constant will see every
default asset handle change, so `wp_add_inline_script()`, `wp_localize_script()`,
dependency arrays and dequeue calls that referenced a `wp-framework-*` handle by
string must be updated. Override `HANDLE_PREFIX` in your subclass to keep the old
handles.
- **BREAKING: the gettext text domain changes from `wp-framework` to `wp-primitives`**
across the 23 translated strings in `inc/`. No `.pot`, `.po` or `.mo` files ship with
this package, so nothing in-repo breaks, but any consumer shipping translations for
the old domain must retarget them.
- **BREAKING: the package is now `rtcamp/wp-primitives`** (previously
`rtcamp/wp-framework`). Require `rtcamp/wp-primitives:^2.0`. Existing installs keep
working from their `composer.lock`, but `composer update` no longer resolves the old
name. The new name also changes these defaults:
- PHP namespace: `rtCamp\WPPrimitives\`.
- `AssetLoader::HANDLE_PREFIX`: `wp-primitives-`. Default asset handles change, so
handles referenced by string in `wp_add_inline_script()`, `wp_localize_script()`,
dependency arrays or dequeue calls must be updated. Override the constant to keep
the 1.x handles.
- `ComponentLoader::get_context()`: `wp-primitives`. Subclasses that do not override
it get `wp-primitives/component_*` hooks (`before_render`, `after_render`,
`asset_handle`, `should_enqueue`) and `wp-primitives-component-*` asset handles.
Override `get_context()` to keep the 1.x names.
- Text domain of the 22 translated strings in `inc/`: `wp-primitives`. No
translation files ship with this package; retarget any you maintain.
- AI rules file: `ai/primitives-php.instructions.md`, synced into consumers as
`.github/instructions/primitives-php.instructions.md`.

### Build

- Dist archives (Packagist and GitHub zipballs) no longer include `docs/`,
`AGENTS.md`, `CONTRIBUTING.md` or `composer.lock`. `ai/` and
`bin/sync-ai-instructions.js` still ship, because consumers run them from
`vendor/` via `npm run sync-ai`.
- CI runs on Node 24 (Node 20 reached end of life in April 2026), PHPStan runs at
level 6, the documentation action is pinned to a commit, and checkouts no longer
persist credentials. Dependabot auto-merge uses GitHub's documented
`pull_request` pattern instead of a `workflow_run` trigger with a spoofable
`github.actor` check.

### Documentation

Expand All @@ -36,8 +83,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added `docs/upgrading.md` (versioning promise and the 1.0.0 → 1.0.1 `Singleton`
migration) and `docs/troubleshooting.md` (symptom → cause for the framework's
exceptions, `_doing_it_wrong()` notices, and silent no-ops).
- Documented the real install path: the package is not on public Packagist, so
the consumer needs a VCS `repositories` entry and a `^2.0` constraint.
- Install docs are Packagist-first (`composer require rtcamp/wp-primitives:^2.0`),
with a VCS `repositories` fallback for installing straight from GitHub.
- Added a worked WP-CLI example to `docs/contracts.md`, the only contract that
had none, and a quick-look snippet to the README.
- Corrected the `Loader::load()` snippet in `docs/architecture.md` to match the
Expand Down Expand Up @@ -100,6 +147,7 @@ Initial release. Requires PHP 8.2+.
- Reference documentation under `docs/`, a GPL-2.0-or-later `LICENSE.md`, and a
WordPress integration test suite running against `@wordpress/env`.

[Unreleased]: https://github.com/rtCamp/wp-primitives/compare/v1.0.1...HEAD
[Unreleased]: https://github.com/rtCamp/wp-primitives/compare/v2.0.0...HEAD
[2.0.0]: https://github.com/rtCamp/wp-primitives/compare/v1.0.1...v2.0.0
[1.0.1]: https://github.com/rtCamp/wp-primitives/compare/v1.0.0...v1.0.1
[1.0.0]: https://github.com/rtCamp/wp-primitives/releases/tag/v1.0.0
17 changes: 8 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,14 @@ Requirements:

## Install

Not on public Packagist — add the repository to the consuming project's
`composer.json`, then require it with a caret constraint:
```bash
composer require rtcamp/wp-primitives:^2.0
```

The package is published on [Packagist](https://packagist.org/packages/rtcamp/wp-primitives),
so no extra configuration is needed. To install straight from GitHub instead (a
branch, a fork, or a project that does not use Packagist), add a VCS repository
before requiring it:

```json
{
Expand All @@ -39,13 +45,6 @@ Not on public Packagist — add the repository to the consuming project's
}
```

```bash
composer require rtcamp/wp-primitives:^2.0
```

(The `repositories` entry is unnecessary when the project already resolves this
package through an rtCamp-hosted Composer registry.)

PSR-4 autoloading: `rtCamp\WPPrimitives\` → `inc/`.

## Quick look
Expand Down
25 changes: 25 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Security policy

## Supported versions

| Version | Supported |
|---|---|
| 2.x | Yes |
| 1.0.x | No further releases; upgrade to 2.x |

## Reporting a vulnerability

Please do not report security issues in public issues, pull requests or
discussions.

Report them privately through GitHub instead: open the repository's
**Security** tab and choose **Report a vulnerability**, or go straight to
<https://github.com/rtCamp/wp-primitives/security/advisories/new>. The report
stays visible only to you and the maintainers, and the fix, the release and
the advisory are coordinated in that same thread.

Include what you can of:

- the affected class or method and the package version;
- the impact, and the conditions an attacker needs;
- steps or a minimal proof of concept that reproduce it.
Loading
Loading