#Когда возникает ошибка
После переноса PHP-проекта с Windows/macOS на Linux либо переименования каталога строка include_once "Includes/config.php" может не находить файл, который лежит в includes/Config.php. На файловых системах с учётом регистра это разные пути. Кроме регистра, относительный путь может считаться из другого рабочего каталога, а имя каталога в хранилище Git может не обновиться ожидаемым образом.
#Причины и признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Различие прописных и строчных буквВ коде и на диске отличается хотя бы одна буква в имени каталога или файла. | На одной файловой системе работает, на Linux выдаёт failed to open stream. | Исправьте точный регистр пути или аккуратно переименуйте файл во всех местах проекта. |
| Относительный путь зависит от запускаPHP подключает файл из другого начального каталога либо не находит его в include_path. | Запуск напрямую работает, из фронт-контроллера — нет. | Стройте путь относительно __DIR__ файла, который подключает ресурс. |
| Файл отсутствует в развёртыванииНа локальной машине файл есть, а серверный пакет не содержит его в ожидаемом регистре. | ls на сервере не показывает точное имя; Git не зафиксировал смену регистра. | Сверьте упаковку, Git и релиз без ручного изменения работающих путей. |
#Пошаговая диагностика и устранение
- Найдите конкретный путь из журналаОткройте закрытый журнал PHP-FPM или вывод тестового запуска и найдите
include_once(): Failed to open streamиFailed opening. Скопируйте только путь без конфиденциальных данных. Затем откройте файл со строкойinclude_onceв редакторе и найдите написание пути в кавычках. Не меняйте все include в проекте по одному случаю. - Проверьте наличие пути с точным регистромВ терминале Linux перейдите в каталог проекта и используйте
ls -laдля каждого уровня: например сначала родительский каталог, затем папкуIncludesи файлConfig.php. В панели файлового менеджера также можно сравнить буквы имён. Если в каталог не удаётся войти из-за прав, обратитесь к администратору; не меняйте права целого сайта наугад. - Сверьте путь относительно самого подключающего файлаВ PHP-файле, который выполняет include_once, используйте
__DIR__— каталог этого файла. Если ресурс на один уровень ниже, соберите конкретный путь как__DIR__ . "/Includes/Config.php". Для другого расположения замените обе части реальным путём;__DIR__не обозначает корень сайта и не совпадает автоматически с$_SERVER["DOCUMENT_ROOT"]. - Отличите проблему регистра от отсутствия файлаВ отдельном тестовом блоке перед подключением примените
is_file($path), чтобы проверить именно собранный путь. Если false, выведите в закрытый журналbasenameфайла и путь к родительской папке, а затем сверяйте список файлов; не выводите серверные пути посетителям. Если true, но подключение всё равно не работает, смотрите права чтения или ошибки внутри самого подключаемого файла. - Исправьте написание и сохраните единообразиеЕсли файл реально называется
Config.php, везде используйте точноConfig.php. Если принято имяconfig.php, переименуйте файл согласованно и убедитесь, что система контроля версий видит изменение. На файловых системах, не различающих регистр, при необходимости сделайте переименование через промежуточное уникальное имя в отдельном коммите; это требует внимания к одновременным обращениям и ссылкам. - Проверьте репозиторий и копию развёртыванияВ терминале корня проекта выполните
git status --shortиgit ls-files(если Git используется), чтобы посмотреть отслеживаемые имена. Сверьте имя в архиве развёртывания и файловой системе сервера. Если пакет не включает файл, пересоберите копию релиза штатной процедурой; не исправляйте только локальный файл, оставляя источник сборки неверным. - Протестируйте включение и откатите при конфликтеЗапустите
php -l файл_с_include.php, затем откройте тестовую страницу, которая включает ресурс тем же способом. Должны исчезнуть предупреждения открытия файла и сохраниться работа функций, которые он объявляет. Если при переименовании сломались другие подключения, восстановите прежнее состояние из Git/резервной копии и исправьте все ссылки в отдельном согласованном изменении.
#Проверяемый пример и команды
PHP
Измените Includes/Config.php на настоящее имя и регистр файла. Пример предназначен для закрытой тестовой копии проекта;
require_once остановит выполнение при отсутствии критически важного файла.<?php
// Файл здесь находится в подкаталоге Includes рядом с этим скриптом.
$path = __DIR__ . '/Includes/Config.php';
if (!is_file($path)) {
throw new RuntimeException('Файл конфигурации не найден: проверьте регистр имени');
}
require_once $path;Linux · Терминал (Bash)Команда
В терминале корня проекта; php -l замените целевым файлом.
git status нужен только проектам под Git. Команды не меняют исходники.ls -laphp -l index.phpgit status --short#Проверка исправления и действия при неудаче
Ошибка устранена, если точный путь существует на целевом сервере и include_once подключает нужный ресурс один раз без предупреждений. Если ошибка осталась только при веб-запуске, сравните рабочие каталоги, права пользователя PHP-FPM и фактическое содержимое развёрнутого релиза.