diff --git a/.gitattributes b/.gitattributes index eb86cfd..d50f1e3 100644 --- a/.gitattributes +++ b/.gitattributes @@ -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`. diff --git a/.github/workflows/auto-merge.yml b/.github/workflows/auto-merge.yml index 6bff7a3..1c1e6f3 100644 --- a/.github/workflows/auto-merge.yml +++ b/.github/workflows/auto-merge.yml @@ -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 }} diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index a78cf18..d67d755 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -2,7 +2,6 @@ name: Documentation on: push: - # Temporary deployment test branch; remove after verification. branches: [main] paths: - 'docs/**' @@ -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 }} @@ -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 diff --git a/.github/workflows/test-measure.yml b/.github/workflows/test-measure.yml index d128b2e..7b583f7 100644 --- a/.github/workflows/test-measure.yml +++ b/.github/workflows/test-measure.yml @@ -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 @@ -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 @@ -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 @@ -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 @@ -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' } @@ -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 @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 354ad36..8379b65 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,26 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [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:`. 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 @@ -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 @@ -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 diff --git a/README.md b/README.md index 371c822..cea69f2 100644 --- a/README.md +++ b/README.md @@ -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 { @@ -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 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..cac244c --- /dev/null +++ b/SECURITY.md @@ -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 +. 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. diff --git a/bin/sync-ai-instructions.js b/bin/sync-ai-instructions.js index 20e0c32..e306ebf 100644 --- a/bin/sync-ai-instructions.js +++ b/bin/sync-ai-instructions.js @@ -90,8 +90,13 @@ const discoverPackages = ( root ) => { } fs.readdirSync( container ).forEach( ( slug ) => { const base = path.join( container, slug ); - if ( fs.existsSync( path.join( base, '.github', 'instructions' ) ) ) { - found.push( { type, slug, base, dir: path.join( base, '.github', 'instructions' ) } ); + const dir = path.join( base, '.github', 'instructions' ); + // A package qualifies when it already carries instructions or when it vendors + // the framework, because refreshPackage() creates its .github/instructions/ on + // the first run. Site repos often commit only the root projection, so a fresh + // checkout has no per-package directory and would otherwise be skipped forever. + if ( fs.existsSync( dir ) || fs.existsSync( path.join( base, FRAMEWORK_SRC ) ) ) { + found.push( { type, slug, base, dir } ); } } ); } ); @@ -195,11 +200,13 @@ const refreshPackage = ( base, relRoot ) => { writeIfChanged( dest, withMarker( fs.readFileSync( src, 'utf8' ) ), relRoot, 'refresh' ); // Migration from <2.0: drop the superseded filename so it is not projected to the root - // and so Copilot does not read two copies of the same rules. + // and so Copilot does not read two copies of the same rules. Only a copy the old + // sync generated (it carries LEGACY_MARKER) is removed; a hand-written file that + // happens to share the name is left alone, matching the root prune below. const legacy = path.join( base, '.github', 'instructions', LEGACY_INSTRUCTION_FILE ); - if ( fs.existsSync( legacy ) ) { + if ( fs.existsSync( legacy ) && fs.readFileSync( legacy, 'utf8' ).includes( LEGACY_MARKER ) ) { drift = true; - log.push( color.red( ` prune ${ relRoot }/.github/instructions/${ LEGACY_INSTRUCTION_FILE }` ) ); + log.push( color.red( ` prune ${ path.relative( relRoot, legacy ) }` ) ); if ( ! isCheck ) { fs.unlinkSync( legacy ); } @@ -217,6 +224,11 @@ const refreshPackage = ( base, relRoot ) => { const projectToRoot = ( root, packages ) => { const groups = new Map(); packages.forEach( ( { type, slug, dir } ) => { + // Under --check a package discovered through its vendored framework has no + // directory yet; refreshPackage() has already reported that as drift. + if ( ! fs.existsSync( dir ) ) { + return; + } const prefix = `${ type }/${ slug }`; fs.readdirSync( dir ) .filter( ( f ) => f.endsWith( '.instructions.md' ) ) @@ -275,7 +287,7 @@ const main = () => { } else { const packages = discoverPackages( root ); if ( 0 === packages.length ) { - console.log( color.yellow( 'No packages with .github/instructions/ under plugins/ or themes/. Nothing to do.' ) ); + console.log( color.yellow( 'No package under plugins/ or themes/ has .github/instructions/ or a vendored rtcamp/wp-primitives. Run `composer install` in each package, then re-run. Nothing to do.' ) ); process.exit( 0 ); } packages.forEach( ( p ) => refreshPackage( p.base, root ) ); diff --git a/composer.json b/composer.json index 1c02ee8..ad30d06 100644 --- a/composer.json +++ b/composer.json @@ -1,12 +1,28 @@ { "name": "rtcamp/wp-primitives", - "description": "Shared PHP utilities for rtCamp WordPress projects", + "description": "Contracts, loaders and utilities for building WordPress plugins and themes on a shared, tested base.", + "keywords": [ + "wordpress", + "wordpress-plugin", + "wordpress-theme", + "framework", + "library", + "rtcamp" + ], "type": "library", "license": "GPL-2.0-or-later", + "authors": [ + { + "name": "rtCamp", + "email": "support@rtcamp.com", + "homepage": "https://rtcamp.com" + } + ], "homepage": "https://github.com/rtCamp/wp-primitives", "support": { "issues": "https://github.com/rtCamp/wp-primitives/issues", - "source": "https://github.com/rtCamp/wp-primitives" + "source": "https://github.com/rtCamp/wp-primitives", + "docs": "https://opensource.rtcamp.com/wp-primitives/" }, "require": { "php": ">=8.2" @@ -60,7 +76,7 @@ }, "extra": { "branch-alias": { - "dev-main": "2.0.x-dev" + "dev-main": "2.x-dev" } }, "minimum-stability": "stable", diff --git a/composer.lock b/composer.lock index ad7ebbe..f81b6be 100644 --- a/composer.lock +++ b/composer.lock @@ -4,37 +4,37 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "90832f0a54275b28f76520bf5a51f693", + "content-hash": "d2ae57078b8d948435c060fa2ae5963c", "packages": [], "packages-dev": [ { "name": "automattic/vipwpcs", - "version": "3.0.1", + "version": "3.1.0", "source": { "type": "git", "url": "https://github.com/Automattic/VIP-Coding-Standards.git", - "reference": "2b1d206d81b74ed999023cffd924f862ff2753c8" + "reference": "9c47cd036754e0e5f354a9914568f052043c3f30" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/Automattic/VIP-Coding-Standards/zipball/2b1d206d81b74ed999023cffd924f862ff2753c8", - "reference": "2b1d206d81b74ed999023cffd924f862ff2753c8", + "url": "https://api.github.com/repos/Automattic/VIP-Coding-Standards/zipball/9c47cd036754e0e5f354a9914568f052043c3f30", + "reference": "9c47cd036754e0e5f354a9914568f052043c3f30", "shasum": "" }, "require": { - "php": ">=5.4", - "phpcsstandards/phpcsextra": "^1.2.1", - "phpcsstandards/phpcsutils": "^1.0.11", - "sirbrillig/phpcs-variable-analysis": "^2.11.18", - "squizlabs/php_codesniffer": "^3.9.2", - "wp-coding-standards/wpcs": "^3.1.0" + "php": ">=7.4", + "phpcsstandards/phpcsextra": "^1.5.1", + "phpcsstandards/phpcsutils": "^1.2.3", + "sirbrillig/phpcs-variable-analysis": "^2.13.0", + "squizlabs/php_codesniffer": "^3.13.5", + "wp-coding-standards/wpcs": "^3.4.1" }, "require-dev": { "php-parallel-lint/php-console-highlighter": "^1.0.0", - "php-parallel-lint/php-parallel-lint": "^1.3.2", + "php-parallel-lint/php-parallel-lint": "^1.4.0", "phpcompatibility/php-compatibility": "^9", - "phpcsstandards/phpcsdevtools": "^1.0", - "phpunit/phpunit": "^4 || ^5 || ^6 || ^7 || ^8 || ^9" + "phpcsstandards/phpcsdevtools": "^1.2.3", + "phpunit/phpunit": "^9" }, "type": "phpcodesniffer-standard", "notification-url": "https://packagist.org/downloads/", @@ -59,7 +59,7 @@ "source": "https://github.com/Automattic/VIP-Coding-Standards", "wiki": "https://github.com/Automattic/VIP-Coding-Standards/wiki" }, - "time": "2024-05-10T20:31:09+00:00" + "time": "2026-07-27T14:33:48+00:00" }, { "name": "dealerdirect/phpcodesniffer-composer-installer", @@ -465,16 +465,16 @@ }, { "name": "php-stubs/wordpress-stubs", - "version": "v6.9.4", + "version": "v7.1.0", "source": { "type": "git", "url": "https://github.com/php-stubs/wordpress-stubs.git", - "reference": "90a9412826b9944f93b10bf41d795b5fe68abcd5" + "reference": "394570301894799e69a4aa117c9c995427e3ba04" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/php-stubs/wordpress-stubs/zipball/90a9412826b9944f93b10bf41d795b5fe68abcd5", - "reference": "90a9412826b9944f93b10bf41d795b5fe68abcd5", + "url": "https://api.github.com/repos/php-stubs/wordpress-stubs/zipball/394570301894799e69a4aa117c9c995427e3ba04", + "reference": "394570301894799e69a4aa117c9c995427e3ba04", "shasum": "" }, "conflict": { @@ -484,13 +484,13 @@ "dealerdirect/phpcodesniffer-composer-installer": "^1.0", "nikic/php-parser": "^5.5", "php": "^7.4 || ^8.0", - "php-stubs/generator": "^0.8.6", + "php-stubs/generator": "^0.9", "phpdocumentor/reflection-docblock": "^6.0", - "phpstan/phpstan": "^2.1", + "phpstan/phpstan": "^2.2", "phpunit/phpunit": "^9.5", "symfony/polyfill-php80": "*", - "szepeviktor/phpcs-psr-12-neutron-hybrid-ruleset": "^1.1.1", - "wp-coding-standards/wpcs": "3.1.0 as 2.3.0" + "szepeviktor/phpcs-psr-12-neutron-hybrid-ruleset": "^1.2", + "wp-coding-standards/wpcs": "3.4.1 as 2.3.0" }, "suggest": { "paragonie/sodium_compat": "Pure PHP implementation of libsodium", @@ -511,9 +511,9 @@ ], "support": { "issues": "https://github.com/php-stubs/wordpress-stubs/issues", - "source": "https://github.com/php-stubs/wordpress-stubs/tree/v6.9.4" + "source": "https://github.com/php-stubs/wordpress-stubs/tree/v7.1.0" }, - "time": "2026-05-01T20:36:01+00:00" + "time": "2026-08-28T00:32:06+00:00" }, { "name": "phpcompatibility/php-compatibility", @@ -730,21 +730,21 @@ }, { "name": "phpcsstandards/phpcsextra", - "version": "1.5.0", + "version": "1.5.1", "source": { "type": "git", "url": "https://github.com/PHPCSStandards/PHPCSExtra.git", - "reference": "b598aa890815b8df16363271b659d73280129101" + "reference": "39467533fdb742446d68c1d10ac33d625ee0311c" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/PHPCSStandards/PHPCSExtra/zipball/b598aa890815b8df16363271b659d73280129101", - "reference": "b598aa890815b8df16363271b659d73280129101", + "url": "https://api.github.com/repos/PHPCSStandards/PHPCSExtra/zipball/39467533fdb742446d68c1d10ac33d625ee0311c", + "reference": "39467533fdb742446d68c1d10ac33d625ee0311c", "shasum": "" }, "require": { "php": ">=5.4", - "phpcsstandards/phpcsutils": "^1.2.0", + "phpcsstandards/phpcsutils": "^1.2.3", "squizlabs/php_codesniffer": "^3.13.5 || ^4.0.1" }, "require-dev": { @@ -808,20 +808,20 @@ "type": "thanks_dev" } ], - "time": "2025-11-12T23:06:57+00:00" + "time": "2026-07-27T11:13:17+00:00" }, { "name": "phpcsstandards/phpcsutils", - "version": "1.2.2", + "version": "1.2.3", "source": { "type": "git", "url": "https://github.com/PHPCSStandards/PHPCSUtils.git", - "reference": "c216317e96c8b3f5932808f9b0f1f7a14e3bbf55" + "reference": "5f35d9408c54d7b529501f3c688b6eae562aea1f" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/PHPCSStandards/PHPCSUtils/zipball/c216317e96c8b3f5932808f9b0f1f7a14e3bbf55", - "reference": "c216317e96c8b3f5932808f9b0f1f7a14e3bbf55", + "url": "https://api.github.com/repos/PHPCSStandards/PHPCSUtils/zipball/5f35d9408c54d7b529501f3c688b6eae562aea1f", + "reference": "5f35d9408c54d7b529501f3c688b6eae562aea1f", "shasum": "" }, "require": { @@ -901,15 +901,15 @@ "type": "thanks_dev" } ], - "time": "2025-12-08T14:27:58+00:00" + "time": "2026-07-27T10:28:41+00:00" }, { "name": "phpstan/phpstan", - "version": "2.2.5", + "version": "2.2.16", "dist": { "type": "zip", - "url": "https://api.github.com/repos/phpstan/phpstan/zipball/909c1e5fef7989ac0d0c1c5c42e32a5c4f6198a0", - "reference": "909c1e5fef7989ac0d0c1c5c42e32a5c4f6198a0", + "url": "https://api.github.com/repos/phpstan/phpstan/zipball/46a6d9060e5a7763adfcc21ebcb8b504ebdbcb92", + "reference": "46a6d9060e5a7763adfcc21ebcb8b504ebdbcb92", "shasum": "" }, "require": { @@ -965,7 +965,7 @@ "type": "github" } ], - "time": "2026-07-05T06:31:06+00:00" + "time": "2026-09-25T09:31:51+00:00" }, { "name": "phpunit/php-code-coverage", @@ -2466,16 +2466,16 @@ }, { "name": "squizlabs/php_codesniffer", - "version": "3.13.5", + "version": "3.13.6", "source": { "type": "git", "url": "https://github.com/PHPCSStandards/PHP_CodeSniffer.git", - "reference": "0ca86845ce43291e8f5692c7356fccf3bcf02bf4" + "reference": "4c378e1a528ea066890fc2397cbdd2f94eb2fc91" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/PHPCSStandards/PHP_CodeSniffer/zipball/0ca86845ce43291e8f5692c7356fccf3bcf02bf4", - "reference": "0ca86845ce43291e8f5692c7356fccf3bcf02bf4", + "url": "https://api.github.com/repos/PHPCSStandards/PHP_CodeSniffer/zipball/4c378e1a528ea066890fc2397cbdd2f94eb2fc91", + "reference": "4c378e1a528ea066890fc2397cbdd2f94eb2fc91", "shasum": "" }, "require": { @@ -2541,25 +2541,25 @@ "type": "thanks_dev" } ], - "time": "2025-11-04T16:30:35+00:00" + "time": "2026-08-06T00:17:32+00:00" }, { "name": "szepeviktor/phpstan-wordpress", - "version": "v2.0.3", + "version": "v2.0.4", "source": { "type": "git", "url": "https://github.com/szepeviktor/phpstan-wordpress.git", - "reference": "aa722f037b2d034828cd6c55ebe9e5c74961927e" + "reference": "84577e2ea1e4c2a95537fe5ea2ac8e18f4ceab1a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/szepeviktor/phpstan-wordpress/zipball/aa722f037b2d034828cd6c55ebe9e5c74961927e", - "reference": "aa722f037b2d034828cd6c55ebe9e5c74961927e", + "url": "https://api.github.com/repos/szepeviktor/phpstan-wordpress/zipball/84577e2ea1e4c2a95537fe5ea2ac8e18f4ceab1a", + "reference": "84577e2ea1e4c2a95537fe5ea2ac8e18f4ceab1a", "shasum": "" }, "require": { "php": "^7.4 || ^8.0", - "php-stubs/wordpress-stubs": "^6.6.2", + "php-stubs/wordpress-stubs": ">=6.6.2", "phpstan/phpstan": "^2.0" }, "require-dev": { @@ -2602,9 +2602,9 @@ ], "support": { "issues": "https://github.com/szepeviktor/phpstan-wordpress/issues", - "source": "https://github.com/szepeviktor/phpstan-wordpress/tree/v2.0.3" + "source": "https://github.com/szepeviktor/phpstan-wordpress/tree/v2.0.4" }, - "time": "2025-09-14T02:58:22+00:00" + "time": "2026-05-22T16:22:09+00:00" }, { "name": "theseer/tokenizer", @@ -2658,16 +2658,16 @@ }, { "name": "wp-coding-standards/wpcs", - "version": "3.4.0", + "version": "3.4.1", "source": { "type": "git", "url": "https://github.com/WordPress/WordPress-Coding-Standards.git", - "reference": "469c18ceab4d642b15bad4c65ebf3b307bfd55ab" + "reference": "ec2ff942335f33683a5957a85d138753876a05cf" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/WordPress/WordPress-Coding-Standards/zipball/469c18ceab4d642b15bad4c65ebf3b307bfd55ab", - "reference": "469c18ceab4d642b15bad4c65ebf3b307bfd55ab", + "url": "https://api.github.com/repos/WordPress/WordPress-Coding-Standards/zipball/ec2ff942335f33683a5957a85d138753876a05cf", + "reference": "ec2ff942335f33683a5957a85d138753876a05cf", "shasum": "" }, "require": { @@ -2676,8 +2676,8 @@ "ext-tokenizer": "*", "ext-xmlreader": "*", "php": ">=7.2", - "phpcsstandards/phpcsextra": "^1.5.0", - "phpcsstandards/phpcsutils": "^1.2.2", + "phpcsstandards/phpcsextra": "^1.5.1", + "phpcsstandards/phpcsutils": "^1.2.3", "squizlabs/php_codesniffer": "^3.13.5" }, "require-dev": { @@ -2720,20 +2720,20 @@ "type": "custom" } ], - "time": "2026-07-16T13:05:29+00:00" + "time": "2026-07-27T11:53:23+00:00" }, { "name": "wp-phpunit/wp-phpunit", - "version": "7.0.2", + "version": "7.1.1", "source": { "type": "git", "url": "https://github.com/wp-phpunit/wp-phpunit.git", - "reference": "0d17335392d78b12b3e7e6b519cd53db728df52a" + "reference": "797edc710afc958854852d859c93d9aa1de6447d" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/wp-phpunit/wp-phpunit/zipball/0d17335392d78b12b3e7e6b519cd53db728df52a", - "reference": "0d17335392d78b12b3e7e6b519cd53db728df52a", + "url": "https://api.github.com/repos/wp-phpunit/wp-phpunit/zipball/797edc710afc958854852d859c93d9aa1de6447d", + "reference": "797edc710afc958854852d859c93d9aa1de6447d", "shasum": "" }, "type": "library", @@ -2768,7 +2768,7 @@ "issues": "https://github.com/wp-phpunit/issues", "source": "https://github.com/wp-phpunit/wp-phpunit" }, - "time": "2026-07-10T02:38:55+00:00" + "time": "2026-08-20T00:59:59+00:00" }, { "name": "yoast/phpunit-polyfills", diff --git a/docs/getting-started.md b/docs/getting-started.md index f1b0987..357a32b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -21,8 +21,14 @@ APIs. `Encryptor` additionally requires the OpenSSL PHP extension when used. ## Install -The package is not published on public Packagist. Add the repository to the -consuming project's `composer.json` first, then require it: +```bash +composer require rtcamp/wp-primitives:^2.0 +``` + +The package is published on [Packagist](https://packagist.org/packages/rtcamp/wp-primitives), +so `composer require` is all a consumer needs. To install from GitHub instead (a +development branch, a fork, or a project that does not use Packagist), add the +repository to the consuming project's `composer.json` first: ```json { @@ -35,14 +41,6 @@ consuming project's `composer.json` first, then require it: } ``` -```bash -composer require rtcamp/wp-primitives:^2.0 -``` - -If the project is already wired to an rtCamp-hosted Composer registry that -serves this package, the `repositories` entry is unnecessary and -`composer require rtcamp/wp-primitives:^2.0` is enough on its own. - Pin with a caret constraint. `inc/Contracts/` is the public API and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html), so `^2.0` accepts additive releases and refuses the next major. Read diff --git a/docs/maintainers.md b/docs/maintainers.md index 1c92029..52973e3 100644 --- a/docs/maintainers.md +++ b/docs/maintainers.md @@ -145,6 +145,33 @@ Use the repository pull-request template. A change is ready for review when: - `CHANGELOG.md` contains an `[Unreleased]` entry; - commits follow Conventional Commits. -Branching, release targeting, version selection, and package publication are not -defined here because the repository does not currently establish one complete, -authoritative release procedure. +## Releasing + +The package is published on Packagist as `rtcamp/wp-primitives`, which reads +versions straight from git tags through the repository's Packagist webhook. +A release is therefore a tag on `main`: + +1. Open a pull request that moves the `[Unreleased]` entries under a new + `## [X.Y.Z] - YYYY-MM-DD` heading and updates the compare links at the bottom + of `CHANGELOG.md`. Pick the version from the changes: anything breaking in + `inc/Contracts/` or in documented behaviour is a major, new API is a minor, + fixes only is a patch. +2. Merge it, then tag the merge commit with an annotated tag and push the tag: + + ```bash + git switch main && git pull + git tag -a vX.Y.Z -m "vX.Y.Z" + git push origin vX.Y.Z + ``` + +3. Create the GitHub release from that tag and paste the version's changelog + section as the notes (`gh release create vX.Y.Z --title vX.Y.Z --notes-file + notes.md`). `.github/release.yml` keeps Dependabot pull requests out of + generated notes if you use `--generate-notes` instead. +4. Confirm Packagist picked the tag up: `composer show rtcamp/wp-primitives --all` + lists the new version within a minute or two. If it does not, check the + webhook delivery under the repository's Settings > Webhooks. + +Never move, delete or re-push a published tag: consumers and Packagist have +already resolved it. Fix forward with a patch release instead. + diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f39adc5..b8d7236 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -70,7 +70,7 @@ one you get is deliberate: | Symptom | Cause | Fix | |---|---|---| | `Class "rtCamp\WPPrimitives\…" not found` | The consumer's `vendor/autoload.php` was never required, or the package resolved from a stale `vendor/`. | Require the autoloader in the plugin/theme entry point; `composer update rtcamp/wp-primitives`. | -| Composer can't find the package | It is not on public Packagist. | Add the VCS `repositories` entry — see [getting-started.md](getting-started.md#install). | +| Composer can't find the package | The project installs from GitHub without a `repositories` entry. | Add the VCS entry from [getting-started.md](getting-started.md#install). | | A missing abstract method only surfaces at runtime | The subclass doesn't implement everything the abstract declares. | Run PHPStan in the consuming package; it catches contract breaks before a request does. | Still stuck? The classes are small and heavily commented — `Loader::load()` in diff --git a/docs/upgrading.md b/docs/upgrading.md index 38283a5..4276060 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -38,46 +38,6 @@ Then run the consumer's own test suite. Static analysis catches the majority of contract breaks (a missing abstract implementation, a changed signature) before runtime does. -## 1.0.x → 2.0.0 (package rename) - -**Affects:** every consumer. 2.0.0 renames the package, so `composer update` alone -cannot cross it. - -1. Replace the requirement and the VCS repository entry in the consumer's - `composer.json`: - - ```diff - -"rtcamp/wp-framework": "^1.0" - +"rtcamp/wp-primitives": "^2.0" - ``` - - ```diff - -{ "type": "vcs", "url": "https://github.com/rtCamp/wp-framework.git", "no-api": true } - +{ "type": "vcs", "url": "https://github.com/rtCamp/wp-primitives.git", "no-api": true } - ``` - - Then `composer remove rtcamp/wp-framework && composer require rtcamp/wp-primitives:^2.0`. - The GitHub redirect keeps the old URL resolving, but the package name it serves has - changed, so the requirement must be edited by hand. - -2. Rewrite the namespace across the consumer: `rtCamp\WPFramework\` becomes - `rtCamp\WPPrimitives\` in every `namespace` declaration, `use` statement, PHPDoc - annotation and class-string. - -3. If you subclass `AssetLoader` without overriding `HANDLE_PREFIX`, every default - asset handle changes from `wp-framework-*` to `wp-primitives-*`. Audit any handle - referenced as a literal string. - -4. Retarget any translations from the `wp-framework` text domain to `wp-primitives`. - -5. Run `npm run sync-ai`. It now writes - `.github/instructions/primitives-php.instructions.md` and deletes the superseded - `framework-php.instructions.md`. - -Projects that are not ready can stay on `^1.0`, which continues to resolve from the -`v1.0.0` and `v1.0.1` tags. Those tags are immutable and still declare the old package -name, so they keep working; they will not receive further releases. - ## 1.0.0 → 1.0.1 **Affects:** any class using the `Singleton` trait. diff --git a/inc/Contracts/Abstracts/AbstractBlock.php b/inc/Contracts/Abstracts/AbstractBlock.php index 88627f8..3639a1f 100644 --- a/inc/Contracts/Abstracts/AbstractBlock.php +++ b/inc/Contracts/Abstracts/AbstractBlock.php @@ -52,6 +52,13 @@ public function register_hooks(): void { /** * Register the block type with WordPress. + * + * Registers from get_block_dir() when that directory holds a block.json, and + * by name otherwise. A configured directory without a block.json (a fresh + * clone or a CI run before `npm run build`, or a deploy that lost its build) + * falls back to registering by name: the server-side render still works, and + * WordPress no longer receives the directory path as a block name, which it + * rejected with a "must contain a namespace prefix" notice on every request. */ public function register_block(): void { $args = $this->get_block_args(); @@ -60,7 +67,7 @@ public function register_block(): void { $args['render_callback'] = [ $this, 'render' ]; $block_dir = $this->get_block_dir(); - if ( $block_dir ) { + if ( $block_dir && file_exists( trailingslashit( $block_dir ) . 'block.json' ) ) { register_block_type( $block_dir, $args ); } else { register_block_type( static::get_name(), $args ); diff --git a/inc/Contracts/Abstracts/AbstractShortcode.php b/inc/Contracts/Abstracts/AbstractShortcode.php index 827252e..8bb7433 100644 --- a/inc/Contracts/Abstracts/AbstractShortcode.php +++ b/inc/Contracts/Abstracts/AbstractShortcode.php @@ -42,8 +42,8 @@ public function register_shortcode(): void { /** * Shortcode callback wrapper. Parses attributes and delegates to render(). * - * @param array|string $atts Shortcode attributes. - * @param string|null $content Enclosed content (if any). + * @param array|string $atts Shortcode attributes. WordPress passes an empty string when the tag has none. + * @param string|null $content Enclosed content (if any). * * @return string Rendered shortcode output. */ diff --git a/inc/Utils/Encryptor.php b/inc/Utils/Encryptor.php index 23a22e6..369773f 100644 --- a/inc/Utils/Encryptor.php +++ b/inc/Utils/Encryptor.php @@ -69,7 +69,7 @@ public function __construct( * @throws \RuntimeException If no encryption key is available. */ public function encrypt( string $raw_value ): string|false { - if ( ! extension_loaded( 'openssl' ) ) { + if ( ! $this->is_openssl_available() ) { _doing_it_wrong( __METHOD__, 'OpenSSL extension is not loaded. Encryption cannot proceed.', @@ -105,7 +105,7 @@ public function encrypt( string $raw_value ): string|false { * @throws \RuntimeException If no encryption key is available. */ public function decrypt( string $raw_value ): string|false { - if ( ! extension_loaded( 'openssl' ) ) { + if ( ! $this->is_openssl_available() ) { _doing_it_wrong( __METHOD__, 'OpenSSL extension is not loaded. Decryption cannot proceed.', @@ -125,6 +125,14 @@ public function decrypt( string $raw_value ): string|false { return false; } + // A valid payload always carries a full IV and a full-length tag. Reject + // anything shorter before it reaches OpenSSL: GCM verifies a truncated tag + // at its truncated length, so a 13-byte payload (IV + 1 tag byte, empty + // ciphertext) would decrypt to '' for 1 in 256 forged tags. + if ( strlen( $decoded_value ) < static::IV_LENGTH + static::TAG_LENGTH ) { + return false; + } + $iv = substr( $decoded_value, 0, static::IV_LENGTH ); $tag = substr( $decoded_value, static::IV_LENGTH, static::TAG_LENGTH ); $ciphertext = substr( $decoded_value, static::IV_LENGTH + static::TAG_LENGTH ); @@ -139,6 +147,19 @@ public function decrypt( string $raw_value ): string|false { ); } + /** + * Whether the OpenSSL extension is available. + * + * A seam rather than an inline extension_loaded() call so the "no OpenSSL" + * path, which makes encrypt() and decrypt() fail closed, can be exercised by + * a subclass in tests. + * + * @return bool True when OpenSSL can be used. + */ + protected function is_openssl_available(): bool { + return extension_loaded( 'openssl' ); + } + /** * Resolve the raw secret. * diff --git a/inc/Utils/Transients.php b/inc/Utils/Transients.php index d2c015d..61c1da1 100644 --- a/inc/Utils/Transients.php +++ b/inc/Utils/Transients.php @@ -35,6 +35,15 @@ */ class Transients { + /** + * Longest transient name WordPress can store. + * + * A DB-backed transient is two option rows, `_transient_{name}` and + * `_transient_timeout_{name}`, and `option_name` is varchar(191), so the name + * itself must be 172 characters or fewer (see set_transient()). + */ + protected const MAX_NAME_LENGTH = 172; + /** * Construct a Transients wrapper bound to a key prefix. * @@ -92,14 +101,23 @@ public function delete( string $key ): bool { * `( 'mod', 'a_b' )` and `( 'mod_a', 'b' )` would both collapse to `mod_a_b` and * silently target the same WordPress transient. * + * A namespaced key longer than {@see Transients::MAX_NAME_LENGTH} is replaced by + * `h:`. WordPress cannot store such a name: the + * option rows are truncated, so the value is never found again (or, just past + * the limit, its expiry is silently lost). Keys within the limit are unchanged, + * and a hashed key can never equal an unhashed one, which always starts with + * digits. + * * Protected override seam (mirrors {@see Cache::resolve_group()}): subclass to - * change the namespacing scheme — for instance a multisite / site-transient variant. + * change the namespacing scheme, for instance a multisite / site-transient variant. * * @param string $key Logical key supplied by the caller. * * @return string Fully namespaced key passed to WordPress's transient API. */ protected function resolve_key( string $key ): string { - return strlen( $this->prefix ) . ':' . $this->prefix . '_' . $key; + $name = strlen( $this->prefix ) . ':' . $this->prefix . '_' . $key; + + return strlen( $name ) > static::MAX_NAME_LENGTH ? 'h:' . md5( $name ) : $name; } } diff --git a/package-lock.json b/package-lock.json index 6e58386..7f6f259 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ "version": "0.0.1", "license": "GPL-2.0-or-later", "devDependencies": { - "@wordpress/env": "11.7.0" + "@wordpress/env": "11.16.0" } }, "node_modules/@inquirer/ansi": { @@ -686,6 +686,7 @@ "integrity": "sha512-/g2d4sW9nUDJOMz3mabVQvOGhVa4e/BN/Um7yca9Bb2XTzPPnfTWHWQg+IsEYO7M3Vx+EXvaM/I2pJWIMun1bg==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@octokit/auth-token": "^4.0.0", "@octokit/graphql": "^7.1.0", @@ -1466,32 +1467,31 @@ } }, "node_modules/@wordpress/env": { - "version": "11.7.0", - "resolved": "https://registry.npmjs.org/@wordpress/env/-/env-11.7.0.tgz", - "integrity": "sha512-BR4qAFZ5xrsQM00K5RJtnUqL86cd9opLMPthXi1uLVJqUXYNVf3YHtsptUgwL1wdZ/aON2jn5QWgKyiRL+0bVw==", + "version": "11.16.0", + "resolved": "https://registry.npmjs.org/@wordpress/env/-/env-11.16.0.tgz", + "integrity": "sha512-B09FByMnGleYaBa4LESZ9Bp/71/EOvovjqvwhXhZjZk25fLIsed4gslZXW9c3EodD2oxF5loHUCMzCAqotGRBg==", "dev": true, "license": "GPL-2.0-or-later", "dependencies": { "@inquirer/prompts": "^7.2.0", "@wp-playground/cli": "^3.0.48", - "chalk": "^4.0.0", + "adm-zip": "^0.6.1", + "chalk": "^4.1.1", "copy-dir": "^1.3.0", "cross-spawn": "^7.0.6", "docker-compose": "^0.24.3", - "extract-zip": "^1.6.7", "got": "^11.8.5", - "js-yaml": "^3.13.1", + "js-yaml": "^3.15.2", "ora": "^4.0.2", "rimraf": "^5.0.10", - "simple-git": "^3.5.0", + "simple-git": "^3.32.3", "yargs": "^17.3.0" }, "bin": { "wp-env": "bin/wp-env" }, "engines": { - "node": ">=18.12.0", - "npm": ">=8.19.2" + "node": ">=18.12.0" } }, "node_modules/@wp-playground/blueprints": { @@ -1646,6 +1646,16 @@ "node": ">= 0.6" } }, + "node_modules/adm-zip": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/adm-zip/-/adm-zip-0.6.1.tgz", + "integrity": "sha512-Xwrja8nx9e5o2N1my4DsKCeKpdrnACyr1wtbPxBDgGzKzKyE9kRtBFA8mWldI+RVlD7CBZNWY/wQ2+ydwOR6kQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=14.0" + } + }, "node_modules/aggregate-error": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/aggregate-error/-/aggregate-error-3.1.0.tgz", @@ -1792,9 +1802,9 @@ "license": "Apache-2.0" }, "node_modules/body-parser": { - "version": "1.20.6", - "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.6.tgz", - "integrity": "sha512-p5tAzS57i5MV9fZFDj9LeIiTZEufbSe2eDozP+ElheSUq1m74CRq1jI4mYNDdVs9vQztXFLuk/Gd6BWTdwRJ5g==", + "version": "1.20.8", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.8.tgz", + "integrity": "sha512-JNcyFQ64OiijEkPzUBTCe+hyPXUD/3LEldGQ6iF5LR1w00mx9o7xtDWHXBY2iItjdCFGoilOLNQbH943ut7pHA==", "dev": true, "license": "MIT", "dependencies": { @@ -1806,7 +1816,7 @@ "http-errors": "~2.0.1", "iconv-lite": "~0.4.24", "on-finished": "~2.4.1", - "qs": "~6.15.1", + "qs": "~6.16.0", "raw-body": "~2.5.3", "type-is": "~1.6.18", "unpipe": "~1.0.0" @@ -1829,6 +1839,23 @@ "node": ">=0.10.0" } }, + "node_modules/body-parser/node_modules/qs": { + "version": "6.16.0", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.16.0.tgz", + "integrity": "sha512-h6fhOIaRrID2CbEY2fqs+7t+UXZo+MLAnU5gRIq85uFtdiUPCdsApMlHhXogKVM4HM2DVbIjGNTTYH2OcmP1vA==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "es-define-property": "^1.0.1", + "side-channel": "^1.1.1" + }, + "engines": { + "node": ">=0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, "node_modules/bottleneck": { "version": "2.19.5", "resolved": "https://registry.npmjs.org/bottleneck/-/bottleneck-2.19.5.tgz", @@ -1837,9 +1864,9 @@ "license": "MIT" }, "node_modules/brace-expansion": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.1.tgz", - "integrity": "sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA==", + "version": "2.1.7", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.7.tgz", + "integrity": "sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g==", "dev": true, "license": "MIT", "dependencies": { @@ -1878,16 +1905,6 @@ "ieee754": "^1.2.1" } }, - "node_modules/buffer-crc32": { - "version": "0.2.13", - "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-0.2.13.tgz", - "integrity": "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": "*" - } - }, "node_modules/buffer-equal-constant-time": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz", @@ -1895,13 +1912,6 @@ "dev": true, "license": "BSD-3-Clause" }, - "node_modules/buffer-from": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz", - "integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==", - "dev": true, - "license": "MIT" - }, "node_modules/bytes": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", @@ -2166,22 +2176,6 @@ "dev": true, "license": "MIT" }, - "node_modules/concat-stream": { - "version": "1.6.2", - "resolved": "https://registry.npmjs.org/concat-stream/-/concat-stream-1.6.2.tgz", - "integrity": "sha512-27HBghJxjiZtIk3Ycvn/4kbJk/1uZuJFfuPEns6LaEvpvG1f0hTea8lilrouyo9mVc2GWdcEZ8OLoGmSADlrCw==", - "dev": true, - "engines": [ - "node >= 0.8" - ], - "license": "MIT", - "dependencies": { - "buffer-from": "^1.0.0", - "inherits": "^2.0.3", - "readable-stream": "^2.2.2", - "typedarray": "^0.0.6" - } - }, "node_modules/content-disposition": { "version": "0.5.4", "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-0.5.4.tgz", @@ -2229,13 +2223,6 @@ "dev": true, "license": "MIT" }, - "node_modules/core-util-is": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz", - "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==", - "dev": true, - "license": "MIT" - }, "node_modules/crc-32": { "version": "1.2.2", "resolved": "https://registry.npmjs.org/crc-32/-/crc-32-1.2.2.tgz", @@ -2609,22 +2596,6 @@ "url": "https://opencollective.com/express" } }, - "node_modules/extract-zip": { - "version": "1.7.0", - "resolved": "https://registry.npmjs.org/extract-zip/-/extract-zip-1.7.0.tgz", - "integrity": "sha512-xoh5G1W/PB0/27lXgMQyIhP5DSY/LhoCsOyZgb+6iMmRtCwVBo55uKaMoEYrDCKQhWvqEip5ZPKAc6eFNyf/MA==", - "dev": true, - "license": "BSD-2-Clause", - "dependencies": { - "concat-stream": "^1.6.2", - "debug": "^2.6.9", - "mkdirp": "^0.5.4", - "yauzl": "^2.10.0" - }, - "bin": { - "extract-zip": "cli.js" - } - }, "node_modules/fast-deep-equal": { "version": "3.1.3", "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", @@ -2633,9 +2604,9 @@ "license": "MIT" }, "node_modules/fast-uri": { - "version": "3.1.4", - "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.4.tgz", - "integrity": "sha512-8JnbkQ4juDyvYs4mgFGQqg4yCYtFDtUtmp2QIQq11ZZe5CFQ5wcqm1rqDgAh/QdMySuBnPzMUiJUNZG5N/AiQw==", + "version": "3.1.8", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.8.tgz", + "integrity": "sha512-GZMtZUTNRpOVIECoXwLNZS5xUGE+mVNbTB8h/7Rwh2TFWcBQiPzTgyZi05BF9UMZKkLJv8XBRJTlU7zg8+ZfMg==", "dev": true, "funding": [ { @@ -2689,16 +2660,6 @@ "fxparser": "src/cli/cli.js" } }, - "node_modules/fd-slicer": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/fd-slicer/-/fd-slicer-1.1.0.tgz", - "integrity": "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g==", - "dev": true, - "license": "MIT", - "dependencies": { - "pend": "~1.2.0" - } - }, "node_modules/finalhandler": { "version": "1.3.2", "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-1.3.2.tgz", @@ -3184,13 +3145,6 @@ "url": "https://github.com/sponsors/ljharb" } }, - "node_modules/isarray": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz", - "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==", - "dev": true, - "license": "MIT" - }, "node_modules/isexe": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", @@ -3268,9 +3222,9 @@ } }, "node_modules/js-yaml": { - "version": "3.15.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.0.tgz", - "integrity": "sha512-ttBQIIQPDeLjpPOohtUdXuXUVoA2uIB6fEH9HyJ7234s5mBJ5wTx20njxplLZQgLaOfpmPQA7X2t5AX6tIPbog==", + "version": "3.15.2", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.2.tgz", + "integrity": "sha512-6EuL879VkRA+1Cz578mKMiKvjPNEuk6+r1JaFzoSWejZmtf7xWbIyw1e3KkxlkzTIt9Taw6JBhEppG7utc1P+w==", "dev": true, "license": "MIT", "dependencies": { @@ -3671,19 +3625,6 @@ "node": ">=16 || 14 >=14.17" } }, - "node_modules/mkdirp": { - "version": "0.5.6", - "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.6.tgz", - "integrity": "sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw==", - "dev": true, - "license": "MIT", - "dependencies": { - "minimist": "^1.2.6" - }, - "bin": { - "mkdirp": "bin/cmd.js" - } - }, "node_modules/ms": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", @@ -3940,13 +3881,6 @@ "dev": true, "license": "MIT" }, - "node_modules/pend": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz", - "integrity": "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==", - "dev": true, - "license": "MIT" - }, "node_modules/pify": { "version": "4.0.1", "resolved": "https://registry.npmjs.org/pify/-/pify-4.0.1.tgz", @@ -3977,13 +3911,6 @@ "node": ">= 0.6.0" } }, - "node_modules/process-nextick-args": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz", - "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==", - "dev": true, - "license": "MIT" - }, "node_modules/proxy-addr": { "version": "2.0.7", "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz", @@ -4010,13 +3937,14 @@ } }, "node_modules/qs": { - "version": "6.15.2", - "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.2.tgz", - "integrity": "sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==", + "version": "6.15.3", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.3.tgz", + "integrity": "sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==", "dev": true, "license": "BSD-3-Clause", "dependencies": { - "side-channel": "^1.1.0" + "es-define-property": "^1.0.1", + "side-channel": "^1.1.1" }, "engines": { "node": ">=0.6" @@ -4077,29 +4005,6 @@ "node": ">=0.10.0" } }, - "node_modules/readable-stream": { - "version": "2.3.8", - "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz", - "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==", - "dev": true, - "license": "MIT", - "dependencies": { - "core-util-is": "~1.0.0", - "inherits": "~2.0.3", - "isarray": "~1.0.0", - "process-nextick-args": "~2.0.0", - "safe-buffer": "~5.1.1", - "string_decoder": "~1.1.1", - "util-deprecate": "~1.0.1" - } - }, - "node_modules/readable-stream/node_modules/safe-buffer": { - "version": "5.1.2", - "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", - "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", - "dev": true, - "license": "MIT" - }, "node_modules/require-directory": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", @@ -4541,23 +4446,6 @@ "node": ">= 0.8" } }, - "node_modules/string_decoder": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz", - "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==", - "dev": true, - "license": "MIT", - "dependencies": { - "safe-buffer": "~5.1.0" - } - }, - "node_modules/string_decoder/node_modules/safe-buffer": { - "version": "5.1.2", - "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz", - "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==", - "dev": true, - "license": "MIT" - }, "node_modules/string-width": { "version": "5.1.2", "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz", @@ -4765,13 +4653,6 @@ "node": ">= 0.4" } }, - "node_modules/typedarray": { - "version": "0.0.6", - "resolved": "https://registry.npmjs.org/typedarray/-/typedarray-0.0.6.tgz", - "integrity": "sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==", - "dev": true, - "license": "MIT" - }, "node_modules/undici-types": { "version": "7.24.6", "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz", @@ -4817,13 +4698,6 @@ "node": ">= 0.8" } }, - "node_modules/util-deprecate": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", - "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", - "dev": true, - "license": "MIT" - }, "node_modules/utils-merge": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/utils-merge/-/utils-merge-1.0.1.tgz", @@ -5123,17 +4997,6 @@ "node": ">=8" } }, - "node_modules/yauzl": { - "version": "2.10.0", - "resolved": "https://registry.npmjs.org/yauzl/-/yauzl-2.10.0.tgz", - "integrity": "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g==", - "dev": true, - "license": "MIT", - "dependencies": { - "buffer-crc32": "~0.2.3", - "fd-slicer": "~1.1.0" - } - }, "node_modules/yoctocolors-cjs": { "version": "2.1.3", "resolved": "https://registry.npmjs.org/yoctocolors-cjs/-/yoctocolors-cjs-2.1.3.tgz", diff --git a/package.json b/package.json index d633eef..8da3808 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,6 @@ "test:php:coverage": "wp-env run tests-cli --env-cwd=wp-content/wp-primitives-rt -- vendor/bin/phpunit -c phpunit.xml.dist --coverage-html coverage" }, "devDependencies": { - "@wordpress/env": "11.7.0" + "@wordpress/env": "11.16.0" } } diff --git a/phpstan.neon.dist b/phpstan.neon.dist index ac2d988..a9c6d81 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -5,7 +5,7 @@ includes: - vendor/szepeviktor/phpstan-wordpress/extension.neon parameters: - level: 5 + level: 6 phpVersion: 80200 paths: diff --git a/tests/AssetLoaderTest.php b/tests/AssetLoaderTest.php index 88391b3..92e3385 100644 --- a/tests/AssetLoaderTest.php +++ b/tests/AssetLoaderTest.php @@ -204,6 +204,28 @@ public function test_register_block_manifest_registers_collection(): void { \WP_Block_Type_Registry::get_instance()->unregister( 'wp-primitives/example' ); } + public function test_legacy_fallback_ignores_a_manifest_that_is_not_an_array(): void { + // Only the 6.5 to 6.7 fallback reads the manifest itself; on 6.8+ core + // does, so the guard under test only exists on older cores. + if ( function_exists( 'wp_register_block_types_from_metadata_collection' ) ) { + $this->markTestSkipped( 'The per-block fallback only runs on WordPress < 6.8.' ); + } + + $this->write_asset( + 'build/blocks/example/block.json', + '{"$schema":"https://schemas.wp.org/trunk/block.json","apiVersion":3,"name":"wp-primitives/example","title":"Example","category":"widgets"}' + ); + // A manifest that evaluates to something other than an array. + $this->write_asset( 'build/blocks-manifest.php', 'loader->register_block_manifest( 'build/blocks', 'build/blocks-manifest.php' ); + + $this->assertFalse( + \WP_Block_Type_Registry::get_instance()->is_registered( 'wp-primitives/example' ), + 'a malformed manifest must register nothing rather than fatal' + ); + } + public function test_missing_block_manifest_warns_and_skips_registration(): void { $this->setExpectedIncorrectUsage( AssetLoader::class ); diff --git a/tests/Contracts/Abstracts/AbstractAbilityRegistrarLegacyCoreTest.php b/tests/Contracts/Abstracts/AbstractAbilityRegistrarLegacyCoreTest.php new file mode 100644 index 0000000..e1a0654 --- /dev/null +++ b/tests/Contracts/Abstracts/AbstractAbilityRegistrarLegacyCoreTest.php @@ -0,0 +1,91 @@ +markTestSkipped( 'Only meaningful on cores without the Abilities API (WordPress < 6.9).' ); + } + } + + /** + * A registrar that records every seam the callbacks touch. + */ + private function make_recording_registrar(): AbstractAbilityRegistrar { + return new class() extends AbstractAbilityRegistrar { + /** + * Seams that were called, in order. + * + * @var array + */ + public array $calls = []; + + protected function category_slug(): string { + $this->calls[] = 'category_slug'; + return 'legacy-plugin'; + } + + protected function abilities(): array { + $this->calls[] = 'abilities'; + return []; + } + + protected function category_description(): string { + $this->calls[] = 'category_description'; + return 'Never registered.'; + } + + protected function before_register(): void { + $this->calls[] = 'before_register'; + } + }; + } + + public function test_register_category_is_a_no_op_without_the_abilities_api(): void { + $registrar = $this->make_recording_registrar(); + + $registrar->register_category(); + + $this->assertSame( [], $registrar->calls, 'no seam may run when the API is missing' ); + } + + public function test_register_abilities_is_a_no_op_without_the_abilities_api(): void { + $registrar = $this->make_recording_registrar(); + + $registrar->register_abilities(); + + $this->assertSame( [], $registrar->calls, 'before_register() and abilities() must not run when the API is missing' ); + } + + public function test_hooks_are_still_added_so_a_later_core_upgrade_picks_them_up(): void { + $registrar = $this->make_recording_registrar(); + + $registrar->register_hooks(); + + $this->assertSame( 10, has_action( 'wp_abilities_api_categories_init', [ $registrar, 'register_category' ] ) ); + $this->assertSame( 10, has_action( 'wp_abilities_api_init', [ $registrar, 'register_abilities' ] ) ); + $this->assertSame( [], $registrar->calls, 'adding the hooks must not touch any seam' ); + } +} diff --git a/tests/Contracts/Abstracts/AbstractBlockTest.php b/tests/Contracts/Abstracts/AbstractBlockTest.php index 3f90490..99ad27c 100644 --- a/tests/Contracts/Abstracts/AbstractBlockTest.php +++ b/tests/Contracts/Abstracts/AbstractBlockTest.php @@ -72,6 +72,38 @@ public function test_render_returns_markup(): void { $this->assertSame( '
rendered
', $output ); } + public function test_block_dir_without_block_json_falls_back_to_the_block_name(): void { + // Regression: an unbuilt block directory used to reach register_block_type() + // as a "block name", so WordPress rejected it with a namespace-prefix + // notice and nothing was registered. WP_UnitTestCase fails the test on any + // unexpected _doing_it_wrong(), so the absence of a notice is asserted too. + $dir = sys_get_temp_dir() . '/wpf-unbuilt-' . str_replace( '.', '', uniqid( '', true ) ); + mkdir( $dir, 0777, true ); + + $block = new class( $dir ) extends AbstractBlock { + public function __construct( private string $dir ) {} + + public static function get_name(): string { + return 'wp-primitives-test/block'; + } + + public function render( array $attributes, string $content, \WP_Block $block ): string { + return 'fallback'; + } + + protected function get_block_dir(): ?string { + return $this->dir; + } + }; + + $block->register_block(); + rmdir( $dir ); + + $type = WP_Block_Type_Registry::get_instance()->get_registered( self::BLOCK_NAME ); + $this->assertNotNull( $type, 'the block must still register by name' ); + $this->assertSame( [ $block, 'render' ], $type->render_callback ); + } + public function test_register_block_uses_block_dir_when_provided(): void { $dir = sys_get_temp_dir() . '/wpf-block-' . str_replace( '.', '', uniqid( '', true ) ); mkdir( $dir, 0777, true ); diff --git a/tests/Utils/CacheTest.php b/tests/Utils/CacheTest.php index c5f9bb9..d43d7dc 100644 --- a/tests/Utils/CacheTest.php +++ b/tests/Utils/CacheTest.php @@ -131,4 +131,111 @@ public function test_remember_swr_returns_stale_without_regenerating_when_lock_i $this->assertSame( 'old', $returned, 'a losing caller is served stale immediately' ); $this->assertFalse( wp_cache_get( 'k', 'ctx-swr-locked:g' ), 'the loser must not regenerate — that is the stampede prevention' ); } + + public function test_empty_context_passes_groups_through_verbatim(): void { + $cache = new Cache(); + + $this->assertTrue( $cache->set( 'k', 'v', 'raw-group' ) ); + $this->assertSame( 'v', wp_cache_get( 'k', 'raw-group' ) ); + $this->assertSame( 'v', $cache->get( 'k', 'raw-group' ) ); + + $this->assertTrue( $cache->delete( 'k', 'raw-group' ) ); + $this->assertFalse( wp_cache_get( 'k', 'raw-group' ) ); + } + + public function test_flush_group_clears_only_the_namespaced_group(): void { + $cache = new Cache( 'ctx-flush' ); + $cache->set( 'a', 1, 'g' ); + $cache->set( 'b', 2, 'g' ); + $cache->set( 'c', 3, 'other' ); + + // Core's non-persistent cache supports group flushing (WordPress 6.1+). + $this->assertTrue( wp_cache_supports( 'flush_group' ), 'precondition: core cache supports flush_group' ); + $this->assertTrue( $cache->flush_group( 'g' ) ); + + $found = null; + $cache->get( 'a', 'g', false, $found ); + $this->assertFalse( $found ); + $cache->get( 'b', 'g', false, $found ); + $this->assertFalse( $found ); + $this->assertSame( 3, $cache->get( 'c', 'other' ), 'flushing one group must not touch another' ); + } + + public function test_remember_swr_returns_a_fresh_hit_without_invoking_the_callback(): void { + $cache = new Cache( 'ctx-swr-hit' ); + $cache->set( 'k', 'fresh', 'g', 100 ); + + $calls = 0; + $returned = $cache->remember_swr( + 'k', + static function () use ( &$calls ): string { + ++$calls; + return 'regenerated'; + }, + 'g', + 100 + ); + + $this->assertSame( 'fresh', $returned ); + $this->assertSame( 0, $calls ); + } + + public function test_remember_swr_cold_start_falls_back_to_the_callback_when_the_lock_never_frees(): void { + $cache = new Cache( 'ctx-swr-wait' ); + // Another process holds the lock on a cold start (no fresh, no stale) and + // never finishes: after the bounded wait the caller regenerates itself. + $this->assertTrue( wp_cache_add( 'k_lock', 1, 'ctx-swr-wait:g', 30 ), 'precondition: hold the lock' ); + + $calls = 0; + $returned = $cache->remember_swr( + 'k', + static function () use ( &$calls ): string { + ++$calls; + return 'computed'; + }, + 'g', + 100 + ); + + $this->assertSame( 'computed', $returned ); + $this->assertSame( 1, $calls ); + $this->assertSame( 'computed', wp_cache_get( 'k', 'ctx-swr-wait:g' ), 'the last-resort value is still cached' ); + $this->assertSame( 1, wp_cache_get( 'k_lock', 'ctx-swr-wait:g' ), 'the other process\'s lock must not be released by the fallback' ); + } + + public function test_remember_swr_cold_start_waits_for_the_lock_holder_to_publish(): void { + // Simulate the lock holder finishing during our wait: the second read of + // the fresh key (the first retry) finds the value it published. + $cache = new class( 'ctx-swr-publish' ) extends Cache { + /** + * Reads of the fresh key so far. + * + * @var int + */ + public int $fresh_reads = 0; + + public function get( string $key, string $group = '', bool $force = false, ?bool &$found = null ): mixed { + if ( 'k' === $key && 2 === ++$this->fresh_reads ) { + parent::set( 'k', 'published', $group, 100 ); + } + + return parent::get( $key, $group, $force, $found ); + } + }; + $this->assertTrue( wp_cache_add( 'k_lock', 1, 'ctx-swr-publish:g', 30 ), 'precondition: hold the lock' ); + + $calls = 0; + $returned = $cache->remember_swr( + 'k', + static function () use ( &$calls ): string { + ++$calls; + return 'computed'; + }, + 'g', + 100 + ); + + $this->assertSame( 'published', $returned ); + $this->assertSame( 0, $calls, 'a caller that sees the published value must not regenerate' ); + } } diff --git a/tests/Utils/EncryptorTest.php b/tests/Utils/EncryptorTest.php index 1509efb..4e92969 100644 --- a/tests/Utils/EncryptorTest.php +++ b/tests/Utils/EncryptorTest.php @@ -90,6 +90,81 @@ public function test_decrypt_returns_false_for_tampered_ciphertext(): void { $this->assertFalse( $encryptor->decrypt( $tampered ) ); } + public function test_decrypt_rejects_a_truncated_tag_for_every_tag_value(): void { + // Regression: a payload holding only the IV plus a 1-byte "tag" left the + // ciphertext empty, and OpenSSL authenticates a truncated GCM tag at its + // truncated length, so 1 of these 256 forgeries decrypted to ''. Every + // candidate must be rejected now, not just most of them. + $encryptor = $this->encryptor(); + $iv = str_repeat( "\x01", 12 ); + + for ( $byte = 0; $byte < 256; $byte++ ) { + $forged = base64_encode( $iv . chr( $byte ) ); + + $this->assertFalse( $encryptor->decrypt( $forged ), sprintf( 'Tag byte 0x%02x was accepted.', $byte ) ); + } + } + + /** + * @dataProvider data_short_payload_lengths + * + * @param int $length Decoded payload length, shorter than IV + tag. + */ + public function test_decrypt_rejects_payloads_shorter_than_iv_plus_tag( int $length ): void { + $this->assertFalse( $this->encryptor()->decrypt( base64_encode( str_repeat( 'x', $length ) ) ) ); + } + + /** + * @return array + */ + public function data_short_payload_lengths(): array { + return [ + 'empty' => [ 0 ], + 'shorter than the IV' => [ 5 ], + 'IV only' => [ 12 ], + 'IV plus partial tag' => [ 27 ], + ]; + } + + public function test_empty_plaintext_roundtrips(): void { + // The smallest legitimate payload is IV + full tag with no ciphertext; + // the length guard must still let it through. + $encryptor = $this->encryptor(); + $encrypted = $encryptor->encrypt( '' ); + + $this->assertIsString( $encrypted ); + $this->assertSame( 28, strlen( (string) base64_decode( $encrypted, true ) ) ); + $this->assertSame( '', $encryptor->decrypt( $encrypted ) ); + } + + /** + * An Encryptor that behaves as if the OpenSSL extension were missing. + */ + private function encryptor_without_openssl(): Encryptor { + return new class( self::KEY ) extends Encryptor { + protected function is_openssl_available(): bool { + return false; + } + }; + } + + public function test_encrypt_fails_closed_without_openssl(): void { + $encryptor = $this->encryptor_without_openssl(); + $this->setExpectedIncorrectUsage( Encryptor::class . '::encrypt' ); + + $this->assertFalse( $encryptor->encrypt( 'secret' ) ); + } + + public function test_decrypt_fails_closed_without_openssl(): void { + $encrypted = $this->encryptor()->encrypt( 'secret' ); + $this->assertIsString( $encrypted ); + + $encryptor = $this->encryptor_without_openssl(); + $this->setExpectedIncorrectUsage( Encryptor::class . '::decrypt' ); + + $this->assertFalse( $encryptor->decrypt( $encrypted ) ); + } + public function test_key_seam_can_be_overridden_by_a_subclass(): void { // A subclass can source the key from anywhere via the key() seam, while // reusing the crypto unchanged. diff --git a/tests/Utils/TimerTest.php b/tests/Utils/TimerTest.php index a3372bd..5ae6e68 100644 --- a/tests/Utils/TimerTest.php +++ b/tests/Utils/TimerTest.php @@ -126,6 +126,16 @@ public function test_lap_after_stop_warns(): void { $this->timer->lap( 'stopped_lap', 'too_late' ); } + public function test_lap_empty_label_warns_and_records_nothing(): void { + $this->setExpectedIncorrectUsage( Timer::class . '::lap' ); + + $this->timer->start( 'lap_target' ); + $this->timer->lap( '', 'split' ); + + $data = $this->timer->get( 'lap_target' ); + $this->assertEmpty( $data['laps'], 'an empty label must not record a lap on any timer' ); + } + public function test_lap_empty_name_warns_and_records_nothing(): void { $this->setExpectedIncorrectUsage( Timer::class . '::lap' ); diff --git a/tests/Utils/TransientsTest.php b/tests/Utils/TransientsTest.php index 2a105ac..9d3c18d 100644 --- a/tests/Utils/TransientsTest.php +++ b/tests/Utils/TransientsTest.php @@ -73,6 +73,55 @@ public function test_prefix_key_boundary_is_unambiguous(): void { $this->assertSame( 'two', $two->get( 'y' ) ); } + public function test_over_long_key_still_round_trips_through_the_database(): void { + // Regression: a namespaced name past 172 characters was truncated by the + // options table, so once the in-request option cache was gone (a new request) + // the value could never be read back. Flushing the object cache simulates that. + $store = new Transients( 'rt_long' ); + $key = str_repeat( 'k', 200 ); + + $this->assertTrue( $store->set( $key, 'long-value', HOUR_IN_SECONDS ) ); + + wp_cache_flush(); + + $this->assertSame( 'long-value', $store->get( $key ) ); + $this->assertTrue( $store->delete( $key ) ); + $this->assertFalse( $store->get( $key ) ); + } + + public function test_over_long_keys_stay_distinct_and_within_the_limit(): void { + $store = new Transients( 'rt_long_distinct' ); + $first = str_repeat( 'a', 180 ) . '-one'; + $other = str_repeat( 'a', 180 ) . '-two'; + + $store->set( $first, 'one' ); + $store->set( $other, 'two' ); + wp_cache_flush(); + + $this->assertSame( 'one', $store->get( $first ) ); + $this->assertSame( 'two', $store->get( $other ) ); + + $resolve = new \ReflectionMethod( Transients::class, 'resolve_key' ); + $name = $resolve->invoke( $store, $first ); + + $this->assertLessThanOrEqual( 172, strlen( $name ) ); + $this->assertStringStartsWith( 'h:', $name ); + } + + public function test_key_at_the_limit_is_not_hashed(): void { + // '5:rt_ok_' is 8 characters, so a 164-character key lands exactly on 172. + $store = new Transients( 'rt_ok' ); + $key = str_repeat( 'k', 164 ); + $resolve = new \ReflectionMethod( Transients::class, 'resolve_key' ); + + $this->assertSame( '5:rt_ok_' . $key, $resolve->invoke( $store, $key ) ); + + $store->set( $key, 'at-limit', HOUR_IN_SECONDS ); + wp_cache_flush(); + + $this->assertSame( 'at-limit', $store->get( $key ) ); + } + public function test_value_is_stored_under_the_namespaced_key(): void { ( new Transients( 'rt_ns' ) )->set( 'thing', 'v' );