This guide explains all the development tools configured for this project and how to customize them.
Purpose: Enforces WordPress and PSR coding standards.
Configuration: phpcs.xml.dist
Key Settings:
src/ directory onlyvendor/, node_modules/, tests/, assets/, minified filesUsage:
# Check code
composer run lint:php
# Auto-fix issues
composer run fix:php
# Check specific file
./vendor/bin/phpcs src/core/SparxstarGluonCore.php
Customization:
To change text domain:
<property name="text_domain" type="array">
<element value="your-text-domain"/>
</property>
To change prefix:
<property name="prefixes" type="array">
<element value="your_prefix"/>
</property>
Purpose: Finds bugs and type errors without running code.
Configuration: phpstan.neon.dist
Key Settings:
src/ onlyphpstan-baseline.neon (existing errors)Usage:
# Run analysis
composer run analyze:php
# Generate new baseline (to accept current errors)
./vendor/bin/phpstan analyse --generate-baseline
# Check specific file
./vendor/bin/phpstan analyse src/core/SparxstarGluonCore.php
Customization:
Increase strictness:
parameters:
level: 8 # Max level
Add custom ignores:
ignoreErrors:
- '#Your custom error pattern#'
Purpose: Automatically modernizes PHP code and applies best practices.
Configuration: rector.php
Key Settings:
src/ onlyUsage:
# Preview changes
composer run refactor:php
# Apply changes
composer run refactor:php:fix
# Process specific file
./vendor/bin/rector process src/core/SparxstarGluonCore.php
Customization:
Skip specific rules:
->withSkip([
YourRuleClass::class,
])
Add custom paths:
->withPaths([
__DIR__ . '/src',
__DIR__ . '/includes',
])
Purpose: Unit testing framework for PHP.
Configuration: phpunit.xml.dist
Usage:
# Run all tests
composer run test:php
# Run specific test
./vendor/bin/phpunit tests/phpunit/ExampleTest.php
# With coverage (requires Xdebug)
./vendor/bin/phpunit --coverage-html coverage/
Customization:
Add test suites:
<testsuite name="Integration Tests">
<directory>tests/integration</directory>
</testsuite>
Purpose: Lints JavaScript code for errors and style issues.
Configuration: eslint.config.js
Key Settings:
Usage:
# Lint JS files
npm run lint:js
# Auto-fix
npx eslint src/js --fix
# Check specific file
npx eslint src/js/admin.js
Customization:
Add custom rules:
rules: {
'no-console': 'warn',
'prefer-const': 'error',
}
Add TypeScript support:
// Install: npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin
parser: '@typescript-eslint/parser',
plugins: ['@typescript-eslint'],
Purpose: JavaScript unit testing framework.
Configuration: jest.config.js
Usage:
# Run tests
npm test
# Watch mode
npm test -- --watch
# Coverage
npm test -- --coverage
# Specific file
npm test -- src/js/__tests__/example.test.js
Customization:
Configure in jest.config.js:
module.exports = {
testEnvironment: 'jsdom', // For DOM testing
coverageThreshold: {
global: {
statements: 80,
branches: 80,
functions: 80,
lines: 80,
},
},
};
Purpose: Lints CSS for errors and enforces style conventions.
Configuration: .stylelintrc.json
Key Settings:
.stylelintignore (vendor, node_modules, assets, minified files)Usage:
# Lint CSS
npm run lint:css
# Auto-fix
npx stylelint "src/css/**/*.css" --fix
# Specific file
npx stylelint src/css/admin.css
Customization:
Add rules in .stylelintrc.json:
{
"extends": "stylelint-config-standard",
"rules": {
"color-hex-length": "short",
"max-nesting-depth": 3
}
}
Purpose: End-to-end browser testing.
Configuration: playwright.config.js
Key Settings:
tests/e2eUsage:
# Run all tests
npm run test:e2e
# Specific browser
npx playwright test --project=chromium
# Headed mode (see browser)
npx playwright test --headed
# Debug
npx playwright test --debug
# Generate tests interactively
npx playwright codegen http://localhost:8080
Customization:
export default defineConfig({
retries: 3, // Retry failed tests
workers: 4, // Parallel workers
timeout: 30000, // Test timeout
});
Purpose: Headless Chrome automation (alternative to Playwright).
Usage:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('http://localhost:8080');
// Your automation code
await browser.close();
})();
Purpose: Minifies JavaScript files.
Configuration: scripts/build-js.js
Settings:
src/js/**/*.jsassets/js/**/*.min.jsCustomization:
Edit scripts/build-js.js:
const result = await minify(code, {
compress: {
drop_console: true, // Remove all console
drop_debugger: true,
passes: 3,
},
mangle: {
toplevel: true,
},
});
Purpose: Minifies CSS files.
Configuration: scripts/build-css.js
Settings:
src/css/**/*.cssassets/css/**/*.min.cssCustomization:
Edit scripts/build-css.js to add options:
const cmd = `npx cleancss -o "${destFile}" --compatibility ie9 --level 2 "${srcFile}"`;
Purpose: Generates translation POT files.
Usage:
# Generate POT file
npm run makepot
# Or directly
wp i18n make-pot . languages/plugin-textdomain.pot --domain=plugin-textdomain
Purpose: Runs scripts before Git commits.
Configuration: .husky/ directory
Setup:
npm run prepare
Purpose: Runs linters only on staged files.
Configuration: package.json
Settings:
Customization:
Edit package.json:
"lint-staged": {
"*.{js,ts}": ["eslint --fix", "prettier --write"],
"*.php": ["phpcs", "phpstan analyse"],
}
Located in .github/workflows/:
Each workflow is documented in the file with comments.
Create .env file (based on example.env):
# WordPress Test Environment
WP_BASE_URL=http://localhost:8080
WP_ADMIN_USER=admin
WP_ADMIN_PASSWORD=password
# Testing
PLAYWRIGHT_HEADLESS=true
# Reinstall dependencies
rm -rf node_modules vendor
composer install
npm install
composer run analyze:php -- --generate-baseline
npx playwright install --with-deps