README.md

WP Standard

WP Standard は、KODANSHA tech チームの標準的な WordPress 構成を提供します。

• 目的
• 主な特徴
• これを用意している理由
  • Bedrock 採用の理由
  • VS Code Dev Container を標準的な開発環境として利用する理由
• 具体的な開発方法について
  • 開発フロー
• テーマのサンプル実装
• デフォルトで含まれているプラグイン
• ローカル開発環境
  • 開発環境の起動
  • ACF フィールド定義の同期
  • テーマの開発
  • コードスタイル
  • プラグインのインストール
  • デバッガー
• FAQ
  • なぜ WordPress は cms ディレクトリに入っているのか？
  • Node.js / NPM の環境が必要な場合は？
  • メディアライブラリにアップロードされる画像などのアップロード先は？
  • 実際に本番公開するときのシステム構成はどうなるのか？

目的

WP Standard は、以下の目的のために用意されています。

• 開発パートナーの製作会社様と協調して WP テーマ開発を行うときの標準的な構成として提案できること
• 案件ごとの GitHub リポジトリのベースとして利用できること

主な特徴

WP Standard の主な特徴は以下です。

• テンプレートとして Bedrock を採用している
• ローカル開発は VS Code Dev Container を利用することを前提としている

これを用意している理由

弊社案件では、外部の制作会社様をパートナーとして WordPress 案件を開発するケースが多いです。

そのとき、基本的にはサーバーやインフラの管理は弊社で行っているので、その基盤の標準的な構成に合わせた WordPress の構成を提供することで、開発環境を統一して効率を向上させることができると考えています。

Bedrock 採用の理由

一般的な WordPress 構成とこの WP Standard で最も異なる点はこの Bedrock の採用だと思います。

これは、以下の理由によるものです。

• テーマ開発において Git / GitHub ベースのプレーンテキストでのバージョン管理がしやすいこと
• wp-config.php に記載するような構成情報も環境変数などで管理しやすいこと
• プラグインやパッケージのインストール、バージョン指定を composer で行うことができて、Git のバージョン管理対象にできること
• ステージング環境や CI / CD を構成しやすいこと

WordPress テーマ開発では、テーマ (wp-content/themes/*) のみをバージョン管理することが一般的に行われていますが、実際の運用では、WordPress 本体のバージョンやプラグイン構成、そして設定すべき機密情報など、テーマだけでは完結しないものも含めて運用されるため、それらも含めて管理しやすいようにしたいという動機があります。

また、例えば各種 SDK などの追加ライブラリを導入したいことが多くの案件で発生するのですが、このとき Composer を利用してパッケージとしてインストールできることで、デフォルトの WordPress では悩みがちなベンダーライブラリの導入が容易になります。

ただ、あくまでもこの Bedrock は WordPress 構成のボイラープレートに過ぎませんので、この中に themes ディレクトリは含まれていますし、 Bedrock を使っているから必ず特殊なテーマ開発やプログラミングをしなければならないというものではありません。 Bedrock ではない環境で開発したテーマも、Bedrock の themes ディレクトリに設置すれば基本的には動作します。

ですので、テーマ開発という点では、例えば開発を MAMP / Local などで行うなど普段通りの慣れた環境で開発をしていただき、Git に commit / push するときにテーマのコードのみを Bedrock 構成に揃えるということも可能です。

Bedrock をご存知なかった場合に詳細を知りたい場合には、Bedrock 公式サイトをご覧いただくのが一番とは思いますが、例えば以下のページのような外部サイトでも紹介されているものが多くあるので、まずは軽くそういったサイトで概要を掴んでいただくのも良いかと思います。

https://kinsta.com/jp/blog/bedrock-trellis/

VS Code Dev Container を標準的な開発環境として利用する理由

WP Standard は Visual Studio の Dev Containers という拡張機能を利用して開発環境を構築することを前提としています。

これは、Docker コンテナを利用して自動的に統一された開発環境を僅かな操作で構築できるものです。したがって、開発を行うマシンには Docker がインストールされている必要があります。

Dev Container 開発環境を立ち上げると、例えば以下が揃った状態ですぐに開発をスタートできるように構成することができます。

• WordPress アプリケーション開発環境
• Nginx ウェブサーバー
• MySQL データベース
• Composer パッケージによる WordPress 本体やプラグインのダウンロード
• WordPress 本体のインストールと初期設定
• 必要なプラグインの有効化と初期設定
• その他、言語やパーマリンク設定、必須カテゴリの登録などの必要な初期設定

また、デバッガーの自動構成も行われるので、Dev Container 内でそのまま Xdebug を使ったコードのデバッグもできる状態になります。

こういった多くのメリットがあるため、開発環境の構築については Dev Container を利用することを前提としているのですが、これを利用することも、テーマ開発という点では必須ではありません。

Dev Container を使わない普段通りの慣れた環境で開発をしていただき、Git に commit / push するときにテーマのコードのみを本構成に揃えていただければ、それでも問題ありません。

具体的な開発方法について

Docker や VS Code 環境のご用意があるのであれば、まずは、後述する「ローカル開発環境」の手順をなぞりながら、この WP Standard の動作や内容を把握いただくのが手っ取り早いと思います。

もし、それで立ち上げてみて、それでそのまま開発することに支障がなさそうとご判断いただけるのであば、そのまま開発していただくのが一番スムーズですし、弊社の開発環境とも一致しているのでトラブルも僅かだと思います。

ですので、ここはパートナー様ごとに個別にご相談させていただく点となります。例えば以下のような運用のオプションが考えられます。

• Bedrock + Dev Container 標準構成をそのまま利用していただく
• Bedrock 構成は利用するが、Dev Container は利用しない
• Bedrock 構成も利用せず開発いただき、開発したテーマのみを共有いただく

ただ、いずれの場合も、最終的に開発した成果物を取り込んでリリースする際には、この標準構成に揃えることになります。

また、開発したコードを共有いただくのは、完成品のみを納品という形だけではなく、原則的に GitHub 上で pull request の形で出していただくことをお願いすることが多いです。

開発フロー

前項で「原則的に GitHub 上で pull request の形で出していただく」と記載しました。

このフローで実際に発生する作業の標準的な流れは以下です。

1. 制作会社様がテーマを開発する
2. 制作会社様が開発したテーマを cms/web/app/themes/* にコミットし、GitHub に push する
3. 制作会社様が GitHub 上で pull request を作成する
4. 弊社もしくは制作会社様が確認を行い main ブランチにマージして取り込む

• 誰がマージ操作を行うかは、双方合意の上で決めさせていただきます
• 弊社によるコードレビューを行うかどうかも、双方合意の上で決めさせていただきます
• 基本的に、マージされた内容は自動的に検証環境に反映されるようにデプロイ構成をする予定です

テーマのサンプル実装

WP Standard のテーマである default-theme は、画面も無い空っぽの状態になっており、ご自由に開発を行なっていただくことができます。

ただ、どのような形で開発していくかをイメージしやすいように、ごくごく簡単なサンプルの実装だけは含めています。

ニュース という投稿タイプを追加するというユースケースを例とした実装となります。

もちろん、これはあくまでサンプルですので、実際の開発では、このサンプルをそのまま利用することはありませんし、自由に書いていただいて構いませんが、以下のみ合わせていただければありがたいです。

• 別のテーマとして追加するのではなく、このように default-theme の内容を直接変更・更新する (別のテーマ・ディレクトリにしてしまうと、構成に不整合が発生するため)
• ACF を利用する場合は、このサンプルのように、ACF のフィールドグループを acf-json に保存する (参考: Local JSON)

デフォルトで含まれているプラグイン

以下の2つのプラグインをデフォルトでインストールしています。

• Advanced Custom Fields
  • シンプルに、多くの案件で利用するため含めています
  • Pro 版を利用したい場合は別途ご相談ください
• WP Multibyte Patch
  • 特に日本語ファイル名の画像アップロードなどで、外部ストレージや CDN との連携をするときの不具合を避ける目的で含めています
  • このプラグインによって不都合が発生することがあった場合は別途ご相談ください

その他、必要なプラグインについては任意に追加いただいて構いませんが、追加に関しては後述の「プラグインのインストール」もあわせてご参照ください。

ローカル開発環境

ここでは、実際に Dev Container を使ってローカル開発環境を立ち上げる手順を記載します。

繰り返しになりますが、Dev Container は Docker を利用しますので、事前に Docker 環境をご用意ください。

Note

現在、ローカル開発環境は macOS と Windows の Docker Desktop のみで動作確認をしています。 それ以外の環境でも同じように動作するように構成していますが、もし不具合などあればご報告お願いします。

開発環境の起動

VS Code で clone したフォルダーをワークスペースとして開き、Dev Containers: Reopen in Container を実行してください。

それだけで、.devcontainer ディレクトリに格納された各種設定情報にしたがって、自動的に Docker コンテナ内の開発環境が起動します。

Note

• 初回起動時には、Docker イメージのダウンロードなども行うので、上記実行に多少時間がかかります。エラーがなければ待っていれば終了します
• Dev Container の起動や動作に不具合があると思われるときは、まず Dev Containers: Rebuild Container を実行してコンテナの再ビルドをお試しください
• ごく稀に、再ビルドなどを実行してもどうしても復旧しない場合があります。そのときな、データベースのデータは初期化されますが、Docker ボリュームの削除が有効なことがあります。その際には docker volume ls や Docker Desktop アプリケーションのダッシュボードからボリュームを特定し、個別に削除してください

実行が完了すると、すぐにブラウザで WordPress 管理画面にアクセスできるようになります。

• 管理画面ログイン: http://mylocaldoma.in/wp/wp-login.php
  • ユーザー: admin
  • パスワード: admin

Note

Dev Container でローカル開発する場合の WordPress の URL は上記の通りループバックアドレスに解決される mylocaldoma.in ドメインとポート 80 を利用します。 これは、コンテナ側とホスト側が異なるドメイン・ポートを利用すると REST API や WP Cron の動作に問題が発生するのを回避するためです。 どうしても既存のサービスとポート番号が被っていて開発しにくい、などあれば別途ご相談ください。

ACF フィールド定義の同期

ACF のフィールド定義は Local JSON を利用して、以下に格納された JSON ファイルで同期します。

cms/web/app/themes/default-theme/acf-json

初期設定やフィールド定義に更新があった場合は、管理画面の カスタムフィールド > フィールドグループ > 同期が利用できます からインポートして同期してください。

テーマの開発

基本的な開発は WordPress テーマに対して行います。

対象のテーマは cms/web/app/themes/default-theme として配置されているので、そこで通常のテーマ開発と同じようにコーディングしてください。

コードスタイル

テーマ開発のコードスタイルは PER のコーディングスタイルに準拠しています。

Note

WordPress のコーディング規約ではないので注意。 設定内容は cms/pint.json を参照ください。

コードスタイルについては、Dev Container を利用して開発する場合は、必要パッケージと拡張機能がデフォルトインストールされるので、エディタ上の指示に従えば良いです。自動フォーマットも有効です。

もし、テーマのコーディングに対してもこのスタイルが適用されてしまうと開発に不都合がある、という場合は、cms/pint.json の exclude 配列に以下を追加してください。

    "web/app/themes/default-theme/"

これで、テーマのディレクトリをコードスタイルのチェック対象から除外することができます。

プラグインのインストール

プラグインは WordPress 管理画面からインストールするのではなく、必ず WordPress Packagist から Composer パッケージとしてインストールしてください。

例えば、WP Multibyte Patch のバージョン 2.8.5 をインストールする場合は以下のように composer コマンドでインストールします。

composer require wpackagist-plugin/wp-multibyte-patch:2.8.5

Note

プラグインのバージョンはできる限り厳密にマイナーバージョン、パッチバージョンまで指定するようにしてください。

デバッガー

Dev Container では Xdebug が有効になっています。

.vscode/launch.json を同梱しているため、Dev Container で "Listen for XDebug" でデバッグを実行すればコードレベルのデバッグが可能です。

FAQ

なぜ WordPress は cms ディレクトリに入っているのか？

この WP Standard の構成では、WordPress 関連のファイル群はリポジトリのトップレベルではなく、cms ディレクトリに配置されています。

これは、案件に関連するコードベースをできるだけ monorepo 化してまとめて管理したいという背景があり、そのときに WordPress だけではなく以下のようなアプリケーションやツールも同様に整理してリポジトリに設置したいためです。

• 弊社案件では WordPress をヘッドレス CMS として利用することが多いため、cms とは別に frontend などのディレクトリがあることが多い
• インフラを構築するコードを infra ディレクトリに設置することが多い

cms というディレクトリに分離しておくことで、こういった整理をしやすくしています。

Node.js / NPM の環境が必要な場合は？

例えば、

• Gutenberg エディタのカスタマイズやブロックの追加をしたい場合
• Sass や TypeScript などのコンパイルが必要な場合

こういった場合に、Node.js / NPM が必要になると思います。

WP Standard には Node.js 実行環境が含まれているので、特に追加の設定の必要なく利用することができます。

Note

同梱する Node.js のバージョンは、原則として最新の LTS バージョンになります。

メディアライブラリにアップロードされる画像などのアップロード先は？

基本的には、開発時点では画像のアップロード先を意識していただく必要はありません。

もちろん、実際の本番環境ではサーバーをスケールアウトさせるケースがほとんどなので、サーバーのファイルシステムにアップロードすることはないのですが、そこはこちらで対応します。

ただし、例えば画像配布 CDN と連携したい場合や、画像最適化プラグインなどを使いたい場合には、この構成を開発時点から考慮する必要がある可能性があります。

そういった要件がある場合は別途個別にご相談ください。

実際に本番公開するときのシステム構成はどうなるのか？

弊社ではインフラの設置に主に AWS を利用しています。その際の典型的なシステム構成は以下のようになります。