Как использовать файл .user.ini в ServBay: руководство по локальной настройке PHP

ServBay — это мощная интегрированная локальная среда для веб-разработки, созданная специально для разработчиков и поддерживающая множество языков и технологических стеков, включая гибкое управление версиями PHP и удобные опции конфигурирования. На практике различные проекты могут иметь разные требования к настройкам PHP — например, ограничение размера загружаемых файлов, лимит памяти или уровень отображаемых ошибок. Если напрямую изменять глобальный файл php.ini, изменения затронут все проекты, что неудобно при одновременной работе с несколькими приложениями.

К счастью, PHP предоставляет механизм файла .user.ini, позволяющий разработчику определять кастомные PHP-настройки на уровне отдельной директории и её поддиректорий без модификации глобального php.ini. ServBay полностью поддерживает .user.ini, что делает точечную настройку PHP для отдельных проектов или папок максимально простой и эффективной.

В этом материале подробно рассказывается о принципах работы файла .user.ini, способах его использования в ServBay и приводятся примеры, как задать уникальные PHP-настройки только для нужного проекта.

Обзор файла .user.ini

Файл .user.ini появился, начиная с версии PHP 5.3.0, и был призван заменить устаревшие методы конфигурирования PHP через директивы php_value и php_flag в настройках веб-сервера (например, в .htaccess для Apache). Такой подход более гибкий и безопасный. Файл .user.ini, размещённый в доступной через веб директории, влияет только на PHP-скрипты в этой папке и её поддеректориях.

Основные преимущества

1. Локальная область действия: директивы в .user.ini воздействуют только на ту директорию, где располагается файл, и все её подпапки. Они не затрагивают глобальный php.ini ServBay или конфигурации других проектов.
2. Высокая гибкость: разработчик может задавать независимую конфигурацию PHP, отвечающую требованиям каждого конкретного проекта.
3. Простота управления: нет необходимости редактировать глобальные файлы сервера или PHP, благодаря чему снижается риск конфликтов конфигураций, а настройка становится более независимой и переносимой.
4. Без перезапуска сервера: изменения в .user.ini обычно вступают в силу автоматически через интервал, задаваемый директивой user_ini.cache_ttl (по умолчанию — 300 секунд или 5 минут), в отличие от глобального php.ini, при изменениях которого требуется перезапуск PHP-FPM или веб-сервера.

Какие директивы доступны для настройки

Не все директивы PHP можно задать в .user.ini: это определяется «режимом изменения» (Changeable Modes) каждой настройки. В файле .user.ini можно указывать только те параметры, режим которых — PHP_INI_USER, PHP_INI_PERDIR или PHP_INI_ALL.

Примеры часто используемых в .user.ini директив:

• upload_max_filesize
• post_max_size
• memory_limit
• display_errors
• log_errors
• max_execution_time
• session.save_path
• date.timezone

Директивы с режимом PHP_INI_SYSTEM (например, extension_dir, zend_extension, disable_functions и др.) не могут настраиваться через .user.ini — их можно задавать только в основном php.ini или конфигурации сервера.

Посмотреть режим изменения конкретной директивы можно в руководстве PHP по конфигурационным директивам php.ini.

Использование .user.ini в ServBay

Процесс использования .user.ini в ServBay очень прост. Ниже приведены шаги настройки на примере повышения лимита загрузки файлов и увеличения лимита памяти скрипта.

Допустим, ваш веб-проект размещён в корневой директории ServBay: /Applications/ServBay/www/, а для проекта myproject вам нужно задать индивидуальные параметры PHP для каталога веб-корня: /Applications/ServBay/www/myproject/public.

Шаг 1: Определите целевую папку

Для начала определите директорию, к которой должны применяться ваши индивидуальные настройки. Обычно это веб-корень вашего проекта (например, папка public для проектов Laravel или Symfony) либо другая подпапка, где нужна особая конфигурация.

Пример: /Applications/ServBay/www/myproject/public

Шаг 2: Создайте или отредактируйте файл .user.ini

В указанной директории создайте новый файл под названием .user.ini (или отредактируйте существующий). Обратите внимание: файлы, начинающиеся с точки, обычно скрыты — настройте файловый менеджер на отображение скрытых файлов.

Создать файл можно через терминал:

cd /Applications/ServBay/www/myproject/public
touch .user.ini

Затем откройте .user.ini в текстовом редакторе и добавьте нужные директивы PHP, размещая каждую на новой строке. Пример:

; Устанавливаем максимальный размер загружаемого файла — 20МБ
upload_max_filesize = 20M

; Ограничиваем лимит памяти для PHP-скрипта до 256МБ
memory_limit = 256M

; Включаем отображение ошибок (рекомендуется только на этапе разработки)
display_errors = On

Сохраните и закройте файл .user.ini.

Шаг 3: Ожидайте вступления изменений в силу или форсируйте обновление

Изменения в .user.ini применяются не мгновенно: PHP кэширует их для повышения производительности. За интервал обновления отвечает директива user_ini.cache_ttl — обычно это 300 секунд (5 минут). После истечения срока изменения подхватятся автоматически.

Чтобы увидеть результат сразу, используйте один из следующих способов (возможности могут различаться в зависимости от используемой версии и конфигурации ServBay):

1. Перезапустить соответствующий процесс PHP-FPM: в интерфейсе ServBay найдите версию PHP, которую использует сайт, и перезапустите соответствующий сервис PHP-FPM.
2. Перезапустить ServBay: это самый гарантированный способ, но приведёт к остановке всех локальных сервисов.
3. Дождаться истечения времени кэша: рекомендовано в большинстве случаев, если нет острой необходимости в мгновенном применении.

Шаг 4: Проверьте, применились ли настройки из .user.ini

Для проверки эффективности настроек .user.ini, создайте в той же папке, где лежит .user.ini (например, /Applications/ServBay/www/myproject/public), файл info.php со следующим содержимым:

<?php
phpinfo();
?>

Сохраните файл info.php.

Затем откройте в браузере страницу проекта на ServBay и перейдите по адресу файла info.php. Например, если у проекта настроен домен myproject.servbay.demo, а файл размещён в папке public, адрес будет примерно таким: https://myproject.servbay.demo/info.php.

На загруженной странице функции phpinfo() найдите интересующие директивы (например, upload_max_filesize, memory_limit, display_errors). Обычно их параметры показаны в двух колонках: Master Value и Local Value.

• Master Value — значение, заданное в глобальном php.ini.
• Local Value — текущее значение для исполняемого скрипта (из .user.ini или конфигурации сервера).

Если в колонке Local Value показаны введённые вами значения (20M, 256M, On), значит, настройки из .user.ini функционируют корректно.

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

Дополнительные пояснения и рекомендации

• Имя и расположение файла: Файл обязательно должен называться .user.ini и находиться в директории, к которой нужно применять настройки — он затрагивает также все внутренние папки.
• Поддержка режимов директив: Напоминаем: только директивы с нужным режимом можно настраивать через .user.ini. Попытка изменить директиву с режимом PHP_INI_SYSTEM не даст эффекта и может не вызвать ошибок. Смотрите руководство PHP.
• Кэширование: Учитывайте значение параметра user_ini.cache_ttl. Если вы часто изменяете .user.ini и хотите видеть эффект немедленно, временно уменьшите это значение в глобальном php.ini (например, user_ini.cache_ttl = 5), но на продуктивных серверах не рекомендуется устанавливать слишком маленький интервал — это может негативно сказаться на производительности. Изменение глобального php.ini требует перезапуска PHP-FPM.
• Приоритет настроек: Приоритет применения PHP-конфигурации обычно следующий: значения по умолчанию ядра < php.ini (или дополнительных файлов .ini) < конфигурация веб-сервера (php_value/php_flag, если используется Apache/nginx) < .user.ini < функция ini_set() в скрипте. Значения из .user.ini перекрывают одноимённые из глобального php.ini, но могут быть перезаписаны вызовами ini_set() в самих скриптах.
• Безопасность: Не храните в .user.ini чувствительные данные — несмотря на то, что его область действия ограничена, сам файл, как правило, размещается в публичной директории проекта.

Часто задаваемые вопросы (FAQ)

В: Я создал .user.ini и добавил нужные директивы, но они не действуют. Почему?

О: Возможные причины:

1. Ошибка в имени или месте файла: Убедитесь, что имя файла — .user.ini, а папка выбрана верно.
2. Директива не поддерживает этот режим: Возможно, вы пытаетесь задать директиву, не поддерживаемую в .user.ini (режим не PHP_INI_USER или PHP_INI_PERDIR). Проверьте актуальный список в руководстве PHP.
3. Кэш не обновлён: Подождите завершения времени, указанного в user_ini.cache_ttl (обычно 5 минут), либо перезапустите PHP-FPM.
4. Синтаксическая ошибка: Проверьте файл на наличие ошибок.
5. Настройка перекрыта более приоритетным уровнем: Возможно, в коде вызывается функция ini_set(), которая перекрывает ваши значения.

В: В чем разница между .user.ini и глобальным файлом php.ini?

О: Глобальный php.ini влияет на все окружение PHP (или на приложения для конкретной версии), и его параметры действуют для всех скриптов (если не переопределены на более высоком уровне). .user.ini затрагивает параметр только для скриптов в текущей папке и её подпапках, причём не все директивы разрешены к использованию этим способом. Главная сила .user.ini — это точечная настройка и отсутствие необходимости менять глобальный файл.

Заключение

Использование .user.ini в ServBay — лучший способ задать отдельные PHP-настройки для конкретного проекта. Такой подход максимально гибок и даёт разработчику возможность конфигурировать среду PHP для каждого приложения независимо, не затрагивая все остальные проекты или глобальные параметры ServBay. Следуя этому руководству и приведённым примерам, вы легко сможете самостоятельно внедрять и управлять локальными настройками PHP, значительно повышая эффективность и удобство разработки. Концепция ServBay — предоставить разработчикам гибкие и мощные локальные средства, и поддержка .user.ini — отличная иллюстрация этого подхода.