WordPress VIP Integration Starter Kit

Welcome to WordPress VIP! This repository is a starting point for developing an integration and submitting for the Integrations Center.

It contains an example of fully configured VIP local and cloud development environments along with unit tests, end-to-end tests, static analysis and linting.

Utilizing these tools will allow you to submit the new versions of your integrations and us to deploy the code with confidence.

The kit implements the WordPress VIP integration requirements and doubles as a reference implementation: runtime config via a single VIP-provided constant, config fixtures, Tracks telemetry, composer test, and the handoff manifest VIP registers the integration from. See /docs/vip-integration.md for the operational details. Check conformance with the vip-integration CLI (npx @automattic/vip-integration validate).

📝 Already have a plugin? Don't start again. /docs/existing-plugin.md lists only the pieces an established plugin needs to add, and what it can safely ignore.

Technology

We used tools that we consider the best technology in the industry with convenience in mind. These are the tools we use on a day-to-day basis to ensure code quality on WordPress VIP platform.

Unit Tests

We utilize PHPUnit 9 for unit tests. For an example of a test suite please refer to /tests/phpunit folder.

End-to-end tests

For end-to-end tests we use Playwright. Examples can be found in /tests/e2e.

Static analysis

PHPStan runs at level 10 with the WordPress, strict-rules, PHPUnit and dead-code extensions. Run it with composer phpstan. For it to work properly you will need to annotate your PHP code; see /inc for examples. Overrides for stub signatures that are missing or wrong live in /tests/phpstan.

Linting and coding standards.

Linting and coding standards are powered by PHP_CodeSniffer (commonly known as PHPCS) along with WordPress VIP and WordPress core rulesets.

For more information please refer to linting doc.

GitHub Actions

CI runs on every push and pull request to main:

Repository structure

⚠️ You may notice the repository contains several folders. These should not be removed as they constitute a complete WordPress VIP application. A brief description is available in /docs/directories.md

For more information on how our codebase is structured, see https://docs.wpvip.com/technical-references/vip-codebase/.

Local installation and development

To fully leverage the starter kit you will need to have the following tools installed: Composer, Node.js, NPM (installed with Node.js), Docker, VIP-CLI.

📝 While we usually recommend Docker Desktop we understand that it may be not possible to utilize it for your organization. The Starter Kit is compatible with alternative container runtimes like Colima and Rancher Desktop. For details please refer to our documentation.

Assuming you have prerequisites installed, follow these steps to set up the local environment.

1. Clone the repository and make it your own.
2. Change the working directory to your repository.
3. Install Composer dependencies

composer install

4. Install Node.js dependencies

npm i

5. Rename the example prefix set (slug, namespace, constants) to your integration's names:

composer setup

Setup finishes by listing the example values it cannot derive from your names — the manifest summary, support contact and documentation URLs, the plugin header description, and this README. Work through that list before submitting: the conformance checker passes with those values still in place, so nothing downstream will flag them. See Making it your own for the full table.

6. Create and start a WPVIP local development instance:

vip dev-env create
vip dev-env start

7. Write code, write tests. Or the other way around! composer test runs both suites (the e2e half needs the dev-env from the previous step running — see /docs/vip-integration.md).

📝 For convenience, this repository contains a special configuration file vip-dev-env.yml, feel free to tweak it to your needs. For more in-depth guide to VIP Local Development Environments please refer to our documentation site.

Cloud-based development

We leverage GitHub Codespaces. There are no set up steps. On the first start of the codespace it will take a few minutes to build. Once the build runs you'll have a working environment. You can use either Web-based editor or local VSCode.

Submitting your plugin to WordPress VIP Integrations Center

Once you're confident your code is ready for the prime time, please contact your Technology Partner Manager for the next steps.