MailPoet

The MailPoet plugin monorepo.

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.

🔌 Initial setup

1. Run ./do setup to pull everything and install necessary dependencies.
2. Add secrets to .env files in mailpoet and mailpoet-premium directories. Go to the Secret Store and look for "MailPoet: plugin .env"
3. Run ./do start to start the stack.
4. Go to http://localhost:8888 to see the dashboard of the dev environment.

🔍 PHPStorm setup for XDebug

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

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

Xdebug for integration tests

• In Languages & Preferences > PHP > Servers create a new sever named MailPoetTest, set the host to localhost and port to 80 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 to mailpoet/tests/docker/docker-compose.yml -> codeception service to start triggering Xdebug
• Make PHPStorm listen to connections by clicking on the phone icon

💾 NFS volume sharing for Mac

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.

🐶 Husky

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.

🕹 Commands

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.

✉️ Adding new templates to the plugin

Read the article.

🚥 Testing with PHP 7.4 or PHP 8.0

To switch the environment to PHP 7.4/8.0:

1. Configure the wordpress service in docker-compose.override.yml to build from the php74 Dockerfile:

   wordpress:
     build:
       context: .
       dockerfile: docker/php74/Dockerfile # OR docker/php80/Dockerfile

2. Run docker-compose build wordpress.

3. Start the stack with ./do start.

To switch back to PHP 8.1 remove what was added in 1) 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.

✅ TODO

• install woo commerce, members and other useful plugins by default