Pinterest for WooCommerce
A native integration which allows you to market your store on Pinterest, including:
Status - in development
Pinterest for WooCommerce is under development. To find out more about availability and release, refer to WooCommerce.com.
Support
This repository is not suitable for support. Please don't use our issue tracker for support requests.
Requirements
Pinterest for WooCommerce requires PHP 7.4 or newer, WordPress 7.0 or newer, and WooCommerce 11.1 or newer.
See pinterest-for-woocommerce.php for current required versions.
Supported browsers
As per WordPress Core Handbook we currently support:
- Last 1 Android versions.
- Last 1 ChromeAndroid versions.
- Last 2 Chrome versions.
- Last 2 Firefox versions.
- Last 2 Safari versions.
- Last 2 iOS versions.
- Last 2 Edge versions.
- Last 2 Opera versions.
- Browsers with > 1% usage based on can I use browser usage table
:warning: We do not support Internet Explorer.
Development
After cloning the repo. Remember to use the appropriate node version
nvm use to autoselect the node version based on .nvmrc file.
Then, install dependencies:
npm install to install JavaScript dependencies.composer install to gather PHP dependencies.
Now you can build the plugin using one of these commands:
npm start: Build a development version and watch files for changes.npm build: Build a production version.npm run build:zip: Build the production plugin and package it as deploy/pinterest-for-woocommerce.zip. The Production package workflow runs this command on pull requests to trunk and retains the ZIP as an artifact.
Branches
trunk branch is the most up-to-date code.
Releases
Releases are started with the Start Release workflow and shipped by merging the release PR it creates.
Before starting a release, make sure that:
- Everything you want to ship has been merged into
trunk, and each of those pull requests left a change file under changelog/.
- An open milestone titled after the version (e.g.
1.6.0) exists. The workflow refuses to start without one.
To start the release, run the Start Release workflow from the Actions tab, or locally with:
bin/release_start.sh
Run it with no arguments to be prompted for the version and the WP/WC "tested up to" values (press enter to keep the current ones), or pass them directly: bin/release_start.sh X.Y.Z --wp A.B --wc C.D. The script dispatches the workflow, watches it, and prints the release PR URL when it's done.
On a release/X.Y.Z branch, the workflow bumps the version and tested-up-to headers, compiles the change files under changelog/ into changelog.txt and deletes the ones it consumed, copies the release's entries into the readme.txt changelog, then opens a pull request against trunk. It also posts a comment on the PR comparing the changelog entries with the issues in the milestone - review that comment to make sure nothing is missing.
While the release PR is open, trunk is under code freeze: the required Check release freeze check fails on all other pull requests, and flips back automatically once the release PR is merged or closed.
A smoke test workflow runs on the release branch (ci-release-smoke-test.yml), and the release PR goes through the regular PR CI and review like any other PR.
Merging the release PR into trunk triggers the release workflow (ci-release.yml), which builds the zip, creates the GitHub release and tag, and deploys that zip to WordPress.org under the slug set by config.wp_org_slug in package.json. Progress is posted in the #team-somewherewarm-releases Slack channel.
After a successful release, the workflow closes the released milestone and creates one for the next patch version (rename it if the next release will be a minor/major). What's left for you: post-release tasks like documentation and stakeholder notifications.
Public API compatibility
Follow the deprecation policy when replacing public functions or methods.
AI code reviews
CodeRabbit requires its GitHub App
to have access to this repository. A WooCommerce organization owner must grant that
access; committing .coderabbit.yaml does not install the app.
Once enabled, CodeRabbit reviews non-draft PRs targeting the default branch when
opened or marked ready, then reviews new commits. The configuration follows the
default branch if it is renamed. Reviews use the repository's agent guidance and
pause after five reviewed commits to limit repeated reviews.
Use these PR comment commands:
@coderabbitai review: review changes since the last review.@coderabbitai full review: review the whole PR again.@coderabbitai pause: pause automatic reviews.@coderabbitai resume: resume automatic reviews.
Add @coderabbitai ignore to the PR description to skip automatic reviews for that
PR. Human review and CI checks still apply.
Development tools
There are a number of development tools available as npm scripts. Check the package.json file for more.
npm run lint:js: Run eslint to validate JavaScript code style.npm run lint:css: Run stylelint to validate CSS code style.npm run lint:php: Run phpcs to validate PHP code style.
Run npm run lint:composer to validate composer.json and confirm composer.lock is up to date. Pull request CI runs the same check before installing PHP dependencies.
Use composer check:php for the same PHP standards check as CI. It compares
committed PHP changes with the merge base of origin/trunk; fetch that branch
first, or pass another base with composer check:php -- base-ref. New errors
and warnings at severity 5 or higher fail. Existing findings remain excluded by
phpcs-changed. Commit changes before this check; composer lint and
composer lint-staged remain available for work in progress.
Use composer phpcs -- . for the full-tree debt report. Review existing debt
separately from the changed-line gate.
Please use these tools to ensure your code changes are consistent with the rest of the code base. This code follows WooCommerce and WordPress standards.
This repository includes an EditorConfig to automate basic code formatting. Please install the appropriate plugin for your editor.
JavaScript unit tests
Use the Node version in .nvmrc, then install locked dependencies and run Vitest:
nvm use
npm ci
npm run test:js
npm run test:js -- assets/source/setup-guide/app/data/settings/settings.test.js
Both commands collect line and branch coverage in coverage/index.html
and coverage/coverage-summary.json. Coverage includes every production JavaScript
module under assets/source, including modules no test imports; test files, the
assets/source/tests fixtures/examples and generated output are excluded.
Use --no-coverage for a faster focused run. No live Pinterest account is needed.
Product attributes are server-rendered PHP forms; their submitted-value tests use
the existing PHP runner: composer test-unit -- --filter AttributesFormTest.
Prepare its WordPress/WooCommerce environment as described below.
PHPUnit
Prerequisites
Install composer, git, svn, and either wget or curl.
Change to the plugin root directory and type:
composer install
Install Test Dependencies
To run the unit tests you need WordPress, WooCommerce, and the WordPress Unit Test lib (included in the core development repository).
Install them using the install-wp-tests.sh script:
./bin/install-wp-tests.sh <db-name> <db-user> <db-pass> <db-host>
Example:
./bin/install-wp-tests.sh wordpress_tests root root localhost
To test the minimum supported versions, use a fresh test directory and a dedicated database:
WC_VERSION=11.1.0 ./bin/install-wp-tests.sh wordpress_tests root root localhost 7.0.0
WC_VERSION accepts a release tag; latest (the default) and the legacy trunk alias select the latest stable release. The script reuses an existing WooCommerce directory, so use a fresh TMPDIR and WP_CORE_DIR when switching versions.
The reusable unit-test workflow accepts JSON arrays in wp_version and wc_version, both defaulting to ["latest"]. Each matrix job passes its WordPress version as the installer's fifth argument and its WooCommerce version through WC_VERSION, matching the local invocation above. The PHPUnit bootstrap prints the installed PHP, WordPress, and WooCommerce versions.
This script installs the test dependencies into your system's temporary directory and also creates a test database.
You can also specify the path to their directories by setting the following environment variables:
WP_TESTS_DIR: WordPress Unit Test lib directoryWP_CORE_DIR: WordPress core directoryWC_DIR: WooCommerce directory
PHP Tests in wp-env
npm run test:php:wp-env runs the PHPUnit suite inside @wordpress/env's tests-cli container. Compared to ./bin/install-wp-tests.sh, this path needs no host MySQL or svn, and wp-env scopes its containers by working-directory hash so concurrent runs from separate worktrees stay isolated.
wp-env prerequisites
- Docker (Docker Desktop on macOS/Windows is enough).
- A local development checkout of WooCommerce. The plugin's
tests/bootstrap.php requires WooCommerce's tests/legacy/bootstrap.php, which ships only in the WooCommerce source repo — not in the WordPress.org zip the base .wp-env.json downloads.
One-time setup
Create .wp-env.override.json alongside .wp-env.json to swap the base WooCommerce zip for your local checkout (adjust the path to wherever you cloned WooCommerce):
{
"plugins": ["../woocommerce/plugins/woocommerce", "."]
}
plugins in the override file replaces the base list, so include both WooCommerce and . (this plugin). If vendor/ is missing inside your WooCommerce checkout, run composer install in that directory before starting wp-env.
Running tests
npx wp-env start # ~30–90s first run, faster afterwards
npm run test:php:wp-env # run the full PHPUnit suite
npm run test:php:wp-env -- --filter ProductSyncTest --testsuite=unit
npx wp-env stop # tear down when finished
Anything after -- is forwarded to phpunit, so PHPUnit flags such as --filter, --testsuite, and --group work as usual.
Saved-data regression tests
composer test-unit runs all PHP suites. Use composer test-unit -- --filter SavedDataTest for historical upgrades, product-editor attribute saves and exact order conversion values in both HPOS and legacy storage. HTTP responses are local fixtures; no Pinterest account is needed. The 1.3.9 JSON fixture records its source version and stored settings; the test separately seeds the encrypted pre-v5 token. A second case covers the pre-1.0.10 single local feed ID.
Create a separate database and install directory for each dependency combination:
pinterest_test_root="$(mktemp -d /tmp/pinterest-tests.XXXXXX)"
export WP_CORE_DIR="$pinterest_test_root/wordpress"
export WP_TESTS_DIR="$pinterest_test_root/wordpress-tests-lib"
TMPDIR="$pinterest_test_root" WC_VERSION=11.1.0 ./bin/install-wp-tests.sh pinterest_regression_test root "$PINTEREST_TEST_DB_PASSWORD" 127.0.0.1 7.0.0
composer test-unit -- --filter SavedDataTest
Use a dedicated empty test database: the WordPress bootstrap replaces its test prefix tables on each run. Test cases roll back their fixtures, so rerunning the command resets products, orders and options. To change supported WordPress or WooCommerce versions, choose the matching installer arguments and a new directory and database; the installer reuses existing downloads. Missing dependencies are reported by the bootstrap before PHPUnit runs. The existing wp-env runner accepts the same --filter and --testsuite arguments.
Order storage
The PHP suite uses legacy order storage (CPT) by default. Run the same suite with HPOS, with order synchronization disabled, using:
PINTEREST_FOR_WOOCOMMERCE_TEST_ORDER_STORAGE=hpos composer test-unit
PINTEREST_FOR_WOOCOMMERCE_TEST_ORDER_STORAGE=cpt composer test-unit
The bootstrap prints the selected storage, creates the HPOS tables when needed and fails if the value is not cpt or hpos or the requested storage is inactive. CI runs one HPOS job on PHP 8.4 alongside the CPT matrix.
With Xdebug installed, run XDEBUG_MODE=coverage composer test-unit -- --coverage-html coverage/php --path-coverage for line and branch/path coverage. PCOV supports the same HTML report without --path-coverage and reports lines only. Coverage includes unexecuted plugin PHP source and excludes tests and vendor code. Open coverage/php/index.html; a missing driver cannot produce a report.
Running Tests
The PHP suite runs on PHP 7.4, 8.3 and 8.4 in both PHP workflows. To reproduce the
newer-PHP lane locally, put PHP 8.4 on your PATH, install the locked Composer
dependencies, and prepare the isolated WordPress/WooCommerce test environment
above. Run composer test-unit, the same command used in CI. The bootstrap prints
the actual PHP, WordPress and WooCommerce versions, so a configured version can be
checked against the installed version. For wp-env, set "phpVersion": "8.4" in
your local .wp-env.override.json before starting the environment.
Change to the plugin root directory and type:
vendor/bin/phpunit
The tests will execute, and you'll be presented with a summary.
Made with 💜 by WooCommerce.
We're hiring! Come work with us!
PHPStan
After composer install, run composer lint:phpstan. CI runs the same command
on PHP, Composer and PHPStan configuration changes using PHP 8.4. PHPStan checks
owned production PHP at level 8 against the plugin's minimum PHP version.
WordPress and WooCommerce stubs supply core symbols. Vendor code, generated files,
tests and build tools are outside analysis.
The baseline records existing findings by message, rule, file and count. New
findings and unmatched baseline entries fail the check. Run
composer lint:phpstan:baseline:update only for a reviewed baseline change;
never regenerate it to hide new findings. PHPCS and PHPCompatibility remain separate checks.
Browser regression journeys
See tests/browser/README.md for isolated browser setup, merchant and checkout journeys, focused runs and fixture reset.
Dependency advisories
Run npm run audit:npm and npm run audit:composer to check locked dependencies, including development ones, for high or critical advisories. CI does not run them. Instead, a scheduled run every Monday fails when the repository has open high or critical Dependabot alerts.
