Development

Development

Stack

• PHP 8.2+ with declare(strict_types=1) and typed signatures throughout
• React + TypeScript for the block-editor UI, compiled by @wordpress/scripts
• Native Gutenberg APIs (@wordpress/blocks, @wordpress/block-editor, @wordpress/components) — no third-party editor frameworks

Project structure

pv-blocks-suite/
├── pv-blocks-suite.php     # Plugin bootstrap
├── composer.json           # PHPStan, PSR-4 autoloading
├── package.json
├── phpstan.neon
├── phpcs.xml.dist
├── .wp-env.json             # Development environment (port 8888)
├── .wp-env.tests.json       # Test environment (port 8889)
├── includes/
│   ├── class-block-loader.php     # Auto-registers blocks from src/blocks/*/block.json
│   └── class-block-categories.php # Registers the "PV Blocks Suite" inserter category
├── src/
│   ├── blocks/
│   │   └── {block-name}/
│   │       ├── block.json
│   │       ├── edit.tsx
│   │       ├── render.php   # Dynamic (server-side) render
│   │       ├── style.scss
│   │       └── test/
│   └── shared/
│       ├── components/
│       └── hooks/
└── build/                    # Compiled assets (generated)

Every block lives in its own folder under src/blocks/ and is discovered automatically by Block_Loader — adding a new block never requires touching the bootstrap.

Local environment

Local development runs on @wordpress/env (wp-env), with separate configurations for development and automated tests:

Command	Description
npm run env:start	Start the development site (localhost:8888)
npm run env:start:tests	Start the test environment (localhost:8889)
npm run env:stop	Stop the development site
npm run env:stop:tests	Stop the test environment
npm run env:destroy	Remove the development environment
npm run env:destroy:tests	Remove the test environment
npm run start	Start the webpack dev build in watch mode
npm run build	Produce a production build

Quality tooling

Every change is expected to pass the full quality gate before merging:

Tool	Command	What it checks
PHPStan (level 5+)	npm run lint:php:stan	Static analysis, with WordPress core stubs
PHP_CodeSniffer (WPCS)	npm run lint:php	WordPress-Extra coding standards
PHPUnit (wp-phpunit)	npm run test:php	Server-side rendering, real WP_UnitTestCase integration
Jest (wp-scripts)	npm run test:js	Editor component behavior via Testing Library
TypeScript	npm run typecheck	Type-checking only, build stays on Babel

Auto-fixable WPCS violations can be corrected with npm run lint:php:fix.

Every block's block.json must declare the pv-blocks-suite inserter category and an example with realistic sample attributes — both are checked by Block_Categories_Test/Block_Examples_Test as part of npm run test:php.