Welcome to the WP Statistics development guide! This document will help you set up your development environment, install dependencies, build assets, and run unit tests for the WP Statistics WordPress plugin.

Before you begin, ensure you have the following installed on your system:

• PHP (version 7.4 or higher)
• Composer
• Node.js and NPM
• Git

First, clone the WP Statistics repository and navigate into it:

git clone https://github.com/wp-statistics/wp-statistics.git
cd wp-statistics

The plugin uses Composer for managing PHP dependencies, which are located in the src/Dependencies folder. If you plan to add new packages or update existing ones, you'll need to install Mozart globally. Mozart helps prevent namespace conflicts by wrapping dependencies.

composer global require coenjacobs/mozart

Ensure that Composer's global vendor/bin directory is in your system's PATH to use the mozart command from any location.

If you haven't installed Gulp CLI globally, run:

npm install --global gulp-cli

The plugin's front-end assets are managed with NPM and built using Gulp.

npm install

This command installs all Node.js dependencies specified in package.json.

After installing NPM packages, build the assets:

gulp

This command runs the default Gulp tasks, compiling, concatenating, and minifying JavaScript and CSS files.

Unit tests are essential for maintaining code quality. WP Statistics uses PHPUnit for testing.

Install PHPUnit and the Yoast PHPUnit Polyfills globally via Composer:

composer global require phpunit/phpunit:"^9.6" --dev
composer global require yoast/phpunit-polyfills:"^3.0" --dev

Ensure that the Composer global vendor/bin directory is in your PATH.

Before running the install script, ensure that both svn/subversion and wget are installed on your system. The script for setting up the WordPress test environment is located in bin/install-wp-tests.sh.

The script is used to download WordPress, create a test database, and set up the testing environment. The usage format is as follows:

bin/install-wp-tests.sh <db-name> <db-user> <db-pass> [db-host] [wp-version] [skip-database-creation]

Example:

bash bin/install-wp-tests.sh wordpress_test root '' localhost latest

You can run the unit tests using Composer:

phpunit

You can add the flag --testdox to print the result in TestDox format.

phpunit --testdox

If phpunit isn't recognized, specify the full path, try bellows:

composer test
~/.composer/vendor/bin/phpunit
/root/.config/composer/vendor/bin/phpunit

• Mozart Documentation
• PHPUnit Documentation
• Yoast PHPUnit Polyfills
• Gulp Documentation

WP Statistics v15 introduces an updated build pipeline that separates legacy (non-React) assets from the React application. The setup uses pnpm for efficient dependency management.

• Node.js version: 20.19+ or 22.12+
• Recommended version: 22.12+

pnpm install

(You may use npm or Yarn, but pnpm is recommended.)

pnpm build:legacy    # Build legacy assets
pnpm watch:legacy    # Watch changes and rebuild legacy assets
pnpm dev:legacy      # Development mode for legacy assets (better debugging)

pnpm build:react     # Build the React application
pnpm watch:react     # Watch changes and rebuild React app
pnpm dev:react       # Development mode for React app

pnpm lint:react          # Run linter on React code
pnpm lint:react:fix      # Auto-fix linting errors
pnpm prettier:react       # Format React code
pnpm prettier:react:check # Check formatting without applying changes

pnpm storybook   # Launch Storybook UI for component development