WordPress オリジナルテーマ作成において、チーム開発がしやすいローカル環境を作りたい

## はじめに

最近は Astro などのフレームワークを使う機会も増え、 WP REST API を使って、 CSR または SG で WordPress サイト制作を検討することも多いと思います。

ただ、SG の構成をとるためには、投稿をフックにデプロイできるサーバ環境が前提になりますし、問い合わせページがあるなど、やはり SSR を選択せざるを得ないケースは多いです。

今回はそのような SSR での WordPress オリジナルテーマ作成において、チーム開発がしやすいローカル環境を作ることについて取り上げます。

## Local で感じていた課題

これまで WordPress ローカル環境はセットアップが簡単にできる [Local](https://localwp.com/) で作ることが多かったのですが、以下のような課題を感じていました。

1. 複数人で開発する場合に、全員のローカル環境を同期しづらい。
    - テスト環境などにセットアップした環境を、 [All-in-One WP Migration プラグイン](https://ja.wordpress.org/plugins/all-in-one-wp-migration/) などを使ってローカル環境にインポートすることが多いかなと思います。
    - 変更があった場合には、毎回インポートとエクスポートを行う必要があるし、明確に運用を定めておかないと違う環境で開発が進んでしまうことになります。
2. デプロイ先の環境と PHP や データベースのバージョンがマイナーバージョンまで含めて一致させれないことがある。
    - Local は選択できる PHP や MySQL のバージョン は決まっているため、デプロイ先の環境とバージョンがずれてしまって動作しなくなるなどの不具合が発生するリスクがあります。
    - また Local のデータベースは MySQL のみで MariaDB はサポートされていません。MySQL と MariaDB の互換性についてここでは触れませんが、いずれにしても全く同じ環境が再現できないことは多いと思います。

Docker を使って GitHub で設定ファイルを共有すれば、上記の課題を解決できそうということは、なんとなく知ってはいたのですが、私は Docker を使ったことがなくハードルを感じていました。

しかし、WordPress の開発チームが、開発環境を整備するための [@wordpress/env（wp-env）](https://github.com/WordPress/gutenberg/tree/HEAD/packages/env#readme) というパッケージをリリースしていることを知り、試してみたところ、とても導入が簡単だったのでご紹介したいと思います。

ただ、使ってみて課題も感じており、その点は解決に至っていませんので最後にまとめています。この記事を読んで情報提供いただける方がいたら嬉しいです！

ちなみに wp-env は新しい技術というわけではありません。 [2020年3月頃にはリリース](https://make.wordpress.org/core/2020/03/03/wp-env-simple-local-environments-for-wordpress/)されていました。

## wp-env を使用したローカル環境構築

[GitHub の README.md](https://github.com/WordPress/gutenberg/tree/HEAD/packages/env#readme) や [ハンドブックのリファレンス](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/packages/packages-env/)とおりになるのですが、順に解説していきます。なお、私は MacBook を使っており、以降は Mac での説明になります。


### 前提ソフトウェアのインストール

#### [Docker Desktop](https://www.docker.com/products/docker-desktop/)

[macOS の場合](https://docs.docker.com/desktop/install/mac-install/#system-requirements)、メジャーバージョンは最新か、旧バージョンは 2 つ前までにしておかないと動作しません。2023年12月1日現在ですと最新のメジャーバージョンは 14 ですので、 12 以上であれば大丈夫だと思います。（私は Docker Desktop は v4.25.0 で macOS は 14.1 です。それ以外のバージョンでの動作確認はしていません。）

#### [Node.js](https://nodejs.org/en) 

npm を使えるようにしておきます。推奨版（LTS）にしておくのがよいでしょう。

### wp-env のインストール

ここからは実際に wp-env を使った環境を作り、WordPress を起動してみましょう。

1. プロジェクトのディレクトリを作成して `@wordpress/env` をインストールします。
    ``` console
    $ cd desktop
    $ mkdir sample-wp-env
    $ cd sample-wp-env
    $ npm init
    $ npm i @wordpress/env -D
    ```

2. `package.json` の scripts に wp-env コマンドを追加します。
    ```json
    "scripts": {
      "wp-env": "wp-env"
    }
    ```

### WordPress の起動

1. まずはインストールした Docker Desktop を立ち上げておきます。
Docker の設定をする必要はありませんので、アプリを起動するだけでよいです。

2. 次のコマンドを入力します。
    ``` console
    $ npm run wp-env start
    ```
    start コマンドは WordPress をインストールして初期化しますので、少し時間がかかります。

3. ターミナルで 「✔ Done!」 と表示されたら、ウェブブラウザで `localhost:8888` にアクセスすると WordPress の初期テーマでサイトが表示されます。

4. 管理画面は `http://localhost:8888/wp-login.php` にアクセスします。
デフォルトの Username / Password は以下になっています。
    ```
    Username: admin
    Password: password
    ```

### 環境ファイルの設定

ここまでで WordPress 環境は動作しましたが、最初に記載した課題は何も解決していません。

wp-env では `.wp-env.json` というファイルを作ることで、WordPress やプラグインのバージョンを指定してインストールしたり、`wp-config.php` の定数を設定するなどのカスタマイズができます。この仕様を活用して「複数人で開発する場合の環境の同期」を解決していきます。

1. プロジェクトのルートディレクトリ（ `package.json` と同階層）に `.wp-env.json` という名前のファイルを作成して、以下のように記述します。

    ```json
    {
      "core": "https://ja.wordpress.org/wordpress-6.4.1-ja.zip",
      "plugins": [
        "https://downloads.wordpress.org/plugin/wp-multibyte-patch.2.9.zip",
        "https://downloads.wordpress.org/plugin/query-monitor.3.15.0.zip"
      ],
      "config": {
        "WP_DEBUG": true
      }
    }
    ```
    <dl>
      <dt>core</dt>
      <dd>WordPress のバージョンを指定できます。省略したり、.wp-env.json がない場合は最新版になります。</dd>
      <dt>plugins</dt>
      <dd>インストール & 有効化するプラグインを配列で指定できます。https://ja.wordpress.org/plugins/ からプラグインを調べて ZIP ファイルへのパスを指定します。GitHub へのパスでもできるようです。</dd>
      <dt>config</dt>
      <dd>wp-config.php の定数の上書きができます。</dd>
    </dl>
 
2. 次のコマンドを入力します。
    ``` console
    $ npm run wp-env start —update
    ```
    今回のように WordPress の構成を変更した場合には `--update` オプションをつけて start すると、更新して適用されます。

3. 管理画面にアクセスしてみると、日本語の管理画面が表示されています。サイドバーから「プラグイン」をみてみると、Query Monitor と WP Multibyte Patch が有効化されていることが確認できます。

`.wp-env.json` を GitHub などで共有すれば、チームメンバーで同じ環境を構築できますね！

## WordPress ファイルの場所

ところで、 WordPress に必要な `wp-config.php` や `wp-content` ディレクトリがないことに気づかれたでしょうか？

これらのファイルはホームディレクトリの `.wp-env` という不可視ディレクトリ内に生成されています。

次のコマンドで起動中のコンテナの一覧が表示されます。

```console
$ docker ps
```

最初の行に書かれている IMAGE と同じ文字列のディレクトリが `.wp-env` 直下に作られています。例えば私の場合、IMAGE は `289cd42a5ea366ce7be8fc51acd38fea-tests-cli` となっていて、 `.wp-env` 直下には `289cd42a5ea366ce7be8fc51acd38fea` というディレクトリが存在しています。これが WordPress の実体ということになります。

## オリジナルテーマファイルの設置と mappings の設定

`.wp-env.json` には `mappings`という設定があり、オリジナルのテーマやプラグインを、先程の隠しファイルで生成された WordPress と関連付けることができます。例えば以下のように行います。

1. プロジェクトのディレクトリに `dist` ディレクトリを作成して、その中に WordPress を構成する最小ファイルである `index.php` と `style.css` を設置します。
    ```html
    // index.php
    <p>Hello wp-env!</p>
    ```

2. `.wp-env.json` に以下を追加して、`npm run wp-env start —update` コマンドを実行します。
    ```json
    "mappings": {
      "wp-content/themes/sample-theme/": "./dist/"
    }
    ```

3. 管理画面のサイドバー「外観」の「テーマ」を選ぶと、「sample-theme」が追加されています。有効化してサイトを表示してみましょう。「Hello wp-env!」が表示されていると思います。

このようにしてマッピングを行い、オリジナルテーマは GitHub 等で管理します。

あとは、 `src` ディレクトリ等を設置して開発し、`dist` に出力するようにすればよいかと思います。

`.wp-env.json` の設定について、詳細は[リファレンス](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/packages/packages-env/#wp-env-json)をご確認ください。

## デプロイ先の環境とローカル環境を合わせる

**最初にお伝えしていた、解決できていない課題とは、「デプロイ先の環境とローカル環境を合わせる」ことです。** Docker を使う大きなモチベーションのひとつはここですので、実現できないと開発環境としては不十分だと思っています。

PHP バージョンについては、`.wp-env.json` に `phpVersion` というフィールドが用意されているため合わせることができます。以下を追記して `npm run wp-env start —update` を実行してみましょう。

```json
"phpVersion": "7.4"
```

管理画面のサイドバーから、ツール＞サイトヘルス＞情報＞サーバー＞PHP バージョンを確認すると、`7.4.33` になっており、指定したバージョンになっていることが確認できます。

あとは、 Web サーバー（Apache or nginx）、データベース（MySQL or MariaDB、またそのバージョン）は合わせておきたいです。

Docker Desktop の確認方法についての知見が足りていないかもしれませんが、 Containers や Images をみると、 Web サーバーは nginx、データベースは MariaDB がデフォルトなようです。

![スクリーンショット 2023-12-01 12.33.34.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/298406/12105dc5-022c-2c6c-4611-d95f8f2b4462.png)

![スクリーンショット 2023-12-01 12.33.18.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/298406/1f22c78c-aee8-85c5-0dea-12e4d952700c.png)

不可視ファイル内の WordPress ファイルをみても、`.htaccess` が存在しないので、このことからも Web サーバーは nginx だとわかります。

wp-env リファレンスをみると、「 [composer、phpunit、wp-cli ツールの使用](https://ja.wordpress.org/team/handbook/block-editor/reference-guides/packages/packages-env/#composer%e3%80%81phpunit%e3%80%81wp-cli-%e3%83%84%e3%83%bc%e3%83%ab%e3%81%ae%e4%bd%bf%e7%94%a8)」あたりの設定なのかなという気がしますが、経験値がないこともあり、まだ試せていません。

このあたりの設定次第では、結局 wp-env は使わなくてもいい（Dockerは使うと思います）という判断になるかもしれないです。

進展があれば、また追記したいと思います。