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
10 changes: 5 additions & 5 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# Copilot instructions — wp-framework
# Copilot instructions — wp-primitives

`rtcamp/wp-framework`: shared base contracts (interfaces, abstracts, traits) and small utilities consumed via Composer by every rtCamp plugin/theme skeleton. **Zero runtime dependencies.** PHP 8.2+.
`rtcamp/wp-primitives`: shared base contracts (interfaces, abstracts, traits) and small utilities consumed via Composer by every rtCamp plugin/theme skeleton. **Zero runtime dependencies.** PHP 8.2+.

This repo defines the framework itself. The rules for *consuming* it live in `ai/framework-php.instructions.md` (shipped to consumers); keep it in sync when contracts change.
This repo defines the framework itself. The rules for *consuming* it live in `ai/primitives-php.instructions.md` (shipped to consumers); keep it in sync when contracts change.

Detailed rules: `.github/instructions/php.instructions.md`.

## Stack

- PHP 8.2+, PSR-4 `rtCamp\WPFramework\` → `inc/`; tests `rtCamp\WPFramework\Tests\` → `tests/`.
- PHP 8.2+, PSR-4 `rtCamp\WPPrimitives\` → `inc/`; tests `rtCamp\WPPrimitives\Tests\` → `tests/`.
- PHPUnit; PHPCS (WordPress-Core/Extra/Docs + VIPCS); PHPStan. Zero errors before merge.
- `require` in `composer.json` holds **only** `php`. Everything else is `require-dev`.

## Universal rules

- **TDD**: failing PHPUnit test first (`tests/` mirrors `inc/`), then code.
- **`inc/Contracts/` is public API.** Interfaces, abstracts and their method signatures are consumed by every plugin/theme: a signature change breaks all of them. Treat changes as breaking.
- When you change a contract, update `ai/framework-php.instructions.md` so the consumer review rules stay accurate.
- When you change a contract, update `ai/primitives-php.instructions.md` so the consumer review rules stay accurate.
- No runtime dependencies. Prefer official WordPress / PHP stdlib.

## Review conduct
Expand Down
2 changes: 1 addition & 1 deletion .github/instructions/php.instructions.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
applyTo: "inc/**/*.php"
description: "Framework-development rules for rtcamp/wp-framework PHP."
description: "Framework-development rules for rtcamp/wp-primitives PHP."
---

# Framework PHP rules
Expand Down
2 changes: 1 addition & 1 deletion .wp-env.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"core": null,
"phpVersion": "8.2",
"mappings": {
"wp-content/wp-framework-rt": "."
"wp-content/wp-primitives-rt": "."
},
"env": {
"tests": {
Expand Down
14 changes: 7 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# AGENTS.md — wp-framework
# AGENTS.md — wp-primitives

Tool-agnostic brief for AI coding agents (Claude Code, Copilot coding agent, Codex). `rtcamp/wp-framework`: shared base contracts (interfaces, abstracts, traits) and small utilities consumed via Composer by every rtCamp plugin/theme skeleton. **Zero Composer runtime dependencies.** PHP 8.2+, WordPress 6.5+ — the floor is set by the Script Modules API (`wp_register_script_module()`, new in 6.5). The APIs used above 6.5 are `wp_register_block_types_from_metadata_collection()` (6.8+), which `AssetLoader::register_block_manifest()` guards with a per-block fallback for 6.5–6.7, and the Abilities API (6.9+), which the ability abstracts reach only through `wp_abilities_api_*` hooks that never fire on older cores. `Encryptor` requires the OpenSSL PHP extension when used.
Tool-agnostic brief for AI coding agents (Claude Code, Copilot coding agent, Codex). `rtcamp/wp-primitives`: shared base contracts (interfaces, abstracts, traits) and small utilities consumed via Composer by every rtCamp plugin/theme skeleton. **Zero Composer runtime dependencies.** PHP 8.2+, WordPress 6.5+ — the floor is set by the Script Modules API (`wp_register_script_module()`, new in 6.5). The APIs used above 6.5 are `wp_register_block_types_from_metadata_collection()` (6.8+), which `AssetLoader::register_block_manifest()` guards with a per-block fallback for 6.5–6.7, and the Abilities API (6.9+), which the ability abstracts reach only through `wp_abilities_api_*` hooks that never fire on older cores. `Encryptor` requires the OpenSSL PHP extension when used.

## Authoritative rules

Expand All @@ -12,15 +12,15 @@ Tool-agnostic brief for AI coding agents (Claude Code, Copilot coding agent, Cod
- **`inc/Contracts/` is public API.** Interfaces, abstracts, and their method signatures are consumed by every plugin/theme: a signature change breaks all of them. Treat such changes as breaking.
- **Zero Composer runtime deps**: `composer.json` `require` holds only `php`; everything else is `require-dev`.
- **TDD**: failing PHPUnit test first (`tests/` mirrors `inc/`), then code.
- **Tests run against real WordPress via wp-env** — no WP function mocking. `npm run wp-env start` then `npm run test:php` (a `pretest:php` hook runs `composer install` in the container first). WP-dependent tests extend `rtCamp\WPFramework\Tests\TestCase` (a `WP_UnitTestCase`); pure-logic tests can stay on `PHPUnit\Framework\TestCase`. CI runs a PHP × WP matrix (PHP 8.2+, WP 6.5+).
- `declare( strict_types = 1 );`, full types, `@package`/`@since`, `static::` not `self::`, PSR-4 (`rtCamp\WPFramework\` → `inc/`).
- **When you change a contract, update `ai/framework-php.instructions.md`**: the rules file shipped to consumers and synced into their `.github/` by `bin/sync-ai-instructions.js` (`npm run sync-ai`).
- **Tests run against real WordPress via wp-env** — no WP function mocking. `npm run wp-env start` then `npm run test:php` (a `pretest:php` hook runs `composer install` in the container first). WP-dependent tests extend `rtCamp\WPPrimitives\Tests\TestCase` (a `WP_UnitTestCase`); pure-logic tests can stay on `PHPUnit\Framework\TestCase`. CI runs a PHP × WP matrix (PHP 8.2+, WP 6.5+).
- `declare( strict_types = 1 );`, full types, `@package`/`@since`, `static::` not `self::`, PSR-4 (`rtCamp\WPPrimitives\` → `inc/`).
- **When you change a contract, update `ai/primitives-php.instructions.md`**: the rules file shipped to consumers and synced into their `.github/` by `bin/sync-ai-instructions.js` (`npm run sync-ai`).

## Structure

`inc/Contracts/{Interfaces,Abstracts,Traits}/` (the consumed contract surface), `inc/` root (`Container`, `AssetLoader`, `ComponentLoader`, `TemplateLoader`), `inc/Utils/`. `ai/` holds the canonical consumer instruction doc; `bin/` holds the sync tool.

## This repo also ships tooling for consumers

- `ai/framework-php.instructions.md`: the canonical framework+WordPress review rules.
- `bin/sync-ai-instructions.js`: run from a consumer via `npm run sync-ai` (chained from `npm run init`). Refreshes each package's `framework-php.instructions.md` from its vendored copy of this doc, then projects every package's instructions up to the `wp-content` repo root for Copilot review. Standalone packages get the refresh only. `--check` for CI.
- `ai/primitives-php.instructions.md`: the canonical framework+WordPress review rules.
- `bin/sync-ai-instructions.js`: run from a consumer via `npm run sync-ai` (chained from `npm run init`). Refreshes each package's `primitives-php.instructions.md` from its vendored copy of this doc, then projects every package's instructions up to the `wp-content` repo root for Copilot review. Standalone packages get the refresh only. `--check` for CI.
31 changes: 26 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,33 @@
# Changelog

All notable changes to `rtcamp/wp-framework` are documented here.
All notable changes to `rtcamp/wp-primitives` are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### 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
Comment thread
AnuragVasanwala marked this conversation as resolved.
Resolved
this package, so nothing in-repo breaks, but any consumer shipping translations for
the old domain must retarget them.

### Documentation

- Added implementor getting-started and maintainer workflow guides; corrected
Expand All @@ -16,7 +37,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
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 `^1.0` constraint.
the consumer needs a VCS `repositories` entry and a `^2.0` constraint.
- 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 @@ -79,6 +100,6 @@ 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-framework/compare/v1.0.1...HEAD
[1.0.1]: https://github.com/rtCamp/wp-framework/compare/v1.0.0...v1.0.1
[1.0.0]: https://github.com/rtCamp/wp-framework/releases/tag/v1.0.0
[Unreleased]: https://github.com/rtCamp/wp-primitives/compare/v1.0.1...HEAD
[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
6 changes: 3 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contributing to wp-framework
# Contributing to wp-primitives

Thanks for your interest in improving `rtcamp/wp-framework`. This is a
Thanks for your interest in improving `rtcamp/wp-primitives`. This is a
**library** — a shared PHP base consumed as a Composer package by rtCamp
WordPress plugins and themes — so its public contract (`inc/Contracts/`) is
treated as stable and changes to it are considered breaking.
Expand Down Expand Up @@ -58,7 +58,7 @@ contract-change, and documentation guidance.
- [ ] `composer lint`, `composer analyse`, and `npm run test:php` pass.
- [ ] New/changed behavior is covered by tests.
- [ ] Any change to `inc/Contracts/` is flagged as breaking in the PR description.
- [ ] Contract changes are reflected in `ai/framework-php.instructions.md`.
- [ ] Contract changes are reflected in `ai/primitives-php.instructions.md`.
- [ ] User-visible behavior is reflected in `README.md` or `docs/`.
- [ ] A `CHANGELOG.md` entry is added under `## [Unreleased]`.
- [ ] Commits follow [Conventional Commits](https://www.conventionalcommits.org/).
Expand Down
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<h1 align="center">wp-framework</h1>
<h1 align="center">wp-primitives</h1>

<p align="center">
<a href="LICENSE.md"><img src="https://img.shields.io/badge/license-GPL--2.0--or--later-blue.svg" alt="License: GPL-2.0-or-later"></a>
Expand All @@ -8,14 +8,14 @@

<p align="center">
A shared PHP base for WordPress projects, distributed as a Composer package
(<code>rtcamp/wp-framework</code>). It ships the contracts, loaders, and
(<code>rtcamp/wp-primitives</code>). It ships the contracts, loaders, and
utilities that plugins and themes boot through — so you write intent instead
of registration boilerplate.
</p>

---

`wp-framework` is a **library, not a plugin**. It ships contracts (interfaces,
`wp-primitives` is a **library, not a plugin**. It ships contracts (interfaces,
abstracts, traits) plus concrete loaders and utilities; consuming plugins and
themes build their features on top. It has **zero Composer runtime dependencies**.

Expand All @@ -34,26 +34,26 @@ Not on public Packagist — add the repository to the consuming project's
```json
{
"repositories": [
{ "type": "vcs", "url": "https://github.com/rtCamp/wp-framework" }
{ "type": "vcs", "url": "https://github.com/rtCamp/wp-primitives" }
]
}
```

```bash
composer require rtcamp/wp-framework:^1.0
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\WPFramework\` → `inc/`.
PSR-4 autoloading: `rtCamp\WPPrimitives\` → `inc/`.

## Quick look

```php
use rtCamp\WPFramework\Contracts\Abstracts\AbstractPostType;
use rtCamp\WPFramework\Contracts\Traits\Loader;
use rtCamp\WPFramework\Contracts\Traits\Singleton;
use rtCamp\WPPrimitives\Contracts\Abstracts\AbstractPostType;
use rtCamp\WPPrimitives\Contracts\Traits\Loader;
use rtCamp\WPPrimitives\Contracts\Traits\Singleton;

final class ArticlePostType extends AbstractPostType {
public static function get_slug(): string { return 'article'; }
Expand Down
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
applyTo: "**/*.php"
description: "Framework + WordPress rules for PHP. Canonical source, shipped by rtcamp/wp-framework."
description: "Framework + WordPress rules for PHP. Canonical source, shipped by rtcamp/wp-primitives."
---

# PHP rules: framework, WordPress, security, tests

`rtcamp/wp-framework` (`rtCamp\WPFramework`) is in gitignored `vendor/` (invisible at review). These rules ARE its contract.
`rtcamp/wp-primitives` (`rtCamp\WPPrimitives`) is in gitignored `vendor/` (invisible at review). These rules ARE its contract.

## Architecture

Expand Down Expand Up @@ -51,4 +51,4 @@ Flag genuine contract/security violations, not style. Allow any correct implemen
5. 🚩 A class calling `register_post_type`/`register_taxonomy`/`register_rest_route`/`add_menu_page`/`add_shortcode`/`register_block_type`/`wp_register_ability` directly instead of extending the matching `Abstract*` (`AbstractPostType`, `AbstractRESTController`, `AbstractAdminPage`, …). Name the abstract to extend.
6. 🚩 Missing `strict_types`/types/docblocks; PSR-4 mismatch; `self::` for LSB.
7. 🚩 Missing escape/sanitize/nonce/capability; raw `$wpdb` without `prepare()`; REST without a real `permission_callback`; inline assets; wrong/absent text domain.
8. 🚩 Edit under `vendor/rtcamp/wp-framework` or WordPress core.
8. 🚩 Edit under `vendor/rtcamp/wp-primitives` or WordPress core.
40 changes: 32 additions & 8 deletions bin/sync-ai-instructions.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@
/**
* Sync AI / Copilot instructions for rtCamp WordPress projects.
*
* Shipped by rtcamp/wp-framework; run from a consuming package via `npm run sync-ai`
* Shipped by rtcamp/wp-primitives; run from a consuming package via `npm run sync-ai`
* (chained from `npm run init`). Does two jobs in one pass:
*
* 1. Refresh: copy the canonical framework rules from each package's
* vendor/rtcamp/wp-framework/ai/framework-php.instructions.md into that
* package's .github/instructions/framework-php.instructions.md.
* vendor/rtcamp/wp-primitives/ai/primitives-php.instructions.md into that
* package's .github/instructions/primitives-php.instructions.md.
* 2. Project: if the package sits inside a wp-content root (an ancestor
* containing plugins/), write every package's instructions to that root's
* .github/instructions/ with applyTo globs re-scoped to the root, so GitHub
Expand All @@ -29,8 +29,14 @@ const fs = require( 'fs' );
const path = require( 'path' );

const PACKAGE_DIRS = [ 'plugins', 'themes' ];
const FRAMEWORK_SRC = 'vendor/rtcamp/wp-framework/ai/framework-php.instructions.md';
const MARKER = '<!-- GENERATED by rtcamp/wp-framework; edit the source, not here. -->';
const FRAMEWORK_SRC = 'vendor/rtcamp/wp-primitives/ai/primitives-php.instructions.md';
const MARKER = '<!-- GENERATED by rtcamp/wp-primitives; edit the source, not here. -->';

// Pre-2.0 this package was rtcamp/wp-framework and shipped framework-php.instructions.md.
// Consumers upgrading across the rename still have the old file committed; recognise it so
// refreshPackage() can delete it and the root prune step can sweep any projected copies.
const LEGACY_INSTRUCTION_FILE = 'framework-php.instructions.md';
const LEGACY_MARKER = '<!-- GENERATED by rtcamp/wp-framework; edit the source, not here. -->';

// Copilot code review reads only the first ~4000 chars of an instruction file.
const COPILOT_CHAR_LIMIT = 4000;
Expand Down Expand Up @@ -174,7 +180,7 @@ const writeIfChanged = ( outPath, content, relRoot, verb ) => {
};

/**
* Step 1 — refresh a package's framework-php copy from its vendored framework.
* Step 1 — refresh a package's primitives-php copy from its vendored package.
*
* @param {string} base Package root.
* @param {string} relRoot Root for log labels.
Expand All @@ -185,8 +191,20 @@ const refreshPackage = ( base, relRoot ) => {
if ( ! fs.existsSync( src ) ) {
return false;
}
const dest = path.join( base, '.github', 'instructions', 'framework-php.instructions.md' );
const dest = path.join( base, '.github', 'instructions', 'primitives-php.instructions.md' );
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.
const legacy = path.join( base, '.github', 'instructions', LEGACY_INSTRUCTION_FILE );
if ( fs.existsSync( legacy ) ) {
drift = true;
log.push( color.red( ` prune ${ relRoot }/.github/instructions/${ LEGACY_INSTRUCTION_FILE }` ) );
if ( ! isCheck ) {
fs.unlinkSync( legacy );
}
}

return true;
};

Expand Down Expand Up @@ -226,7 +244,13 @@ const projectToRoot = ( root, packages ) => {
if ( fs.existsSync( outDir ) ) {
const wanted = new Set( Object.keys( outputs ) );
fs.readdirSync( outDir )
.filter( ( f ) => ! wanted.has( f ) && fs.readFileSync( path.join( outDir, f ), 'utf8' ).includes( MARKER ) )
.filter( ( f ) => {
if ( wanted.has( f ) ) {
return false;
}
const body = fs.readFileSync( path.join( outDir, f ), 'utf8' );
return body.includes( MARKER ) || body.includes( LEGACY_MARKER );
} )
.forEach( ( f ) => {
drift = true;
log.push( color.red( ` prune .github/instructions/${ f }` ) );
Expand Down
17 changes: 11 additions & 6 deletions composer.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
{
"name": "rtcamp/wp-framework",
"name": "rtcamp/wp-primitives",
"description": "Shared PHP utilities for rtCamp WordPress projects",
"type": "library",
"license": "GPL-2.0-or-later",
"homepage": "https://github.com/rtCamp/wp-framework",
"homepage": "https://github.com/rtCamp/wp-primitives",
"support": {
"issues": "https://github.com/rtCamp/wp-framework/issues",
"source": "https://github.com/rtCamp/wp-framework"
"issues": "https://github.com/rtCamp/wp-primitives/issues",
"source": "https://github.com/rtCamp/wp-primitives"
},
"require": {
"php": ">=8.2"
Expand All @@ -25,12 +25,12 @@
},
"autoload": {
"psr-4": {
"rtCamp\\WPFramework\\": "inc/"
"rtCamp\\WPPrimitives\\": "inc/"
}
},
"autoload-dev": {
"psr-4": {
"rtCamp\\WPFramework\\Tests\\": "tests/"
"rtCamp\\WPPrimitives\\Tests\\": "tests/"
}
},
"config": {
Expand Down Expand Up @@ -58,6 +58,11 @@
"test": "Run the PHPUnit test suite.",
"check": "Run lint + analyse + test in sequence. Exit code 0 if all green."
},
"extra": {
"branch-alias": {
"dev-main": "2.0.x-dev"
Comment thread
AnuragVasanwala marked this conversation as resolved.
Resolved
}
},
"minimum-stability": "stable",
"prefer-stable": true
}
Loading
Loading