
ゼロから作る!PHP8.3 + MariaDB + Mailpit 統合Docker開発環境の構築ガイド
本記事では、Web開発の標準とも言えるPHPとデータベースの組み合わせに、便利なツール群(GD、Composer、Mailpit)を盛り込んだ実践的なローカル開発環境の作り方を解説します。
1. 事前準備:Docker Desktopの導入
まずは、ご自身のPCにDockerを動かすためのベースとなるソフトウェアをインストールします。
ダウンロード: Dockerの公式サイト(https://www.docker.com/products/docker-desktop/)にアクセスし、お使いのOS(Windows / Mac)に対応したインストーラーをダウンロードします。
インストール: ダウンロードしたインストーラーを起動し、画面の指示に従ってインストールを完了させます(基本的にはデフォルト設定のままで問題ありません)。
起動確認: インストール後、Docker Desktopアプリを起動します。タスクバーやメニューバーにクジラのアイコンが表示され、エラーが出ていなければ準備完了です。
2. フォルダ構成とファイル配置
任意の作業用フォルダ(例:my-php-env)を作成し、以下のような構造でファイルとフォルダを配置します。(srcフォルダ内のファイルは最初は無くても大丈夫です)
my-php-env/
├── .env (Docker用・ポートやDBパスワード)
├── docker-compose.yml (全体の構成図)
├── php/
│ └── Dockerfile (PHP+GD+メール設定の詳細設計図)
└── src/
├── .env (PHPプログラム用・アプリ設定)
├── composer.json (PDF, Excel等のライブラリ一覧)
└── index.php (動作確認用プログラム)
この構成により、インフラの設定ファイルと、実際のプログラムコード(srcフォルダ内)を綺麗に分離して管理できます。
3. 組み込み機能と構成ファイルの解説
今回の環境を構築する上で中核となる3つの設定ファイルの役割と、そこに組み込まれている機能について解説します。
① .env(環境変数定義ファイル)
システム内で使用する「可変の設定値」をまとめて管理するためのファイルです。頭に.がついているので外部システムから見えません。
.env
APP_PORT=8080
DB_NAME=your_db
DB_USER=your_user
DB_PASS=your_password
DB_ROOT_PASS=db_root_passwordセキュリティと柔軟性: データベースのパスワードやアクセスするポート番号などをメインの設計図に直接書き込まず、このファイルに切り出すことで、安全かつ柔軟に設定を変更できます。githubなどには絶対に上げないようにしてください。DB設定などは適度に書き換えてください。
② docker-compose.yml(全体設計図)
複数のサーバーをどのように連携させるかを定義する「インフラ構成をコードで表現したもの」です。今回は以下の3つのサービス(コンテナ)を稼働させます。
docker-compose.yml
services:
app:
build: ./php
container_name: my-php-container
restart: always
ports:
- "${APP_PORT}:80"
volumes:
- ./src:/var/www/html
environment:
- DB_HOST=db
- DB_DATABASE=${DB_NAME}
- DB_USER=${DB_USER}
- DB_PASSWORD=${DB_PASS}
networks:
- app-network
db:
image: mariadb:11.2
container_name: my-db-container
restart: always
environment:
- MYSQL_ROOT_PASSWORD=${DB_ROOT_PASS}
- MYSQL_DATABASE=${DB_NAME}
- MYSQL_USER=${DB_USER}
- MYSQL_PASSWORD=${DB_PASS}
volumes:
- db-data:/var/lib/mysql
networks:
- app-network
# =========================================
# ★追加:メールテスト用ダミーサーバー (Mailpit)
# =========================================
mailpit:
image: axllent/mailpit
container_name: my-mailpit
restart: always
ports:
- "8025:8025"
- "1025:1025"
networks:
- app-network
networks:
app-network:
driver: bridge
volumes:
db-data:
app (Webサーバー / PHP): phpフォルダ内のDockerfileを読み込んで独自の環境を構築し、PC本体のフォルダをコンテナ内に直結(同期)させることで、ファイルを保存した瞬間にブラウザに反映される仕組みを作ります。
db (データベースサーバー): MariaDB(バージョン11.2)を使用し、データベースの記録を独立した仮想ドライブに逃がすことで、環境を再構築してもデータが消えないように設定されています。
mailpit (メールテストサーバー): プログラムから送信されたメールを安全に傍受・確認するためのダミーサーバーです。実際の顧客アドレスへの誤送信といった情報漏洩リスクを完全に遮断します。
③ php/Dockerfile(Webサーバーの詳細設計図)
PHPが動くWebサーバーの中身をどう組み立てるかを記した製造レシピです。
php/Dockerfile
FROM php:8.3-apache-bookworm
RUN apt-get update && apt-get install -y \
libpng-dev libjpeg62-turbo-dev libfreetype6-dev libwebp-dev libxpm-dev \
libzip-dev libxml2-dev libicu-dev libgmp-dev git unzip mariadb-client \
msmtp msmtp-mta \
&& apt-get clean && rm -rf /var/lib/apt/lists/*
RUN docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp
RUN docker-php-ext-install -j$(nproc) \
gd pdo_mysql mysqli zip intl bcmath gmp soap xml sockets
RUN a2enmod rewrite
# PHPの EXIF拡張モジュール追加
RUN docker-php-ext-install exif
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
# =========================================
# sendmail_pathの中で直接mailpitのポートを指定して強制送信する
# =========================================
RUN echo 'sendmail_path = "/usr/bin/msmtp -t --host=mailpit --port=1025 --from=info@denobase.jp"' > /usr/local/etc/php/conf.d/mail.ini
WORKDIR /var/www/htmlベースイメージ: php:8.3-apache-bookworm(DebianベースのApache + PHP 8.3環境)を採用しています。
GDなどの拡張モジュール: 画像処理(GD)やZIP圧縮、国際化対応に必要なモジュールをインストール・有効化しています。
Composerの導入: マルチステージビルドという手法を使い、公式イメージからPHPのライブラリ管理ツールであるComposer本体だけをコピーして持ち込んでいます。
メール送信の強制ルーティング: PHPから送信されたメールをすべてMailpit(1025番ポート)に転送するルールを強制的に書き込んでいます。
⓸ src/.env(PHPプログラム用環境変数)
Dockerのルートディレクトリにあった .env が「インフラ(ポート番号やDBパスワード)の設定」だったのに対し、src/.env は「PHPアプリケーション自身の挙動を決める設定」です。
APP_ENV=local
DEBUG=trueAPP_ENV=local: 現在の環境が「ローカル開発環境」であることをプログラムに伝えます。本番環境ではここを production に変更し、挙動を切り替えるのが一般的です。
DEBUG=true: デバッグモードを有効にします。エラーが発生した際、画面に詳細なエラー内容を表示させて開発しやすくするための設定です(本番では必ず false にします)。
② src/composer.json(ライブラリ管理ファイル)
PHPのパッケージ管理ツール「Composer」が読み込むファイルで、「このプロジェクトを動かすには、どのライブラリのどのバージョンが必要か」を定義したリストです。
JSON
{
"name": "my-project/standard-php-env",
"require": {
"php": ">=8.3",
"minishlink/web-push": "^7.0",
"dompdf/dompdf": "^2.0",
"phpoffice/phpspreadsheet": "^1.29",
"vlucas/phpdotenv": "^5.5",
"monolog/monolog": "^3.0",
"symfony/messenger": "^7.0",
"respect/validation": "^2.3",
"tecnickcom/tcpdf": "^6.11",
"google/apiclient": "^2.15"
}
}
📌 バージョン表記の意味(記号の解説)
パッケージの横に書かれている記号(>= や ^)には、アップデートの安全性を保つための重要な意味があります。
>=8.3 (以上)
意味:「PHPのバージョンが8.3以上であればOK」です。
^ (キャレット:セマンティックバージョニング)
例:^7.0
意味:「一番左のゼロでない数字を変えない範囲での最新版を許可する」という意味です。
具体的には、7.0.0 から 7.9.9 までのアップデート(機能追加やバグ修正)は自動で取り入れますが、互換性が壊れる可能性のあるメジャーアップデート(8.0.0など)は勝手に入れないようにブロックします。これにより、「安全に最新のバグ修正を受け取りつつ、システムが突然動かなくなるのを防ぐ」ことができます。
📌 構成例
minishlink/web-push: ブラウザへのプッシュ通知機能。
dompdf/dompdf: HTMLベースの簡易的なPDF生成。
phpoffice/phpspreadsheet: Excelファイル(.xlsx)の読み込み・書き込み。
vlucas/phpdotenv: src/.env の中身をPHPで読み込めるようにする機能。
monolog/monolog: アクセス記録やエラー記録をファイルに書き出す高度なログ機能。
tecnickcom/tcpdf:dompdfより日本語強く本格的で細密なPDF帳票やQRをプログラムから直接描画して出力できるようになる。
google/apiclient Googleの各種API(パスキーログイン、googleログインや各種Ai)と連携するための公式ライブラリ。
4. 基本的な動かし方
ファイル群を正しく配置したら、以下の手順で開発環境を立ち上げます。
ステップ1:システムのビルドと起動
ターミナル(PowerShell等)を開き、docker-compose.ymlがある一番外側のフォルダへ移動した後、以下のコマンドを実行します。
PowerShell
docker compose up -d --build
--build: ソフトウェアをインストールして新しいイメージを作成するための指示です(設定書き換え時は必須)。
-d: バックグラウンド実行のオプションです。ターミナルがログで埋まるのを防ぎます。
ステップ2:Composerライブラリのインストール
起動後、以下のコマンドを実行して、composer.jsonに定義されているライブラリ群をインストールします。
PowerShell
docker compose exec app composer install
ステップ3:ブラウザでの動作確認
システムが稼働したら、ブラウザで以下のURLにアクセスして動作を確認します。
Webアプリ画面: http://localhost:8080(プログラムの実行結果が表示されれば連携成功です)
Mailpit画面: http://localhost:8025(テストメールの送信結果がここに集約されます)
ステップ4:システムの停止
開発作業が終わり、PCのリソースを解放したい場合は以下のコマンドでシステムを停止します。
PowerShell
docker compose down
このコマンドでコンテナ群は解体されますが、データベース内の記録や編集したソースコードはPC本体に保存されているため、次回 up -d を実行すればすぐに続きから作業を再開できます。