141 lines
5.5 KiB
Markdown
141 lines
5.5 KiB
Markdown
# 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](mailpoet/README.md).
|
|
|
|
## 🔌 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:
|
|
|
|
```shell
|
|
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](https://www.jetbrains.com/help/phpstorm/browser-debugging-extensions.html).
|
|
|
|
To use XDebug inside the **cron**, you need to pass a URL argument `&XDEBUG_TRIGGER=yes`
|
|
[in the cron request](https://github.com/mailpoet/mailpoet/blob/bf7bd6d2d9090ed6ec7b8b575bb7d6b08e663a52/lib/Cron/CronHelper.php#L155-L166).
|
|
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](https://xdebug.org/docs/develop) 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:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
sudo sh dev/mac-nfs-setup.sh
|
|
```
|
|
|
|
Then create a Docker Compose override file with NFS settings and restart containers:
|
|
|
|
```shell
|
|
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](https://objekt.click/2019/11/docker-the-problem-with-macos-catalina/).
|
|
|
|
# 🐶 Husky
|
|
|
|
We use [Husky](https://github.com/typicode/husky) to run automated checks in pre-commit hooks.
|
|
|
|
In case you're using [NVM](https://github.com/nvm-sh/nvm) for Node version management you may
|
|
need to create or update your `~/.huskyrc` file with:
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
```shell
|
|
./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.](https://mailpoet.atlassian.net/wiki/spaces/MAILPOET/pages/629374977/Adding+new+templates+to+the+plugin)
|
|
|
|
## 🚥 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:
|
|
|
|
```yaml
|
|
wordpress:
|
|
build:
|
|
context: .
|
|
dockerfile: dev/php74/Dockerfile # OR dev/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
|