PHP Profi

Всё, что вы должны знать о переменных окружения в PHP Перевод

php environment variables .env DotEnv переменные окружения

Переменные окружения, используемые в конфигурации, являются на сегодняшний день основным методом установки в приложении таких настроек, как учетные данные базы, API ключи, секретные ключи и всего, что является различным в зависимости от того, где развертывается приложение. Сейчас такие настройки попадают в код через окружение, вместо прямого прописывания в файлах конфигурации или, того хуже, хардкода прямо в коде.

You can't leak what you don't store

Давайте подробнее взглянем на то:

  • как это работает?
  • действительно ли это хорошая идея?
  • как с ними работать в PHP?
  • и в заключение на некоторые рекомендации и распространенные ошибки, которых следует избегать – на те ловушки, на которые мы наткнулись в реальном мире!

Мы не будем рассматривать как настроить переменные окружения в вашем веб-сервере / Docker-е / crontab-ах... т. к. это зависит от системы, программного обеспечения, а мы хотим сосредоточиться на самих переменных окружения.

Если ваш хостинг использует Docker Swarm или AWS, все будет немного по-другому, например, т. к. они решили подсовывать файлы на файловую систему вашего контейнера, чтобы внедрить ваши секретные ключи, а не использовать переменные окружения. Это очень специфично для этих платформ и не является распространённым вариантом для всех.

Env vars 101

При запуске программы, она наследует все переменные окружения от своих родителей. Так что если вы установите переменную YOLO в значение covfefe в bash, а затем выполните команду, вы сможете прочитать YOLO в любом дочернем процессе.

$ YOLO=covfefe php -r 'echo getenv("YOLO");'
covfefe

Поскольку эта переменная определена только локально, мы не можем прочитать её из другого терминала (другого родителя). Идея в том, чтобы убедиться, что ваше приложение всегда наследует нужные переменные.

Вы можете посмотреть все переменные окружения в командной строке, выполнив следующую команду, но вы не увидите переменной YOLO, т. к. она была передана только в команду php "на лету", а не установлена в текущем процессе:

$ env

Вы можете установить переменную окружения с помощью export <имя>=<значение>:

$ export YOLO=covfefe

Имена переменных чувствительны к регистру и соглашение заключается в использовании имён только на английском, в верхнем регистре, с _ в качестве разделителя (т. н. "змеиный" стиль в верхнем регистре). Вы уже наверняка знаете некоторые переменные – такие как PATH, DISPLAY, HTTP_PROXY

Лучшие практики на сегодня

Возможно, вы уже знаете о двенадцати факторной методологии для создания надежных и масштабируемых приложений (если нет, то я предлагаю вам сделать перерыв и проверить его). Глава о конфигурации объясняет, почему сохранение конфигов в окружении это правильный путь:

  • Конфигурация существенно отличается в зависимости от того, где развёрнуто приложение (production, staging, testing…), код – нет.
  • Переменные окружения легко изменять на разных машинах без изменения кода.
  • Они являются стандартом и не зависят от используемого язык или ОС. Одни и же конфигурации могут использоваться и PHP, и Python процессами.

Манифест также довольно хорошо описывает что должно быть в коде и что должно быть в окружении – не кладите все настройки приложения в него, только то, что отличается у одного развернутого стенда от другого.

Я читал(а) в Интернете, что переменные окружения опасны

Некоторые статьи расскажут вам, что переменные окружения вредны для ваших секретных ключей. Главная причина заключается в том, что любой процесс наследует от своего родителя переменные, все из них. Так что если у вас очень секретная настройка в окружающей среде, дочерние процессы будут иметь доступ к нему:

$ export YOLO=covfefe
$ php -r "echo exec('echo $YOLO');"
covfefe

Дочерние процессы могут рассматривать переменную окружения, как что-то публичное, что можно записать в логи, включить в отчеты об ошибках, вывести пользователю в случае ошибки... Они могут допустить утечку ваших секретных ключей.

Альтернатива – старые текстовые файлы, со строгими Unix-правами. Но что действительно должно быть сделано, очистка окружения при запуске дочернего процесса, которому вы не доверяете, как это делает nginx. По умолчанию nginx удаляет все переменные окружения, унаследованные от своего родительского процесса, за исключением переменной TZ. Проблема решена!

Это можно сделать с помощью команды env -i, которая говорит, что следующие команды должны быть запущены в пустой среде.

$ php -r "echo exec('env -i php -r \'echo getenv(\"YOLO\");\'');"

$ php -r "echo exec('php -r \'echo getenv(\"YOLO\");\'');"
covfefe

Всегда запускайте процессы, которым вы не доверяете, в ограниченной среде.

Даже если вы доверяете вашему коду, вы всё равно должны быть очень осторожны и передавать ваши переменные как можно меньшему количеству процессов – кто и как их будет использовать вы никогда не знаете (внутри драма в NPM-проекте).

Подготовка приложения

При работе с переменными окружения в PHP-проекте, вы хотите убедиться, что ваш код всегда будет получать переменную из надежного источника, будь то $_ENV, $_SERVER, getenv... Но эти три метода не возвращают одинаковые результаты!

$ php -r "echo getenv('HOME');"
/home/foobar

$ php -r 'echo $_ENV["HOME"];'
PHP Notice: Undefined index: HOME

$ php -r 'echo $_SERVER["HOME"];'
/home/foobar

Это потому что настройка variables_order в PHP на моей машине установлена в "GPCS". И так как в ней нет буквы "E", я не могу полагаться на суперглобальный массив $_ENV. Это может привести к тому, что код работающий на одном PHP не будет работать на другом.

Другой камень преткновения – это то, что разработчики не хотят управлять переменными окружения локально. Каждый раз, когда мы редактируем VirtualHost, мы не хотим перезагружать php-fpm или некую службу, или очищать кеш... Разработчики хотят иметь простой и безболезненный способ настройки переменных окружения... как .env файл!

Файл .env - это просто сборник переменных окружения с их значениями:

DATABASE_USER=donald
DATABASE_PASSWORD=covfefe

Библиотеки "Dot Env" в помощь

vlucas/phpdotenv, самая популярная библиотека на данный момент:

Эта библиотека будет читать .env файл и заполнит все суперглобальные переменные:

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

$s3Bucket = getenv('S3_BUCKET');
$s3Bucket = $_ENV['S3_BUCKET'];
$s3Bucket = $_SERVER['S3_BUCKET'];

Есть несколько хороших плюшек, таких как возможность помечать некоторые переменные, как обязательные. (используется фреймворком Laravel)

josegonzalez/dotenv, ориентирована на безопасность:

Эта библиотека не заполнит суперглобальные переменные по умолчанию:

$Loader = new josegonzalez\Dotenv\Loader('path/to/.env');
// Парсим файл .env:
$Loader->parse();
// Отправляем результат парсинга .env в переменную $_ENV:
$Loader->toEnv();

Она поддерживает обязательные переменные, фильтрацию, и может выбрасывать исключения, когда переменная перезаписывается.

symfony/dotenv, новый малыш на этом поприще:

Доступен начиная с Symfony 3.3. Этот компонент заботится о .env-файле, как остальные, и тоже заполняет суперглобальные массивы:

$dotenv = new Symfony\Component\Dotenv\Dotenv();
$dotenv->load(__DIR__.'/.env');

$dbUser = getenv('DB_USER');
$dbUser = $_ENV['DB_USER'];
$dbUser = $_SERVER['DB_USER'];

На packagist есть ещё куча других и я даже боюсь спрашивать, почему каждый пишет тот же парсер снова и снова.

Но все они используют ту же логику:

  • найти .env файл;
  • разобрать его, проверить на вложенные значения, вытащить все переменные;
  • заполнить все суперглобальные массивы переменными, кроме тех, что уже установленны.

Я рекомендую комитить файл .env со значениями, заданными для разработчиков: каждый должен иметь возможность вытащить ваш проект и запустить его так, как ему нравится (сервер из командной строки, Apache, nginx...) без мучений с конфигурацией.

(new Dotenv())->load(__DIR__.'/.env');

Эта рекомендация хорошо работает, когда каждый локально имеет ту же инфраструктуру: тот же пароль к БД, тот же сервер и порт... Т. к. мы используем Docker Compose на всех наших проектах, у нас никогда нет никаких различий в настройках одного разработчика от настроек другого. Если у вас нет такой плюшки, просто позвольте разработчикам перезаписывать настройки по умолчанию, импортировав два файла:

(new Dotenv())->load(__DIR__.'/.env', __DIR__.'/.env.dev');

В этом случае, вы просто должны создать и заполнить файл .env.dev тем, что отличается для вас (и добавить его .gitignore).

Затем на продакшене, вы не должны загружать эти значения по умолчанию:

if (!isset($_SERVER['APP_ENV'])) {
    (new Dotenv())->load(__DIR__.'/.env', __DIR__.'/.env.dev');
}

Если вы так не сделаете, и ваш хостинг-провайдер забудет передать переменную, то запустите код в продакшене с настройками от дева, а это не приведёт ни к чему хорошему.

Подводные камни, на которые вы должны обратить внимание ⚠

Конфликты имен

Нейминг – это сложно, и переменные окружения не являются исключением из этого правила.

Поэтому при именовании переменных окружения, вы должны быть осторожными и допускать как можно меньше конфликтов имен. Ситуация усложняется тем, что нет официального списка зарезервированных имен. Хорошая практика – использовать префиксы пользовательских переменных.

В мире Unix это уже делают, используя LC_, GTK_, NODE_

Отсутствие переменных во время выполнения

У вас есть два варианта в случае, если переменная отсутствует: либо бросить исключение, или использовать значение по умолчанию. Решать вам, но второй вариант молчаливый... Что может принести вред во многих случаях.

Как только вы захотите использовать переменные окружения, вы должны установить их везде:

  • на веб-сервере;
  • в длительных скриптах и сервисах;
  • в crontab-ах…
  • и в сценарии развертывания!

Про последний легко забыть, но так как сценарии могут разогревать кеш приложения (как Symfony-вские)... да, отсутствие переменной может привести к поломке деплоя. Будьте осторожны с этим и добавите проверку при запуске приложения.

Префикс HTTP_

Есть только один префикс, который вы никогда не должны использовать: HTTP_. Потому что его использует сам PHP (и другие cgi-подобные контексты) для хранения заголовков http-запроса.

Вы помните httpoxy уязвимость? Она возникала при поиске http-клиентом переменной в окружении таким образом, что её можно было установить через простой http-заголовок.

Некоторые DotEnv-библиотеки также предотвращают переопределение таких переменных, например, Symfony-компонент.

Потокобезопасность функции getenv()

У меня плохие новости: в некоторых конфигурациях, использование функции getenv() приведет к неожиданным результатам. Эта функция не потокобезопасна!

Вы не должны использовать её для получения ваших значений, поэтому я предлагаю вам вместо этого обращаться к $_SERVER – к тому же есть небольшая разница в производительности между обращением к массиву и вызовом функции в пользу массивов.

Переменные окружения – всегда строки

Одной из главных проблем является то, что сейчас в PHP есть указание типов, а наши настройки не всегда правильно набраны.

class Db
{
    public function connect(string hostname, int port)
    {
    }
}

// Это не будет работать:
$db->connect($_SERVER['DATABASE_HOSTNAME'], $_SERVER['DATABASE_PORT']); 

В Symfony теперь можно преобразовывать variables, а даже больше – чтение файла, декодирование json...…

Переменные окружения везде или нет

На данный момент существует много споров между использованием переменных окружения, файлов, или их смеси: переменная окружения ссылается на файл конфигурации. Дело в том, что несмотря на то, что это считается лучшей практикой, переменные окружения не представляют больших преимуществ...

Но если правильно использовать, в приложении на Symfony, например, переменные окружения могут быть изменены "на лету" - без очистки какого-либо кеша, без обращения к файловой системе, без развертывания кода: просто перезапустив процесс, например.

Тенденция иметь только одну переменную, как APP_CONFIG_PATH, и читать её через '%env(json:file:APP_CONFIG_PATH)%' для меня выглядит как заново изобретать старый добрый parameters.yml, если файл не управляется автоматически с помощью надежного инструмента (как AWS Secret Store). И также есть envkey.com, который позволяет управлять вашими переменными окружения из одного места, не возясь с файлами самостоятельно, мне нравится такой подход, т. к. это гораздо проще!

2017-10-26 alek13 оригинал
General Food

Комментарии

авторизуйтесь, чтобы оставить комментарий