Skip to content

AGENTS.md

Latest commit

 

History

History
177 lines (139 loc) · 8.06 KB

AGENTS.md

File metadata and controls

177 lines (139 loc) · 8.06 KB

FakerPress — Agent & Developer Guide

Prerequisites

Tool Version Notes
PHP 8.1+ MAMP, Homebrew, or system PHP
Composer 2.x getcomposer.org
Node 18.17 Matches .nvmrc — use nvm use
npm 9.6.7 Ships with Node 18.17
WordPress 6.4+ Local install (MAMP, Local, Valet, etc.)

Quick Start

# 1. Install PHP dependencies + build vendor/prefixed packages (Strauss)
composer install

# 2. Install Node dependencies
nvm use && npm install

# 3. Build JS and CSS assets
npm run build

After these three steps the plugin is ready to activate in WordPress.

Build Commands

PHP (Composer)

Command What it does
composer install Install deps + run Strauss (auto via post-install hook)
composer strauss Re-run Strauss manually (namespace-prefix third-party packages into vendor/prefixed/)
composer dump-autoload Regenerate autoloader without reinstalling

Strauss vendor-prefixes all third-party packages under FakerPress\ThirdParty\ into vendor/prefixed/. This runs automatically on composer install and composer update.

JS / CSS (npm + @wordpress/scripts)

Command What it does
npm run build Production build — compiles JS and PostCSS into build/ and src/resources/css/
npm run start Watch mode with source maps for development
npm run lint Lint JS and CSS
npm run format:js Auto-fix JS lint issues
npm run format:css Auto-fix CSS lint issues

Source files:

  • JS: src/resources/js/*.js — compiled to build/js/ and exposed on window.fakerpress
  • CSS: src/resources/pcss/*.pcss — PostCSS compiled to src/resources/css/
  • Packages: src/resources/packages/ — modern module entry points compiled to build/packages/

Build tool: @wordpress/scripts with custom webpack config (webpack.config.js) using @stellarwp/tyson helpers.

Gitignored Build Artifacts

These directories are generated and must NOT be committed:

  • vendor/ — Composer dependencies (includes vendor/prefixed/ — Strauss-prefixed packages)
  • build/ — Compiled JS/CSS bundles
  • src/resources/css/ — Compiled CSS output
  • node_modules/ — Node dependencies
  • bin/ — Downloaded tool binaries (strauss.phar, etc.)

Project Structure

fakerpress.php                  # Plugin entry point, defines __FP_FILE__
src/
├── FakerPress/
│   ├── Plugin.php              # Boot, container bindings, autoload
│   ├── Module/                 # Data generation modules (Post, User, Term, Comment, Attachment)
│   │   ├── Abstract_Module.php # set() → generate() → save() chain
│   │   └── Factory.php         # Module registry
│   ├── Provider/               # Faker providers (WP_Post, WP_User, HTML, Image/*)
│   ├── REST/                   # REST API (v1) — endpoints, controller, OpenAPI docs
│   │   ├── Controller.php      # Service provider, registers routes on rest_api_init
│   │   ├── Abstract_Endpoint.php
│   │   └── Endpoints/          # Posts, Users, Terms, Comments, Attachments, Documentation
│   ├── Admin/                  # Admin pages and views
│   ├── Ajax.php                # Legacy AJAX handlers (Select2 only, generate moved to REST)
│   ├── Assets.php              # Script/style registration
│   └── Field.php               # Legacy form field renderer (deprecated, do not extend)
├── functions/                  # Helper functions (container.php, load.php, etc.)
├── resources/
│   ├── js/                     # Source JS files
│   ├── pcss/                   # Source PostCSS files
│   └── img/                    # Static images (SVG icon)
└── templates/                  # PHP view templates

Architecture Notes

  • Container: DI52 (vendor/prefixed). Use helpers: singleton(), make(), bind(), register()
  • Module lifecycle: $module->set(params)->generate()->save() — parse_request() orchestrates this
  • REST namespace: fakerpress/v1 — endpoints at /fakerpress/v1/{module}/generate
  • Service Providers: extend FakerPress\Contracts\Service_Provider, registered via Plugin::register()
  • Version: Plugin::VERSION in src/FakerPress/Plugin.php

Testing

Test Commands

Command What it does
composer test:wpunit Run WPUnit integration tests via Codeception
vendor/bin/codecept run wpunit Run WPUnit tests directly
composer lint:php Run PHPCS code standards checks
composer lint:php:fix Auto-fix PHPCS violations with PHPCBF

Test Directory Structure

tests/
├── _bootstrap.php              # Global test bootstrap
├── _data/                      # Test fixtures and data
├── _output/                    # Test output (gitignored)
├── _support/
│   ├── WpunitTester.php        # Actor class
│   ├── _generated/             # Auto-generated actor methods (gitignored)
│   └── Helper/
│       └── Wpunit.php          # Custom helper module
├── wpunit.suite.dist.yml       # Suite config (WPLoader + Asserts)
└── wpunit/
    ├── _bootstrap.php          # Suite bootstrap (WPLoader handles WP)
    └── PluginTest.php          # Plugin smoke tests

Running Tests Locally

  1. Create a .env.testing file (gitignored) with your local WordPress paths: 
    WP_ROOT_FOLDER=/path/to/wordpress
WP_URL=http://fakerpress.test
WP_DOMAIN=fakerpress.test
WP_DB_URL=mysql://root:root@127.0.0.1:3306/fakerpress_test
WP_TABLE_PREFIX=wp_
  2. Run composer test:wpunit

Running Tests with SLIC

SLIC containers use codeception.slic.yml and .env.testing.slic automatically.

Coding Standards

  • PHP: WordPress Coding Standards. Short array syntax ([]). Early returns to reduce nesting.
  • JavaScript: ES6 with @wordpress/scripts linting. Modules exposed on window.fakerpress.
  • CSS: PostCSS with postcss-nested (not native CSS nesting). & means "this element".
  • Docblocks: @since <current_version_in_dev> for new code (check Plugin::VERSION). Aligned params. Period-terminated descriptions.
  • Namespacing: PSR-4 autoloading under FakerPress\. Third-party code under FakerPress\ThirdParty\.
  • Security: Nonce verification on all requests. Capability checks via get_permission_required(). Sanitize all input.

PHPCS — Validating PHP Code

Before writing or modifying PHP code, internalize these rules so you write compliant code on the first pass — do NOT write code and then fix lint errors in a second pass.

Key rules enforced by phpcs.xml (WordPress + StellarWP + VIP-Go):

  • Tabs for indentation, never spaces. All PHP files use tabs.
  • Yoda conditions disabled — write $var === true, not true === $var.
  • Spaces inside parentheses — if ( $condition ), not if ($condition).
  • Spaces after commas — func( $a, $b ), not func($a,$b).
  • Opening brace on same line — function foo() {, if ( $x ) {.
  • snake_case for functions and variables, UPPER_SNAKE for constants.
  • Short array syntax — [] not array() (Generic.Arrays.DisallowLongArraySyntax).
  • No else — prefer early returns over else blocks.
  • Strict comparisons — === / !==, never == / !=.
  • Escaping output — esc_html(), esc_attr(), wp_kses(), etc. on all echoed values.
  • Nonce verification — wp_verify_nonce() / check_ajax_referer() on all form/AJAX handlers.
  • Direct DB queries — use $wpdb->prepare(), never interpolate. Excluded in src/Test.php.
  • No extract(), no eval(), no compact() in new code.

Run composer lint:php -- <file> to check a single file. Run composer lint:php:fix -- <file> to auto-fix.

When making changes to PHP files, run composer lint:php -- <changed-files> against only the files you touched before considering the task done. Do NOT run PHPCS against the entire codebase.