Skip to content

BUILD.md

Latest commit

 

History

History
400 lines (270 loc) · 6.81 KB

BUILD.md

File metadata and controls

400 lines (270 loc) · 6.81 KB
Raw

Build & Development Guide

This document explains how to build, develop, and maintain this WordPress plugin.

Table of Contents

Prerequisites

  • PHP 8.2 or higher
  • Node.js 20 or higher
  • Composer 2.x
  • npm or yarn

Installation

  1. Clone the repository:
git clone https://github.com/Starisian-Technologies/sparxstar-gluon.git
cd sparxstar-gluon
  1. Install PHP dependencies:
composer install
  1. Install Node dependencies:
npm install
  1. Install Playwright browsers (for E2E testing):
npx playwright install

Development Workflow

Directory Structure

src/
├── js/          # Source JavaScript files
├── css/         # Source CSS files
├── core/        # Core PHP classes
├── helpers/     # Helper PHP classes
├── includes/    # Autoloader and includes
├── integrations/# Third-party integrations
└── templates/   # Template files

assets/
├── js/          # Minified JavaScript (generated)
└── css/         # Minified CSS (generated)

Development Commands

# Lint all code
npm run lint
composer run lint:php

# Fix auto-fixable issues
npm run format
composer run fix:php

# Run tests
npm test
composer run test:php

# Build assets for production
npm run build

# Build JS only
npm run build:js

# Build CSS only
npm run build:css

# Generate translation files
npm run makepot

# Run Rector refactoring (dry-run)
composer run refactor:php

# Apply Rector refactoring
composer run refactor:php:fix

Building Assets

JavaScript

JavaScript files are minified using Terser:

npm run build:js

This will:

  1. Read all .js files from src/js/
  2. Minify them using Terser
  3. Output to assets/js/ as .min.js files
  4. Generate source maps

CSS

CSS files are minified using clean-css:

npm run build:css

This will:

  1. Read all .css files from src/css/
  2. Minify them using clean-css
  3. Output to assets/css/ as .min.css files

Full Build

Run both JS and CSS builds:

npm run build

Testing

PHP Unit Tests

# Run all PHPUnit tests
composer run test:php

# Run specific test file
./vendor/bin/phpunit tests/phpunit/ExampleTest.php

JavaScript Unit Tests

# Run all Jest tests
npm test

# Run in watch mode
npm test -- --watch

# Generate coverage report
npm test -- --coverage

E2E Tests (Playwright)

# Run all E2E tests
npm run test:e2e

# Run specific browser
npx playwright test --project=chromium

# Run in headed mode (see browser)
npx playwright test --headed

# Debug mode
npx playwright test --debug

Puppeteer Tests

Puppeteer is available for custom browser automation. See tests/e2e/ for examples.

Code Quality

PHP

PHPCS (Code Sniffer)

Checks code against WordPress coding standards:

composer run lint:php

Fix auto-fixable issues:

composer run fix:php

Configuration: phpcs.xml.dist

PHPStan (Static Analysis)

Analyzes code for type errors and bugs:

composer run analyze:php

Configuration: phpstan.neon.dist

Rector (Refactoring)

Modernizes PHP code and applies best practices:

# Dry run (preview changes)
composer run refactor:php

# Apply changes
composer run refactor:php:fix

Configuration: rector.php

JavaScript

ESLint

Lints JavaScript code:

npm run lint:js

Configuration: eslint.config.js

CSS

Stylelint

Lints CSS code:

npm run lint:css

Configuration: .stylelintrc.json

Internationalization (i18n)

Generate POT file for translations:

npm run makepot

This creates/updates languages/plugin-textdomain.pot with all translatable strings.

Release Process

Automated Release (Recommended)

  1. Update CHANGELOG.md with changes for the new version
  2. Commit all changes
  3. Create and push a version tag:
git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3

The GitHub Actions workflow will automatically:

  • Update version numbers in all files
  • Install dependencies
  • Build and minify assets
  • Generate translation files
  • Create distribution zip
  • Generate checksums (MD5, SHA256)
  • Create GitHub release with artifacts

Manual Release

  1. Update version in:

    • sparxstar-plugin-entry.php (plugin header, @version, GLUON_PLUGIN_VERSION)
    • package.json
    • composer.json (if version field exists)

  2. Build assets:

npm run build
  1. Generate POT file:
npm run makepot
  1. Create distribution:
# Install production dependencies only
composer install --no-dev --optimize-autoloader

# Create zip excluding dev files
# Use .distignore to exclude files

CI/CD Workflows

Continuous Integration

Runs on every push and pull request:

  • Lint PHP: PHPCS, PHPStan, Rector checks
  • Lint Frontend: ESLint, Stylelint
  • Test PHP: PHPUnit on PHP 8.2, 8.3, 8.4
  • Test JavaScript: Jest unit tests
  • Build Assets: Verify JS/CSS build process

Code Quality

  • HTML Validation: Validates HTML templates
  • CSS Validation: Checks CSS quality and browser compatibility
  • JS Validation: Analyzes JavaScript complexity

Security

Weekly security scans:

  • Dependency audits (Composer & npm)
  • CodeQL analysis
  • Secret scanning
  • Security best practices checks

Accessibility

  • Automated accessibility testing with axe-core
  • HTML validation
  • WCAG 2.1 compliance checks

Troubleshooting

Build Issues

If builds fail, try:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clear composer cache
composer clear-cache
composer install

Test Issues

# Reinstall Playwright browsers
npx playwright install --force

# Clear Jest cache
npm test -- --clearCache

Linting Issues

# Auto-fix what's possible
npm run format
composer run fix:php

# Check what can't be auto-fixed
npm run lint
composer run lint:php

Additional Resources

Support

For issues and questions: