Koriym.EnvJson

env.json logo

.envファイルの代わりにJSONを使って環境変数を設定します。 JSON schemaによるバリデーションにより、環境変数の値を検証します。

特徴

検証機能付き環境変数: JSON schemaによる値の検証機能
充実したドキュメント: スキーマによる説明と制約条件の定義
変換ツール: .envからJSONフォーマットへの移行ツール
CLIユーティリティ: シェル連携と様々な出力形式に対応
フォールバック機能: 開発環境向けのデフォルト値設定

インストール

composer require koriym/env-json

基本的な使い方

// 環境変数の読み込みとバリデーション
$env = (new EnvJson())->load(__DIR__);

// オブジェクトプロパティとしてアクセス
echo $env->DATABASE_URL;

// または従来のgetenv()を使用
echo getenv('DATABASE_URL');

設定ファイル

JSONスキーマ (env.schema.json)

型、説明、制約条件付きで環境変数を定義します:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "required": [
        "DATABASE_URL", "API_KEY"
    ],
    "properties": {
        "DATABASE_URL": {
            "description": "データベース接続文字列",
            "pattern": "^mysql://.*"
        },
        "API_KEY": {
            "description": "外部APIの認証キー",
            "minLength": 32
        },
        "DEBUG_MODE": {
            "description": "デバッグ出力を有効にする (true/false)",
            "enum": ["true", "false"],
            "default": "false"
        },
        "PORT": {
            "description": "サーバーポート番号",
            "pattern": "^[0-9]+$",
            "default": "3000"
        }
    }
}

環境ファイル (env.json / env.dist.json)

実際の設定値:

{
    "$schema": "./env.schema.json",
    "DATABASE_URL": "mysql://user:pass@localhost/mydb",
    "API_KEY": "1234567890abcdef1234567890abcdef",
    "DEBUG_MODE": "true",
    "PORT": "8080"
}

⚠️ 重要: 環境変数の型制約

環境変数は常に文字列として扱われます。JSONスキーマで非文字列型を指定すると検証エラーが発生します。

❌ これらは検証エラーを引き起こします

{
    "DEBUG_MODE": {
        "type": "boolean",
        "default": false
    },
    "PORT": {
        "type": "integer",
        "default": 3000
    },
    "TIMEOUT": {
        "type": "number",
        "default": 30.5
    }
}

エラーメッセージ: 値は文字列（例: “3000”）になりますが、スキーマは整数を期待するため、検証に失敗します。

✅ 正しいアプローチ

{
    "DEBUG_MODE": {
        "description": "デバッグ出力を有効にする (true/false)",
        "enum": ["true", "false"],
        "default": "false"
    },
    "PORT": {
        "description": "サーバーポート番号",
        "pattern": "^[0-9]+$",
        "default": "3000"
    },
    "TIMEOUT": {
        "description": "タイムアウト時間（秒）",
        "pattern": "^[0-9]+(\\.[0-9]+)?$",
        "default": "30.5"
    }
}

推奨パターン

真偽値:

"FEATURE_ENABLED": {
    "enum": ["true", "false"],
    "default": "false"
}

数値:

"TIMEOUT": {
    "pattern": "^[0-9]+$",
    "default": "30"
}

列挙値:

"LOG_LEVEL": {
    "enum": ["debug", "info", "warning", "error"],
    "default": "info"
}

運用フローとベストプラクティス

開発環境

スキーマ作成: すべての必要な変数、型、制約をenv.schema.jsonで定義
デフォルト値: チーム内で共有可能なデフォルト値をenv.dist.jsonに定義（gitリポジトリにコミット可能）
ローカルオーバーライド: 個人環境固有の値をenv.jsonに定義（.gitignoreに追加）
読み込みプロセス:
- EnvJsonはまず既存の環境変数を検証
- 検証に失敗した場合、env.jsonを読み込み
- env.jsonが存在しない場合、env.dist.jsonにフォールバック

本番環境

CI/CD設定:
- デプロイ時にenv.dist.jsonを削除（本番では不要）
- env.jsonは含めない（.gitignoreに追加済み）
設定: すべての環境変数を本番環境に直接設定
検証: EnvJsonがすべての必須変数が存在し有効であることを検証

.envからの変換

既存の.envファイルをJSON形式に変換:

bin/ini2json .env

これによりenv.schema.jsonとenv.dist.jsonの両方が生成されます。

コマンドラインツール: envjson

envjsonコマンドラインツールは様々な環境との連携をサポートします:

# 現在のシェルに変数を読み込む
source <(bin/envjson)

# カスタムディレクトリを指定
source <(bin/envjson -d ./config)

# PHP-FPM形式で出力: env[FOO] = "foo1"
bin/envjson -d ./config -o fpm > .env.fpm

# INI形式で出力: FOO="foo1"
bin/envjson -d ./config -o ini > env.ini

# シェル形式で出力: export FOO="foo1"
bin/envjson -d ./config -o shell > env.sh

オプション

  -d --dir=DIR     envファイルを含むディレクトリ（デフォルト: カレントディレクトリ）
  -f --file=FILE   読み込むJSONファイル名（デフォルト: env.json）
  -o --output=FMT  出力形式: shell, fpm, ini（デフォルト: shell）
  -v --verbose     詳細メッセージを表示
  -q --quiet       警告メッセージを抑制
  -h --help        ヘルプメッセージを表示

なぜ.envではなくJSONか？

検証機能: アプリケーション起動前に値や制約条件を検証
豊富なドキュメント: スキーマに説明、例、制約を直接追加可能
IDE対応: エディタでのJSONスキーマバリデーションによる優れたツーリング
制約データ: JsonSchemaの制約適用による検証

Story

env.json story

Link

This site is open source. Improve this page.