メインコンテンツへスキップ
見出し画像

ゼロから作る!PHP8.3 + MariaDB + Mailpit 統合Docker開発環境の構築ガイド

    本記事では、Web開発の標準とも言えるPHPとデータベースの組み合わせに、便利なツール群(GD、Composer、Mailpit)を盛り込んだ実践的なローカル開発環境の作り方を解説します。

    1. 事前準備:Docker Desktopの導入

    まずは、ご自身のPCにDockerを動かすためのベースとなるソフトウェアをインストールします。

    1. ダウンロード: Dockerの公式サイト(https://www.docker.com/products/docker-desktop/)にアクセスし、お使いのOS(Windows / Mac)に対応したインストーラーをダウンロードします。

    2. インストール: ダウンロードしたインストーラーを起動し、画面の指示に従ってインストールを完了させます(基本的にはデフォルト設定のままで問題ありません)。

    3. 起動確認: インストール後、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=true
    • APP_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 を実行すればすぐに続きから作業を再開できます。


     
     
    秋葉原に住んでいるソフト開発や中古PC販売などやっている個人事業主です。 バイブコーディングでVSコードのような動きをするAIコードマージツールやVroidのキャラクターVRMのテクスチャを手持ちのペイントソフトで書き換えられるツールなどを出品しています。

    あなたへのおすすめ