Skip to content

SETUP.md

Latest commit

 

History

History
228 lines (163 loc) · 8.88 KB

SETUP.md

File metadata and controls

228 lines (163 loc) · 8.88 KB
Raw

Setup Guide

This document describes how to setup your development environment, so that it is ready to run, develop and test the WordPress Plugin.

Suggestions are provided for the LAMP/LEMP stack and Git client are for those who prefer the UI over a command line and/or are less familiar with WordPress, PHP, MySQL and Git - but you're free to use your preferred software.

Setup

LAMP/LEMP stack

Any Apache/nginx, PHP 7.x+ and MySQL 5.8+ stack running WordPress. For example, but not limited to:

  • Local by Flywheel (recommended)
  • Docker
  • MAMP
  • WAMP
  • VVV

Composer

If Composer is not installed on your local environment, enter the following commands at the command line to install it:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === '906a84df04cea2aa72f40b5f787e49f22d4c2f19492ac310e8cba5b96ac8b64115ac402c8cd292b8a03482574915d1a8') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

Confirm that installation was successful by entering the composer command at the command line

Clone Repository

Using your preferred Git client or command line, clone this repository into the wp-content/plugins/ folder of your local WordPress installation.

If you prefer to clone the repository elsewhere, and them symlink it to your local WordPress installation, that will work as well.

If you're new to this, use GitHub Desktop or Tower

Create Test Database

Create a blank test database in MySQL, with a MySQL user who can read and write to it.

Configure Testing Environment

Copy the .env.example file to .env.testing in the root of this repository, changing folder and database credentials as necessary:

TEST_SITE_DB_DSN=mysql:host=localhost;dbname=test  // Your local MySQL host and database name
TEST_SITE_DB_HOST=localhost // Your local MySQL host
TEST_SITE_DB_NAME=test // If you followed the instructions above, your test database should be called test :)
TEST_SITE_DB_USER=root // Your local MySQL user
TEST_SITE_DB_PASSWORD=root // Your local MySQL password
TEST_SITE_TABLE_PREFIX=wp_ // Don't change; this refers to the WordPress database table prefix used  for testing that's stored in _tests/data/dump.sql
TEST_SITE_ADMIN_USERNAME=admin // Don't change; this refers to the WordPress admin login used for testing that's stored in _tests/data/dump.sql
TEST_SITE_ADMIN_PASSWORD=password // Don't change; this refers to the WordPress admin login used for testing that's stored in _tests/data/dump.sql
TEST_SITE_WP_ADMIN_PATH=/wp-admin // Don't change
WP_ROOT_FOLDER="/Users/tim/Local Sites/wp-zinc-plugins/app/public" // Location of your WordPress installation
TEST_DB_NAME=test // If you followed the instructions above, your test database should be called test :)
TEST_DB_HOST=localhost // Your local MySQL host
TEST_DB_USER=root // Your local MySQL user
TEST_DB_PASSWORD=root // Your local MySQL password
TEST_TABLE_PREFIX=wp_ // Don't change; this refers to the WordPress database table prefix used  for testing that's stored in _tests/data/dump.sql
TEST_SITE_WP_URL=http://wpzinc-plugins.local // Your local WordPress URL
TEST_SITE_WP_DOMAIN=wpzinc-plugins.local // Your local WordPress domain
TEST_SITE_ADMIN_EMAIL=wordpress@wpzinc-plugins.local // Don't change

Codeception

Create a codeception.yml file in the root of the repository, with the following contents:

params:
    - .env.testing

This tells Codeception to read the above .env.testing file when testing on the local development enviornment.

PHPStan

Copy the phpstan.neon.example file to phpstan.neon in the root of this repository, changing the scanDirectories to point to your local WordPress installation:

# PHPStan configuration for local static analysis.

# Include PHPStan for WordPress configuration.
includes:
    - vendor/szepeviktor/phpstan-wordpress/extension.neon

# Parameters
parameters:
    # Paths to scan
    # This should comprise of the base Plugin PHP file, plus directories that contain Plugin PHP files
    paths:
        - wp-to-buffer.php
        - includes/
        - lib/

    # Files that include Plugin-specific PHP constants
    bootstrapFiles:
        - wp-to-buffer.php

    # Location of WordPress Plugins for PHPStan to scan, building symbols.
    scanDirectories:
        - /Users/tim/Local Sites/wp-zinc-plugins/app/public/wp-content/plugins

    # Should not need to edit anything below here
    # Rule Level: https://phpstan.org/user-guide/rule-levels
    level: 5

    # Ignore the following errors, as PHPStan and PHPStan for WordPress haven't registered symbols for them yet,
    # so they're false positives.
    ignoreErrors:
        - '#Access to an undefined property WP_Theme::#'
        - '#Constant WP_MEMORY_LIMIT not found.#'
        - '#Function apply_filters invoked with#' # apply_filters() accepted a variable number of parameters, which PHPStan fails to detect

Install Packages

In the Plugin's directory, at the command line, run composer install.

This will install two types of packages:

  • Packages used by the Plugin (i.e. shared libraries used across multiple Plugins)
  • Packages used in the process of development (i.e. testing, coding standards): -- wp-browser -- Codeception -- PHPStan -- PHPUnit -- PHP_CodeSniffer

How to use these is covered later on, and in the Testing Guide

Configure wp-config.php

In the root of your WordPress installation, find the wp-config.php file.

Change the following line from (your database name itself may vary):

define( 'DB_NAME', 'local' );

to:

if( isset( $_SERVER['HTTP_X_TEST_REQUEST'] ) && $_SERVER['HTTP_X_TEST_REQUEST'] ) {
    // WPBrowser request, performed when Codeception tests are run. Connect to test DB.
    define( 'DB_NAME', 'test' );
} elseif( isset( $_SERVER['HTTP_USER_AGENT'] ) && strpos( $_SERVER['HTTP_USER_AGENT'], 'HeadlessChrome' ) !== false ) {
    // WPWebDriver request, performed when Codeception tests are run. Connect to test DB.
    define( 'DB_NAME', 'test' );
} else {
    // Connect to local DB.
    define( 'DB_NAME', 'local' );
}

When Codeception tests are run, they will include either:

  • The HTTP_X_TEST_REQUEST header for tests run using WPBrowser.
  • The HeadlessChrome HTTP User Agent for tests run using WPWebDriver.

Our change above tells WordPress to use the test database for our test requests, whilst using the local/default database for any other requests.

Install ChromeDriver

ChromeDriver is a headless (i.e. non-GUI) browser that our test suite uses to run Acceptance tests, interacting with the Plugin just as a user would - including full JavaScript execution, user inputs etc.

Download ChromeDriver for your Google Chrome version and OS from https://sites.google.com/chromium.org/driver/downloads?authuser=0

For Mac users, copy the unzipped executable to /usr/local/bin.

Running the Test Suite

First, run the ChromeDriver in a separate Terminal window:

chromedriver --url-base=/wd/hub

ChromeDriver Screenshot

In a second Terminal window, in the Plugin's directory, build and run the tests to make sure there are no errors and that you have correctly setup your environment:

vendor/bin/codecept build
vendor/bin/codecept run acceptance
vendor/bin/codecept run wpunit

Codeception Test Results

Don't worry if you don't understand these commands; if your output looks similar to the above screenshot, and no test is prefixed with E, your environment is setup successfully.

Running CodeSniffer

In the Plugin's directory, run the following command to run PHP_CodeSniffer, which will check the code meets WordPress' Coding Standards:

vendor/bin/phpcs ./ -v -s

Coding Standards Test Results

Again, don't worry if you don't understand these commands; if your output looks similar to the above screenshot, with no errors, your environment is setup successfully.

Running PHPStan

In the Plugin's directory, run the following command to run PHPStan, which will perform static analysis on the code, checking it meets required standards, that PHP DocBlocks are valid, WordPress action/filter DocBlocks are valid etc:

vendor/bin/phpstan --memory-limit=1G

PHPStan Test Results

Again, don't worry if you don't understand these commands; if your output looks similar to the above screenshot, with no errors, your environment is setup successfully.

Next Steps

With your development environment setup, you'll probably want to start development, which is covered in the Development Guide