babaev-an / ANB PHP COMPONENTS PACK

classes/File.md

Класс File

Пространство имён: goodboyalex\php_components_pack
Полное имя класса: goodboyalex\php_components_pack\File
Тип: финальный класс
Версия: 1.0.3
Доступно с: 1.0.21

Описание

Класс предоставляет универсальный функционал работы с файлами и директориями, включая:

  • поиск файлов по шаблону;
  • извлечение частей имени файла;
  • работу с путями;
  • удаление директорий;
  • проверку существования и прав доступа;
  • получение и форматирование размера файлов;
  • ротацию файлов.

Автор

  • Имя: Александр Бабаев
  • Email: contact_with_us@babaev-an.ru

Метаданные

  • PSR‑4: goodboyalex/php_components_pack
  • Модификатор класса: final
  • Ключевые особенности:
    • все методы статические;
    • использование констант для локализации сообщений;
    • возврат объектов ActionState для детального контроля операций.

Константы

REMOVE_DIRECTORY_ERROR_MESSAGES

  • Тип: array
  • Описание: массив сообщений об ошибках при удалении директории.

FILE_SIZE_ERROR_MESSAGES

  • Тип: array
  • Описание: массив сообщений об ошибках при получении размера файла.

FILE_SIZE_UNITS

  • Тип: array
  • Описание: массив локализации размеров файлов (единицы измерения: Б, КБ, МБ и т.д.).

Методы

findFiles()

public static function findFiles(string $dir, string $pattern = '*.php'): false|array

Описание:
Получает список файлов в директории и поддиректориях по заданному шаблону.

Параметры:

  • $dir (string) — родительская директория.
  • $pattern (string) — шаблон имени файла (по умолчанию *.php).

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

  • array — список файлов;
  • false — в случае ошибки.

extractFileNameWithoutExtension()

public static function extractFileNameWithoutExtension(string $fileName): string

Описание:
Извлекает имя файла без пути и расширения.

Параметр:

  • $fileName (string) — полное имя файла с путём.

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

  • string — имя файла без пути и расширения.

extractFileName()

public static function extractFileName(string $fileName): string

Описание:
Извлекает имя файла без пути, но с расширением.

Параметр:

  • $fileName (string) — полное имя файла с путём.

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

  • string — имя файла без пути, но с расширением.

extractFileExtension()

public static function extractFileExtension(string $fileName): string

Описание:
Извлекает расширение файла.

Параметр:

  • $fileName (string) — имя файла с путём.

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

  • string — расширение файла (без точки).

getRelativePath()

public static function getRelativePath(string $fullPath, string $basePath): false|string

Описание:
Получает относительный путь к файлу относительно заданной папки.

Параметры:

  • $fullPath (string) — полный путь к файлу.
  • $basePath (string) — базовый путь, который нужно вырезать.

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

  • string — относительный путь;
  • false — в случае ошибки.

removeDir()

public static function removeDir(
    string $directory,
    array $errorMessages = self::REMOVE_DIRECTORY_ERROR_MESSAGES
): \goodboyalex\php_components_pack\classes\ActionState

Описание:
Удаляет директорию вместе со всеми файлами и поддиректориями.

Параметры:

  • $directory (string) — полный путь к директории.
  • $errorMessages (array) — сообщения об ошибках (по умолчанию — константа REMOVE_DIRECTORY_ERROR_MESSAGES).

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

  • ActionState — результат операции (содержит статус и сообщения).

directoryExists()

public static function directoryExists(
    string $directory,
    bool $checkReadAccess = true,
    bool $checkWriteAccess = false
): bool

Описание:
Проверяет существование директории и права доступа.

Параметры:

  • $directory (string) — путь к директории.
  • $checkReadAccess (bool) — проверять доступ на чтение (по умолчанию true).
  • $checkWriteAccess (bool) — проверять доступ на запись (по умолчанию false).

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

  • bool — true, если директория существует и доступны нужные права; иначе false.

fileSize()

public static function fileSize(
    string $filename,
    array $errorLocalization = self::FILE_SIZE_ERROR_MESSAGES
): \goodboyalex\php_components_pack\classes\ActionState

Описание:
Получает размер файла в байтах.

Параметры:

  • $filename (string) — имя файла.
  • $errorLocalization (array) — сообщения об ошибках (по умолчанию — константа FILE_SIZE_ERROR_MESSAGES).

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

  • ActionState — результат операции (содержит размер файла или ошибки).

fileSizeToString()

public static function fileSizeToString(
    int $fileSize,
    array $fileSizeUnits = self::FILE_SIZE_UNITS,
    string $decimalSeparator = ','
): string

Описание:
Преобразует размер файла в байтах в читаемое строковое представление (например, «1.46 КБ»).

Параметры:

  • $fileSize (int) — размер файла в байтах.
  • $fileSizeUnits (array) — локализованные единицы измерения (по умолчанию — константа FILE_SIZE_UNITS).
  • $decimalSeparator (string) — разделитель десятичной части (по умолчанию запятая).

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

  • string — форматированный размер файла.

rotateFile()

public static function rotateFile(string $fileName, int $maxFiles = 0): void

Описание:
Выполняет ротацию файла (создание резервных копий с нумерацией).

Параметры:

  • $fileName (string) — имя файла.
  • $maxFiles (int) — максимальное число резервных копий (по умолчанию 0 — без ограничений).

Возвращаемое значение:
Не возвращает значение (void).

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

Пример 1: Поиск PHP‑файлов

$files = File::findFiles('/var/www/project', '*.php');
if ($files !== false) {
    foreach ($files as $file) {
        echo $file . PHP_EOL;
    }
}

Пример 2: Извлечение имени файла

$name = File::extractFileName('/var/www/project/index.php');
echo $name; // Выведет: index.php

Пример 3: Получение относительного пути

$relative = File::getRelativePath('/var/www/project/src/file.php', '/var/www/project');
echo $relative; // Выведет: src/file.php

Пример 4: Удаление директории

$result = File::removeDir('/var/www/temp');
if ($result->isSuccess()) {
    echo 'Директория удалена успешно';
} else {
    print_r($result->getMessages());
}

Пример 5: Форматирование размера файла

$size = 1500;
$formatted = File::fileSizeToString($size);
echo $formatted; // Выведет: 1,46 КБ

Примечания

  1. Обработка ошибок:

    • Методы, возвращающие ActionState, позволяют детально анализировать ошибки через $result->getMessages().
    • Для методов с возвратом false проверяйте результат перед использованием.

  2. Безопасность операций:

    • Перед удалением директории (removeDir()) всегда проверяйте права доступа и наличие критически важных данных.
    • При ротации файлов (rotateFile()) убедитесь, что $maxFiles задан корректно — слишком большое значение может привести к избыточному расходу дискового пространства.

  3. Локализация:

    • Константы FILE_SIZE_UNITS, FILE_SIZE_ERROR_MESSAGES и REMOVE_DIRECTORY_ERROR_MESSAGES позволяют адаптировать сообщения под разные языки. Для кастомизации:
      • создайте свой массив сообщений;
      • передайте его в соответствующий параметр метода.

  4. Ограничения:

    • Метод findFiles() не поддерживает рекурсию глубже 10 уровней (защита от переполнения стека).
    • fileSizeToString() корректно работает с файлами до 1 ЭБ (10²⁴ Б).
    • Ротация файлов (rotateFile()) не поддерживает сжатие резервных копий.

Рекомендации по использованию

  1. Для поиска файлов
    • Используйте точные шаблоны (*.log, config*.php), чтобы сократить время выполнения.
    • Для больших директорий рассмотрите постраничную обработку результатов.
  2. Для работы с путями
    • Всегда нормализуйте пути перед передачей в методы (например, через realpath()).
    • Избегайте жёстких путей — используйте константы или конфигурационные файлы.
  3. Для удаления директорий
    • Предварительно выводите список удаляемых файлов для подтверждения.
    • журналируйте все операции удаления для аудита.
  4. Для форматирования размеров
    • Настройте FILE_SIZE_UNITS под локаль пользователя (например, «КБ» → «KB»).
    • Для финансовых отчётов используйте $decimalSeparator = '.' для соответствия стандартам.
  5. Для ротации файлов
    • Комбинируйте с fileSize() для ограничения ротации по размеру.
    • Используйте $maxFiles > 0 для автоматического управления количеством резервных копий.

Типичные сценарии применения

  1. Очистка временных файлов

    if (File::directoryExists('/tmp/cache', true, true))
    File::removeDir('/tmp/cache');

  2. Генерация отчётов

    $size = File::fileSize('/var/log/app.log')->getValue();
echo 'Размер лога: ' . File::fileSizeToString($size, [], '.');

  3. Резервное копирование

    File::rotateFile('/etc/nginx/nginx.conf', 5); // Сохраняет 5 последних версий

  4. Анализ структуры проекта

    $phpFiles = File::findFiles('/src', '*.php');
echo 'Найдено PHP‑файлов: ' . count($phpFiles);

На главную | Содержание

Назад