The MailPoet plugin monorepo.
If you have any questions or need help or support, please see the Support document.
To use our Docker-based development environment (recommended), continue with the steps below. If you'd like to use the plugin code directly, see details in the plugin's readme.
- Run
./do setup
to pull everything and install necessary dependencies. - Add secrets to
.env
files inmailpoet
andmailpoet-premium
directories. Go to the Secret Store and look for "MailPoet: plugin .env" - Run
./do start
to start the stack. - Go to https://localhost:8888 to see the dashboard of the dev environment.
Even though it's possible to run everything using Docker, in the development workflow, it may be faster and more convenient to run some tasks outside the container. Therefore, the following tools are recommended:
- PHP as per
composer.json
requirements. - Node.js, as specified by
.nvmrc
. For automatic management use nvm, FNM, or Volta. - pnpm, as specified in
package.json
. For automatic setup enable Corepack usingcorepack enable
.
In Languages & Preferences > PHP > Servers
set path mappings:
wordpress -> /var/www/html
mailpoet -> /var/www/html/wp-content/plugins/mailpoet
mailpoet-premium -> /var/www/html/wp-content/plugins/mailpoet-premium
For PHP 8 and XDebug 3 we support browser debugging extension. You can choose extension by your browser in JetBrains documentation.
To use XDebug inside the cron, you need to pass a URL argument &XDEBUG_TRIGGER=yes
in the cron request.
Alternatively, you can add XDEBUG_TRIGGER: yes
to the wordpress
service in docker-compose.yml
and restart it (which will run XDebug also for all other requests).
Xdebug develop mode is disabled by default because it causes performance issues due to conflicts with the DI container.
It can be enabled when needed using the XDEBUG_MODE
environment variable. For example, it is possible to enable it by adding the following to docker-compose.override.yml
:
environment:
XDEBUG_MODE: debug, develop
- In Languages & Preferences > PHP > Servers create a new sever named
MailPoetTest
, set the host tolocalhost
and port to80
and set following path mappings:
wordpress -> /wp-core
mailpoet -> /wp-core/wp-content/plugins/mailpoet
mailpoet-premium -> /wp-core/wp-content/plugins/mailpoet-premium
mailpoet/vendor/bin/codecept -> /project/vendor/bin/codecept
mailpoet/vendor/bin/wp -> /usr/local/bin/wp
- Add
XDEBUG_TRIGGER: 1
environment totests_env/docker/docker-compose.yml
-> codeception service to start triggering Xdebug - Make PHPStorm listen to connections by clicking on the phone icon
NFS volumes can bring more stability and performance on Docker for Mac. To setup NFS volume sharing run:
sudo sh dev/mac-nfs-setup.sh
Then create a Docker Compose override file with NFS settings and restart containers:
cp docker-compose.override.macos-sample.yml docker-compose.override.yml
docker-compose down -v --remove-orphans
docker-compose up -d
NOTE: If you are on MacOS Catalina or newer, make sure to put the repository
outside your Documents
folder, otherwise you may run into file permission issues.
We use Husky to run automated checks in pre-commit hooks.
In case you're using NVM for Node version management you may
need to create or update your ~/.huskyrc
file with:
# This loads nvm.sh and sets the correct PATH before running the hooks:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
Without it, you may experience errors in some Git clients.
The ./do
script define aliases for most of the commands you will need while working on plugins:
./do setup Setup the environment.
./do start Start the docker containers.
./do stop Stop the docker containers.
./do ssh [--test] Run an interactive bash shell inside the plugin directory.
./do run [--test] <command> Run a custom bash command in the wordpress container.
./do acceptance [--premium] Run acceptance tests.
./do build [--premium] Builds a .zip for the plugin.
./do templates Generates templates classes and assets.
./do [--test] [--premium] <command> Run './do <command>' inside the plugin directory.
Options:
--test Run the command using the 'test_wordpress' service.
--premium Run the command inside the premium plugin.
You can access this help in your command line running ./do
without parameters.
To switch the environment to a different PHP version:
-
Check https://github.com/mailpoet/mailpoet/tree/trunk/dev for a list of available PHP versions. Each directory starting with
php
corresponds to a available version. -
Configure the
wordpress
service indocker-compose.override.yml
to build from the desired PHP version Dockerfile (replace {PHP_VERSION} with the name of the directory that corresponds to the version that you want to use):wordpress: build: context: . dockerfile: dev/{PHP_VERSION}/Dockerfile
-
Run
docker-compose build wordpress
. -
Start the stack with
./do start
.
To switch back to the default PHP version remove what was added in 2) and, run docker-compose build wordpress
for application container and docker-compose build test_wordpress
for tests container,
and start the stack using ./do start
.
To disable the Tracy panel, add the following to docker-compose.override.yml
:
services:
wordpress:
environment:
MAILPOET_DISABLE_TRACY_PANEL: 1
It's recommended to run tests in Docker. Free plugin tests can be run using --test flag (./do --test
). However, to run a premium test, you need to ssh into test container (./do ssh --test
) and run tests there.
./do --test test:integration --skip-deps --file=tests/integration/WP/EmojiTest.php
./do --test test:acceptance --skip-deps --file=tests/acceptance/Misc/MailpoetMenuCest.php
./do ssh --test # to enter the container
cd ../mailpoet-premium # switch to premium plugin directory
./do test:unit --file=tests/unit/Config/EnvTest.php
cd ./mailpoet-premium # switch to premium plugin directory on your local machine
./do test:acceptance --skip-deps --file tests/acceptance/PremiumCheckCest.php
- Install WooCommerce
- Install Members
- Install other useful plugins by default