Функции файлов Albireo CMS

checkRealFile checkUrlAsRealFile contentFile copyDir deleteDir dirToArray dirToArrayFlat dirToArrayFlat2 findFile getContentFile getExtension getSubDirs moveFile requireSafe

Функция checkRealFile

Функция для безопасной проверки существования файла и корректности пути.

Сигнатура

function checkRealFile(string $dir, string $file): string|false

Аргументы

string $dir: Базовый каталог (должен быть абсолютным путем)
string $file: Имя файла или относительный путь внутри каталога

Возвращаемое значение

Абсолютный путь к файлу (string) или false если:

Файл не существует
Путь содержит относительные переходы
Пути не совпадают после нормализации

Алгоритм работы

Объединяет базовый каталог и путь к файлу
Приводит разделители путей к системному формату
Проверяет существование файла через realpath()
Сравнивает реальный путь с ожидаемым

Примеры использования

// Проверка файла в Linux
$valid = checkRealFile('/var/www/', 'public/index.php');

// Проверка файла в Windows
$valid = checkRealFile('C:\\www\\', 'public\\index.php');

// Проверка безопасности (защита от path traversal)
if (checkRealFile('/safe/dir/', '../secret.txt') === false) {
    die('Недопустимый путь!');
}

Особенности безопасности

Защищает от атак path traversal ../
Нормализует разделители путей
Проверяет точное соответствие путей
Не подвержена проблемам с относительными путями

Функция checkUrlAsRealFile

Функция для безопасной проверки соответствия URL реальным файлам в файловой системе.

Сигнатура

function checkUrlAsRealFile(string $url): string|false

Аргументы

string $url: Полный HTTP/HTTPS URL для проверки (например https://example.com/path/file.txt)

Возвращаемое значение

Абсолютный путь к файлу (string) или false если:

URL принадлежит другому домену
Файл не существует
Путь выходит за пределы BASE_DIR

Алгоритм работы

Проверяет что URL начинается с http:// или https:// + FRONT_URL_NAME
Заменяет домен на BASE_DIR для получения файлового пути
Проверяет существование файла через realpath()
Убеждается что путь находится внутри BASE_DIR
Для каталогов добавляет trailing slash

Примеры использования

// Проверка существующего файла
$path = checkUrlAsRealFile('https://example.com/images/logo.png');

// Проверка несуществующего файла
if (checkUrlAsRealFile('https://example.com/nonexistent.txt') === false) {
    echo 'Файл не существует';
}

// Попытка доступа к другому домену
checkUrlAsRealFile('https://another.com/secret.txt'); // false

Функция contentFile

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

Сигнатура

function contentFile(string $fn, array $pageData = []): string

Аргументы

string $fn

Путь к файлу для чтения. Должен быть доступен для чтения.

array $pageData

Настройки обработки контента (передаются в processingContent()):

protect-pre: bool - защищать ли HTML в тегах PRE/CODE
parser: string - список парсеров через запятую
text-function: string - список функций через запятую

Возвращаемое значение

Обработанное содержимое файла (string).

Алгоритм работы

Читает содержимое файла через getContentFile()
Передает содержимое и настройки в processingContent()
Возвращает обработанный результат

Примеры использования

// Чтение шаблона без обработки
echo contentFile('/templates/header.php');

// Чтение с обработкой Markdown
$article = contentFile('/content/article.md', [
    'parser' => 'markdown'
]);

// Чтение с защитой кода и обработкой
$codeExample = contentFile('/examples/demo.html', [
    'protect-pre' => true,
    'text-function' => 'htmlspecialchars'
]);

Функция copyDir

Рекурсивное копирование каталогов с сохранением структуры подкаталогов.

Сигнатура

function copyDir(string $src, string $dst): void

Аргументы

string $src: Абсолютный путь к исходному каталогу. Должен существовать и быть доступным для чтения.
string $dst: Абсолютный путь к целевому каталогу. Будет создан (включая все подкаталоги) если не существует.

Примеры использования

// Простое копирование
copyDir('/var/www/old-site', '/var/www/new-site');

// Копирование с предварительной проверкой
if (file_exists($sourceDir)) {
    copyDir($sourceDir, $backupDir . date('Y-m-d'));
}

Обработка ошибок

Генерирует исключение если исходный каталог не существует
Может генерировать предупреждения при проблемах с правами доступа
Рекомендуется использовать try-catch для обработки ошибок

Функция deleteDir

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

Сигнатура

function deleteDir(string $dir): bool

Аргументы

string $dir: Абсолютный путь к удаляемому каталогу. Должен существовать и быть доступным для записи.

Возвращаемое значение

bool: true при успешном удалении, false при возникновении ошибки.

Примеры использования

// Удаление временного каталога
deleteDir('/tmp/old_cache');

// Удаление с обработкой ошибок
try {
    deleteDir('/var/www/old_project');
} catch (RuntimeException $e) {
    error_log('Ошибка удаления: ' . $e->getMessage());
}

Обработка ошибок

Проверяет существование каталога перед удалением
Генерирует исключение при невозможности прочитать/удалить содержимое
Возвращает false при неудачном удалении основного каталога

Функция dirToArray

Рекурсивное сканирование файловой структуры с возможностью фильтрации по расширениям.

Сигнатура

function dirToArray(string $dir, array $allowExt = []): array

Аргументы

string $dir: Абсолютный путь к сканируемому каталогу
array $allowExt: Массив разрешенных расширений файлов (например ['php', 'jpg']). Пустой массив - без фильтрации.

Возвращаемое значение

Ассоциативный массив (array), где:

Ключи - имена подкаталогов
Значения - массивы содержимого подкаталогов
Файлы - элементы массива

Формат результата

Пример возвращаемого массива:

[
    'subdir1' => [
        'file1.txt',
        'file2.php',
        'nested' => [
            'image.jpg'
        ]
    ],
    'file3.html'
]

Примеры использования

// Полное сканирование
$fullTree = dirToArray('/var/www/project');

// С фильтрацией изображений
$images = dirToArray('/var/www/images', ['jpg', 'png', 'gif']);

// Визуализация структуры
function renderTree(array $tree, int $level = 0) {
    foreach ($tree as $key => $value) {
        if (is_array($value)) {
            echo str_repeat('  ', $level) . "[$key]" . PHP_EOL;
            renderTree($value, $level + 1);
        } else {
            echo str_repeat('  ', $level) . "$value" . PHP_EOL;
        }
    }
}

renderTree(dirToArray('/path/to/dir'));

$mapDir = dirToArray(PAGES_DIR, ['php', 'jpg']);
$outText = tree($mapDir); 
// pr($outText); // для просмотра структуры

// функция обхода массива
function tree($data, $tab = '', $root = '')
{
    $result = '';
    
    foreach ($data as $key => $value) {
        if (is_array($value)) {
            // это каталог
            $result .= $tab . DIRECTORY_SEPARATOR . $key . LF;
            $old_root = $root;
            $root = $root . $key . DIRECTORY_SEPARATOR;
            $result .= tree(data: $value, tab: $tab . str_repeat(' ', 4), root: $root);
            $root = $old_root;
        } else {
            // это файл
            $result .= $tab . $root . $value . LF;
        }
    }
    
    return $result;
}

Функция dirToArrayFlat

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

Сигнатура

function dirToArrayFlat(string $scanDir, string $mask = '*.*', array $exclude = []): array

Аргументы

string $scanDir

Абсолютный путь к корневому каталогу для сканирования

string $mask

Маска поиска файлов в синтаксисе glob():

* - любое количество символов
? - один символ
{ext1,ext2} - альтернативные расширения

array $exclude

Массив подкаталогов для исключения (относительные пути от $scanDir)

Возвращаемое значение

Ассоциативный массив (array), где:

Ключи - относительные пути подкаталогов (включая / для корня)
Значения - массивы имен файлов с относительными путями

Особенности работы

Рекурсивно сканирует все подкаталоги
Применяет естественную сортировку (natsort) к результатам
Исключает указанные подкаталоги (полные пути)
Поддерживает сложные маски через GLOB_BRACE
Возвращает относительные пути (без $scanDir)

Примеры использования

// Получить все файлы проекта
$allFiles = dirToArrayFlat('/var/www/project');

// Только PHP и HTML файлы, исключая тестовые каталоги
$codeFiles = dirToArrayFlat('/var/www', '*.{php,html}', ['tests', 'vendor']);

// Получить структуру для отображения
foreach (dirToArrayFlat('/path') as $dir => $files) {
    echo "Каталог $dir:\n";
    foreach ($files as $file) {
        echo "- $file\n";
    }
}

Формат результата

Пример возвращаемого массива:

[
    '/' => [
        'index.php',
        'config.ini'
    ],
    '/subdir' => [
        'subdir/file1.txt',
        'subdir/image.jpg'
    ],
    '/subdir/nested' => [
        'subdir/nested/script.php'
    ]
]

Функция dirToArrayFlat2

Альтернативная версия dirToArrayFlat с плоской структурой и особой сортировкой.

Сигнатура

function dirToArrayFlat2(string $scanDir, string $mask = '*.*', array $exclude = []): array

Ключевые особенности

Возвращает простой массив относительных путей вместо группировки по каталогам
Сортировка выполняется по именам файлов (без учета путей)

Отличия от dirToArrayFlat

dirToArrayFlat	dirToArrayFlat2
Группирует по каталогам	Плоская структура
Сортировка внутри каталогов	Общая сортировка по именам файлов
Возвращает ассоциативный массив	Возвращает простой массив

Формат результата

Пример возвращаемого массива:

[
    'docs/file1.txt',
    'images/photo1.jpg',
    'images/photo2.jpg',
    'logs/error_20230101.log',
    'logs/error_20230102.log'
]

Примеры использования

// Получить все изображения, отсортированные по именам
$images = dirToArrayFlat2('/var/www/images', '*.{jpg,png}');

// Работа с файлами, имеющими временные метки
$logs = dirToArrayFlat2('/var/log', '*.log');
// Новые файлы (с большими временными метками) будут в конце массива
$latestLog = end($logs);

Функция findFile

Поиск файла в нескольких возможных каталогах с возвратом первого найденного.

Сигнатура

function findFile(string $file, array $dirs): string|false

Аргументы

string $file: Имя искомого файла (может содержать относительный путь)
array $dirs: Массив каталогов для поиска (должны быть абсолютными путями)

Возвращаемое значение

Полный абсолютный путь к файлу (string) или false, если файл не найден ни в одном каталоге.

Примеры использования

// Поиск языкового файла
$langFile = findFile('ru.json', [
    '/var/www/app/lang',
    '/usr/local/share/lang',
    './lang'
]);

// Поиск с fallback каталогами
$template = findFile('footer.tpl', [
    '/var/www/templates/custom',
    '/var/www/templates/default' 
]) or die('Template not found');

Особенности

Проверяет каталоги в порядке их указания в массиве
Использует безопасную проверку через checkRealFile()
Поддерживает относительные пути в имени файла
Возвращает абсолютный путь к найденному файлу

Типичные сценарии использования

Поиск конфигурационных файлов в нескольких расположениях
Реализация системы тем/шаблонов с fallback
Загрузка ресурсов из разных возможных каталогов
Поиск одноименных модулей в нескольких директориях

Функция getContentFile

Изолированное подключение PHP-файла с захватом вывода.

Сигнатура

function getContentFile(string $fn): string

Аргументы

string $fn: Абсолютный путь к PHP-файлу, который требуется подключить

Возвращаемое значение

Строка (string) с содержимым, которое сгенерировал подключенный файл.

Если файл не существует, возвращается пустая строка.

Примеры использования

// Подключение шаблона
$header = getContentFile(__DIR__ . '/templates/header.php');
echo $header;

Функция getExtension

Универсальная функция для работы с расширениями файлов.

Сигнатура

function getExtension(string $file, array $allowExt = []): string|bool

Аргументы

string $file: Имя файла или путь к файлу. Может содержать путь (например: '/path/to/file.txt')
array $allowExt: Массив разрешенных расширений (без точки). Например: ['jpg', 'png', 'gif']

Возвращаемое значение

Может возвращать два типа значений:

string: расширение файла в нижнем регистре (если $allowExt не указан)
bool: true если расширение в списке разрешенных, false если нет (если $allowExt указан)

Примеры использования

// Получение расширения
echo getExtension('archive.tar.gz'); // 'gz'

// Проверка расширения
if (getExtension($uploadedFile, ['jpg', 'jpeg', 'png'])) {
    // файл имеет допустимое расширение
}

// Фильтрация файлов по расширению
$images = array_filter($files, function($file) {
    return getExtension($file, ['jpg', 'png', 'gif']);
});

Особенности

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

Функции файлов Albireo CMS

Функция checkRealFile

Сигнатура

Аргументы

Возвращаемое значение

Алгоритм работы

Примеры использования

Особенности безопасности

Рекомендации

Функция checkUrlAsRealFile

Сигнатура

Аргументы

Возвращаемое значение

Алгоритм работы

Примеры использования

Рекомендации

Функция contentFile

Сигнатура

Аргументы

Возвращаемое значение

Алгоритм работы

Примеры использования

Функция copyDir

Сигнатура

Аргументы

Примеры использования

Обработка ошибок

Функция deleteDir

Сигнатура

Аргументы

Возвращаемое значение

Примеры использования

Обработка ошибок

Функция dirToArray

Сигнатура

Аргументы

Возвращаемое значение

Формат результата

Примеры использования

Функция dirToArrayFlat

Сигнатура

Аргументы

Возвращаемое значение

Особенности работы

Примеры использования

Формат результата

Функция dirToArrayFlat2

Сигнатура

Ключевые особенности

Отличия от dirToArrayFlat

Формат результата

Примеры использования

Рекомендации

Функция findFile

Сигнатура

Аргументы

Возвращаемое значение

Примеры использования

Особенности

Типичные сценарии использования

Функция getContentFile

Сигнатура

Аргументы

Возвращаемое значение

Примеры использования

Функция getExtension

Сигнатура

Аргументы

Возвращаемое значение

Примеры использования

Особенности

No description 😟...

No description 😟...

No description 😟...