PHPで環境変数を扱う方法や設定方法について

PHPの環境変数とは

PHPの環境変数とは、アプリケーションの設定値をソースコードの外部で管理するための仕組みです。

データベースの接続先やユーザー名、パスワード、APIキー、アプリケーションの実行環境など、環境によって変更したい情報を設定する用途でよく使われます。

例えば、次のような情報を環境変数として管理できます。

APP_ENV=production
DB_HOST=localhost
DB_NAME=sample_db
DB_USER=sample_user
DB_PASSWORD=secret
API_KEY=xxxxxxxx

これらの値をPHPファイルへ直接書き込むこともできますが、開発環境と本番環境で設定が異なる場合、そのたびにコードを書き換えなければなりません。

環境変数を利用すれば、PHPのコードを変更せず、サーバー側や実行環境側の設定を変更するだけで値を切り替えられます。

また、パスワードやAPIキーなどの機密情報をソースコードから分離しやすくなる点も大きなメリットです。

PHPで環境変数を使うメリット

PHPで環境変数を利用すると、設定情報とプログラム本体を分離できます。

特に、Webアプリケーションを開発・運用する場合に有効です。

開発環境と本番環境を切り替えやすい

Webアプリケーションでは、開発環境と本番環境で異なるデータベースやAPIを利用することがあります。

例えば、開発環境では次のように設定します。

APP_ENV=development
DB_HOST=localhost
DB_NAME=myapp_dev

本番環境では次のように設定できます。

APP_ENV=production
DB_HOST=db.example.com
DB_NAME=myapp_production

PHP側では同じコードを利用できます。

<?php

$appEnv = getenv('APP_ENV');
$dbHost = getenv('DB_HOST');
$dbName = getenv('DB_NAME');

環境ごとにPHPファイルを書き換える必要がないため、設定ミスを減らしやすくなります。

パスワードやAPIキーをコードから分離できる

データベースのパスワードやAPIキーをPHPファイルへ直接記述すると、Gitなどへ誤って登録してしまう可能性があります。

例えば、次のような書き方です。

<?php

$dbPassword = 'secret-password';
$apiKey = 'abcdef123456';

環境変数を利用すると、PHPコードには変数名だけを記述できます。

<?php

$dbPassword = getenv('DB_PASSWORD');
$apiKey = getenv('API_KEY');

実際の値をコードから切り離せるため、設定管理やセキュリティ対策を行いやすくなります。

ただし、環境変数を利用すれば自動的に安全になるわけではありません。

サーバーのアクセス権限やログ、CI/CD、秘密情報管理サービスなども含めて適切に管理する必要があります。

PHPで環境変数を取得する方法

PHPで環境変数を取得する代表的な方法として、getenv()と$_ENVがあります。

利用環境や設計によって使い分けます。

getenv()で環境変数を取得する

getenv()は、PHPに標準で用意されている環境変数取得用の関数です。

基本的な書き方は次のとおりです。

<?php

$appEnv = getenv('APP_ENV');

echo $appEnv;

環境変数として次の値が設定されている場合、

APP_ENV=production

実行結果は次のようになります。

production

指定した環境変数が存在しない場合、getenv()はfalseを返します。

そのため、次のように厳密比較して確認できます。

<?php

$appEnv = getenv('APP_ENV');

if ($appEnv === false) {
    echo 'APP_ENVが設定されていません';
} else {
    echo $appEnv;
}

falseとの比較には===を利用するのがポイントです。

getenv()でデフォルト値を設定する

環境変数が存在しなかった場合に、デフォルト値を利用することもできます。

<?php

$appEnv = getenv('APP_ENV');

if ($appEnv === false) {
    $appEnv = 'development';
}

次のように短く記述する方法もあります。

<?php

$appEnv = getenv('APP_ENV') ?: 'development';

ただし、この書き方では"0"などPHPで偽として評価される値もデフォルト値に置き換わります。

環境変数が存在しない場合だけデフォルト値を設定したいなら、=== falseで判定する方が確実です。

getenv()のlocal_onlyについて

getenv()には第2引数としてlocal_onlyを指定できます。

例えば次のように記述します。

<?php

$value = getenv('APP_ENV', true);

FastCGIなど一部の実行環境では、SAPIによって設定された値とローカルな環境変数が同じ名前で存在することがあります。

local_onlyをtrueにすると、OSやputenv()などによって設定されたローカル側の値を取得できます。

一般的なPHP開発では第1引数だけを使うケースが多いですが、実行環境によっては知っておくと役立ちます。

$_ENVで環境変数を取得する方法

$_ENVは、PHPのスーパーグローバル変数の一つです。

環境変数を連想配列として扱えます。

<?php

echo $_ENV['APP_ENV'];

環境変数が設定されていない可能性を考慮するなら、次のように記述できます。

<?php

$appEnv = $_ENV['APP_ENV'] ?? 'development';

echo $appEnv;

$_ENVが空になる場合がある

$_ENVは、PHPの設定によって利用できない場合があります。

関係する設定がphp.iniのvariables_orderです。

例えば次のようになっている場合、

variables_order = "GPCS"

Eが含まれていないため、$_ENVは環境変数の生成対象になりません。

EはEnvironmentを表します。

例えば次のように設定すると、$_ENVを利用できる構成になります。

variables_order = "EGPCS"

それぞれの文字はおおむね次の意味です。

E = Environment
G = GET
P = POST
C = Cookie
S = Server

なお、auto_globals_jitなどPHP内部の設定によって、$_ENVは実際に参照されたタイミングで生成される場合があります。

そのため、厳密には「Eが含まれている場合、$_ENVが利用可能になる」と理解するとよいでしょう。

getenv()と$_ENVの違い

getenv()と$_ENVはどちらも環境変数を扱えますが、仕組みや使い方が異なります。

getenv()の特徴

getenv()は関数として環境変数を取得します。

$value = getenv('APP_ENV');

OSやPHPの実行環境から渡された環境変数を取得する場合に分かりやすい方法です。

$_ENVの特徴

$_ENVは配列として環境変数を扱います。

$value = $_ENV['APP_ENV'] ?? null;

ただし、php.iniのvariables_orderなどの設定に影響されます。

また、Dotenvライブラリによっては$_ENVへ値を読み込む設計が採用されています。

$_SERVERとの違い

$_SERVERは、サーバーやPHPの実行環境に関する情報を格納するスーパーグローバル変数です。

例えば次のような情報が入ることがあります。

<?php

echo $_SERVER['REQUEST_METHOD'] ?? '';
echo $_SERVER['SERVER_NAME'] ?? '';

CGIやFastCGIでは環境由来の値が$_SERVERに格納される場合もあります。

ただし、どの値が存在するかはWebサーバーやPHPの実行方式によって異なります。

単純な環境変数の管理では、getenv()や$_ENV、利用しているフレームワークの仕組みを使用する方が分かりやすいでしょう。

PHPから環境変数を設定する方法

PHPの実行中に環境変数を設定したい場合はputenv()を利用できます。

putenv()の基本的な使い方

次のように記述します。

<?php

putenv('APP_ENV=development');

echo getenv('APP_ENV');

実行結果は次のようになります。

development

putenv()は永続的な設定ではない

putenv()は、OSへ環境変数を恒久的に登録するための関数ではありません。

現在実行中のPHPプロセスの環境を変更するために利用します。

また、その値が別のPHPスクリプト実行時まで維持されることを前提にするべきではありません。

PHPの実行方式によって挙動が異なるため、永続的な環境変数はOS、Webサーバー、Docker、クラウドサービスなどの設定側で管理するのが基本です。

$_ENVへ直接代入するとどうなるか

次のように$_ENVへ直接値を代入することもできます。

<?php

$_ENV['APP_ENV'] = 'development';

ただし、これは$_ENVというPHPの配列へ値を追加しているだけです。

OSやPHPプロセスそのものの環境変数を恒久的に変更しているわけではありません。

PHPプロセスの環境へ値を設定する場合にはputenv()を利用します。

<?php

putenv('APP_ENV=development');

ただし、前述したようにputenv()も永続的な環境設定を行う仕組みではありません。

LinuxやmacOSで環境変数を設定する方法

LinuxやmacOSでは、シェルから環境変数を設定できます。

exportで環境変数を設定する

bashやzshでは、次のように設定します。

export APP_ENV=production

確認する場合は次のようにします。

echo $APP_ENV

PHPから取得します。

<?php

echo getenv('APP_ENV');

PHP実行時だけ環境変数を渡す

特定のPHPコマンドを実行するときだけ環境変数を渡すこともできます。

APP_ENV=development php index.php

PHPでは通常どおり取得できます。

<?php

echo getenv('APP_ENV');

CLIで実行するPHPスクリプトやバッチ処理などで便利な方法です。

Windowsで環境変数を設定する方法

WindowsでもコマンドプロンプトやPowerShellから環境変数を設定できます。

コマンドプロンプトで設定する

現在のコマンドプロンプトで一時的に設定する場合は、次のようにします。

set APP_ENV=development

確認します。

echo %APP_ENV%

そのままPHPを実行できます。

php index.php

PHPでは次のように取得します。

<?php

echo getenv('APP_ENV');

PowerShellで設定する

PowerShellでは次のように記述します。

$env:APP_ENV = "development"

確認する場合は次のようにします。

$env:APP_ENV

PHPからは同じように取得できます。

<?php

echo getenv('APP_ENV');

.envファイルとは

PHP開発では、環境ごとの設定を.envファイルへまとめる方法がよく利用されます。

例えば次のような内容です。

APP_ENV=development
APP_DEBUG=true

DB_HOST=localhost
DB_PORT=3306
DB_NAME=sample_db
DB_USER=root
DB_PASSWORD=password

.envへ設定値をまとめることで、PHPファイルと設定情報を分離しやすくなります。

PHPは.envを自動的に読み込まない

注意したいのは、.envというファイルを置いただけではPHPが自動的に読み込んでくれるわけではないことです。

例えば、

APP_ENV=development

という.envを作成しただけで、

<?php

echo getenv('APP_ENV');

から必ず値を取得できるわけではありません。

.envを利用する場合は、LaravelやSymfonyなどのフレームワークが提供する仕組みや、Dotenvライブラリなどを使って読み込む必要があります。

phpdotenvで.envを読み込む方法

PHPで.envを読み込むライブラリとして、vlucas/phpdotenvがあります。

Composerを利用してインストールできます。

composer require vlucas/phpdotenv

phpdotenvの基本的な使い方

例えば、プロジェクトを次のような構成にします。

project/
├── .env
├── composer.json
├── index.php
└── vendor/

.envへ次のように記述します。

APP_ENV=development
DB_HOST=localhost
DB_NAME=sample_db
DB_USER=root
DB_PASSWORD=password

PHP側では次のように読み込みます。

<?php

require __DIR__ . '/vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

$appEnv = $_ENV['APP_ENV'];

echo $appEnv;

createImmutable()を利用した場合、phpdotenvは既存の環境変数を不用意に上書きしない設計になります。

createMutable()との違い

既存の値を上書きできるようにしたい場合は、createMutable()を利用できます。

<?php

$dotenv = Dotenv\Dotenv::createMutable(__DIR__);
$dotenv->load();

通常は、OSや本番環境側で設定された値を.envによって意図せず上書きすることを避けるため、createImmutable()を利用する方が安全です。

phpdotenvでは$_ENVを利用する

phpdotenvの通常のcreateImmutable()では、読み込んだ値を$_ENVなどから利用します。

<?php

$appEnv = $_ENV['APP_ENV'] ?? null;

phpdotenvにはcreateUnsafeImmutable()も用意されており、getenv()やputenv()へ反映させる構成も可能です。

ただし、phpdotenvではgetenv()やputenv()を積極的に利用する方法は推奨されていません。

一般的にはcreateImmutable()と$_ENVを組み合わせると分かりやすいでしょう。

.envをGitへ登録しないようにする

.envには、次のような機密情報が含まれることがあります。

DB_PASSWORD
API_KEY
SECRET_KEY
ACCESS_TOKEN
PRIVATE_KEY

そのため、秘密情報を含む実際の.envは通常Git管理対象から外します。

.gitignoreへ次のように記述します。

.env

.env.exampleを用意する

実際の値を含めず、必要な環境変数だけを示す.env.exampleを用意すると便利です。

APP_ENV=development
APP_DEBUG=false

DB_HOST=localhost
DB_PORT=3306
DB_NAME=
DB_USER=
DB_PASSWORD=
API_KEY=

新しくプロジェクトへ参加した人は、これをコピーして利用できます。

cp .env.example .env

その後、自分の環境に合わせて値を設定します。

データベース接続情報を環境変数で管理する方法

環境変数の代表的な用途の一つが、データベース接続情報の管理です。

.envへデータベース情報を設定する

例えば次のようにします。

DB_HOST=localhost
DB_PORT=3306
DB_NAME=sample_db
DB_USER=sample_user
DB_PASSWORD=secret

phpdotenvを読み込んだ後、次のように取得できます。

<?php

$host = $_ENV['DB_HOST'];
$port = $_ENV['DB_PORT'];
$dbName = $_ENV['DB_NAME'];
$user = $_ENV['DB_USER'];
$password = $_ENV['DB_PASSWORD'];

PDOへ環境変数を渡す

取得した値をPDOへ渡す例です。

<?php

$dsn = "mysql:host={$host};port={$port};dbname={$dbName};charset=utf8mb4";

$pdo = new PDO(
    $dsn,
    $user,
    $password,
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    ]
);

このようにすれば、データベースのパスワードをPHPソースコードへ直接記述せずに済みます。

APIキーを環境変数で管理する方法

外部サービスのAPIキーも、環境変数として管理するのが一般的です。

環境変数へAPIキーを設定する

例えば次のように設定します。

API_KEY=xxxxxxxxxxxxxxxx

PHPでは次のように取得できます。

<?php

$apiKey = getenv('API_KEY');

if ($apiKey === false) {
    throw new RuntimeException(
        'API_KEYが設定されていません'
    );
}

phpdotenvを利用している場合は次のようにできます。

<?php

$apiKey = $_ENV['API_KEY'] ?? null;

if ($apiKey === null) {
    throw new RuntimeException(
        'API_KEYが設定されていません'
    );
}

APIキーやパスワードはブラウザ上へ表示したり、ログへ不用意に出力したりしないことも重要です。

環境変数の値は文字列として扱う

環境変数を利用するときは、値の型に注意する必要があります。

例えば次のように設定したとします。

APP_DEBUG=false
DB_PORT=3306

見た目ではfalseは真偽値、3306は整数に見えます。

しかし、環境変数から取得した値は基本的に文字列として扱う必要があります。

falseという文字列に注意する

次のコードには注意が必要です。

<?php

$debug = getenv('APP_DEBUG');

if ($debug) {
    echo 'デバッグモードです';
}

環境変数へ、

APP_DEBUG=false

と設定しても、取得される"false"はPHPの論理値falseそのものではありません。

真偽値として利用する場合は明示的に変換します。

<?php

$debug = filter_var(
    getenv('APP_DEBUG'),
    FILTER_VALIDATE_BOOLEAN
);

数値は整数へ変換する

ポート番号などを整数として利用したい場合は、必要に応じてキャストします。

<?php

$port = (int) getenv('DB_PORT');

アプリケーション内部では、環境変数をそのまま使うのではなく、用途に合わせて適切な型へ変換すると安全です。

必須の環境変数をチェックする

必要な環境変数が設定されていない状態で処理を続けると、後から分かりにくいエラーが発生する場合があります。

そのため、アプリケーションの起動時にチェックする方法が有効です。

getenv()で確認する

例えば次のようにします。

<?php

$required = [
    'DB_HOST',
    'DB_NAME',
    'DB_USER',
    'DB_PASSWORD',
];

foreach ($required as $key) {
    if (getenv($key) === false) {
        throw new RuntimeException(
            "{$key}が設定されていません"
        );
    }
}

phpdotenvのrequired()を使う

phpdotenvを利用している場合は、必須項目をまとめて検証することもできます。

<?php

$dotenv->required([
    'DB_HOST',
    'DB_NAME',
    'DB_USER',
    'DB_PASSWORD',
]);

環境変数の設定漏れを早い段階で発見できるため、実際のアプリケーションでも有効な方法です。

DockerでPHPの環境変数を設定する方法

Dockerを利用している場合、コンテナへ直接環境変数を渡せます。

Docker Composeで設定する

例えば、Composeファイルでは次のように記述できます。

services:
  app:
    environment:
      APP_ENV: production
      DB_HOST: database

PHPでは通常どおり取得できます。

<?php

$appEnv = getenv('APP_ENV');
$dbHost = getenv('DB_HOST');

Dockerやクラウド環境を利用する場合、本番環境では.envファイルだけに依存せず、実行基盤側から環境変数を渡す構成もよく利用されます。

PHPフレームワークで環境変数を使う場合

LaravelやSymfonyなどのPHPフレームワークでは、環境変数を管理する仕組みが用意されています。

そのため、フレームワークを利用している場合は、独自にgetenv()やphpdotenvを追加する前に、フレームワークが推奨する方法を確認することが重要です。

Laravelの場合

Laravelでは.envファイルを利用した設定管理が標準的に行われます。

ただし、アプリケーションコードのさまざまな場所から直接env()を呼び出すのではなく、設定ファイルを経由して値を利用する設計が基本です。

Symfonyの場合

SymfonyにはDotenvコンポーネントがあり、.envファイルを利用した環境設定が可能です。

利用しているフレームワークによって推奨される環境変数の扱い方が異なるため、それぞれの公式ドキュメントに従うことが重要です。

PHPの環境変数で起こりやすいトラブル

環境変数は便利ですが、実行環境によって挙動が異なることがあります。

代表的なトラブルを理解しておくと、問題を切り分けやすくなります。

getenv()がfalseになる

次のコードで、

<?php

var_dump(getenv('APP_ENV'));

falseになる場合、PHPプロセスへ環境変数が渡されていない可能性があります。

特に注意したいのが、CLIとWebサーバーでは実行環境が異なることです。

例えば、ターミナルから実行すると取得できても、

php index.php

ApacheやNginx、PHP-FPM経由では取得できないことがあります。

PHPを実行しているプロセスへ、実際に環境変数が渡されているか確認する必要があります。

$_ENVが空になっている

$_ENVが空の場合は、php.iniのvariables_orderを確認します。

variables_order = "GPCS"

この設定ではEが含まれていません。

$_ENVを利用する場合は、例えば次のような設定を検討します。

variables_order = "EGPCS"

ただし、共有サーバーなどではPHP設定を自由に変更できない場合があります。

.envを書いたのに値が取得できない

.envを作成しただけではPHPは自動的に読み込みません。

例えば、

APP_ENV=development

を作成しても、Dotenvライブラリなどでロードしなければ利用できません。

phpdotenvなら次のように読み込みます。

<?php

require __DIR__ . '/vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

その後、

<?php

echo $_ENV['APP_ENV'];

のように利用できます。

PHPの環境変数を安全に扱うポイント

環境変数を利用する場合、単に値を外部へ移すだけでなく、管理方法にも注意する必要があります。

秘密情報をGitへコミットしない

次のような情報をGitへ登録しないようにします。

DB_PASSWORD
API_KEY
SECRET_KEY
ACCESS_TOKEN
PRIVATE_KEY

秘密情報を含む.envは通常.gitignoreへ追加します。

.env

万が一、APIキーなどをGitへコミットして外部へ公開した場合は、ファイルを削除するだけでは不十分なことがあります。

Gitの履歴に情報が残る可能性があるため、該当するキーやパスワードを失効・変更することも重要です。

phpinfo()を本番環境で公開しない

PHPの設定を確認するために、次のようなコードを使うことがあります。

<?php

phpinfo();

phpinfo()は開発時のトラブル調査には便利ですが、PHPの設定やサーバー環境に関する多くの情報を表示します。

本番環境で外部から閲覧できる状態にしておくのは避けるべきです。

確認が終わったら削除するか、外部からアクセスできないように管理します。

パスワードを画面やログへ表示しない

次のようなコードは避けます。

<?php

echo getenv('DB_PASSWORD');

環境変数に移したとしても、画面やログへ表示すれば秘密情報が漏れる可能性があります。

デバッグ時にもパスワードやAPIキーそのものを出力しないよう注意が必要です。

PHPで環境変数を管理するおすすめの構成

小規模なPHPプロジェクトでphpdotenvを利用する場合、例えば次のような構成にできます。

my-project/
├── .env
├── .env.example
├── .gitignore
├── composer.json
├── public/
│   └── index.php
└── vendor/

.gitignoreを設定する

.env
/vendor/

.env.exampleを作成する

APP_ENV=development
APP_DEBUG=false

DB_HOST=localhost
DB_PORT=3306
DB_NAME=
DB_USER=
DB_PASSWORD=

実際の.envを作成する

APP_ENV=development
APP_DEBUG=true

DB_HOST=localhost
DB_PORT=3306
DB_NAME=sample_db
DB_USER=sample_user
DB_PASSWORD=secret

PHPで.envを読み込む

<?php

require dirname(__DIR__) . '/vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(
    dirname(__DIR__)
);

$dotenv->load();

$appEnv = $_ENV['APP_ENV'] ?? 'production';

このような構成にすると、プログラム本体と環境固有の設定を分離しやすくなります。

PHPで環境変数を扱う方法のまとめ

PHPでは、環境変数を利用することで、データベース接続情報やAPIキー、実行環境などの設定をソースコードから分離できます。

PHP標準で環境変数を取得する代表的な方法はgetenv()です。

<?php

$appEnv = getenv('APP_ENV');

$_ENVを利用する方法もあります。

<?php

$appEnv = $_ENV['APP_ENV'] ?? null;

ただし、$_ENVはphp.iniのvariables_orderなどの設定に影響される点に注意が必要です。

PHP実行中に一時的に環境変数を設定する場合はputenv()を利用できます。

<?php

putenv('APP_ENV=development');

ただし、putenv()はOSへ環境変数を恒久的に登録する機能ではありません。

また、.envファイルはPHPが自動的に読み込むわけではないため、phpdotenvやフレームワークが提供する仕組みを利用する必要があります。

phpdotenvを利用する場合は、一般的には次のようにcreateImmutable()で読み込み、

<?php

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

$_ENVから値を利用します。

<?php

$appEnv = $_ENV['APP_ENV'];

実際の開発では、**「PHPコードには環境変数の名前だけを記述し、パスワードやAPIキー、接続先などの実際の値は実行環境側で管理する」**という考え方が基本です。

この方法を採用すると、開発環境と本番環境を切り替えやすくなり、設定の保守性や安全性も高めやすくなります。

以上、PHPで環境変数を扱う方法や設定方法についてでした。

最後までお読みいただき、ありがとうございました。