README

A CLI tool designed for validating phpBB 3.3.x styles against official standards and best practices. It mirrors the functionality of the official EPV but is specifically tailored for style development, ensuring security, proper file structure, and adherence to extension compatibility requirements.

Features

• Configuration Validation: Validates style.cfg metadata, inheritance rules, and required versions.
• Structural Integrity Check: Validates mandatory files and paths based on the inheritance hierarchy (Standalone vs. Child Style).
• Twig AST Syntax Engine: Thoroughly parses .html templates using strict Twig environments. Includes a powerful pre-processor that natively handles legacy phpBB logic (<!-- IF .draftrow -->, strict operators, $VARIABLES) preventing false positives.
• HTMLHint Integration: Validates the underlying HTML structure of templates after Twig tag stripping to ensure valid DOM syntax, while gracefully ignoring Twig conditional tags.
• Stylelint Integration: Automated CSS code-style checking enforcing the official phpBB .stylelintrc configuration with deprecation-safe rules.
• Baseline Integration: Automatically queries, downloads, and caches the exact prosilver baseline to map, index, and check <!-- EVENT --> hooks seamlessly.
• Remote Extraction: Allows downloading and testing directly from a GitHub repository dynamically.

Requirements

• PHP >= 8.2
• Composer
• Node.js >= 18 & NPM (for Stylelint and HTMLHint dependencies)
• Git (Optional, but recommended)

Installation

This package is intended to be installed as a global development requirement or locally inside a specific workflow.

Global Installation (Recommended)

composer global require vinny/spv

(Make sure your global Composer vendor/bin directory is in your system's $PATH environment variable.)

Local Installation

composer require --dev vinny/spv

Usage

Validating a Local Style

Use the --dir option to pass the absolute or relative path to your style directory containing the style.cfg.

# Using global alias:
spv validate --dir=/path/to/my_style

# Or local binary:
php bin/spv validate --dir=../styles/my_custom_style

Validating from a GitHub Repository

The tool can query GitHub, download, and extract a specific branch internally into a temporary directory to perform a fast remote inspection.

php bin/spv validate --github="username/my-style-repo" --branch="master"

Options Overview

• --dir="/path/to/style": Local path to validate.
• --github="author/repo": Validates a remote style directly from a GitHub repository.
• --branch="master": Used alongside --github to target a specific branch.
• --target-prosilver: Bypasses your style and fetches the official PHPBB prosilver baseline for internal validation.
• --phpbb-version="3.3.15": Overrides checking against the style target style.cfg to explicitly run validation against a defined version of prosilver (Used heavily with --target-prosilver).
• --html-report: Exports the terminal output to an automatically opening HTML local page.

CI/CD Validation for Style Authors (GitHub Actions)

You can automatically protect your style repository so no invalid code is shipped! SPV is specifically engineered to run in GitHub Actions validating every commit or Pull Request.

A complete ready-to-use pipeline is available at resources/github-actions-example.yml. Simply copy the contents of that file into your style's .github/workflows/validate.yml repository folder. SPV will boot up seamlessly, fetch all necessary dependencies natively within Ubuntu-latest runners, and check your style continuously.

Generating Visual Reports

If you prefer a structured browser reading experience (e.g., examining a heavy PR audit with descriptions on fixing them), you can export the output to HTML:

php bin/spv validate --dir=/path/to/my_style --html-report

This command parses your entire style and immediately opens your default browser with a formatted HTML document reporting your validation score and issues.

Testing & Architecture

This tool was designed following Clean Architecture principles, ensuring modular Checkers and abstracted reporting interfaces. We use PHPUnit for robust test coverage and PHPStan (Level 8) to ensure the highest code quality standards.

To run the internal testing suite:

composer test
composer analyse

License

GPL-2.0