movephp/classloader

Extended Autoloader for Movephp framework

, _(*1)

Расширенный Autoloader для фреймворка Movephp

Это механизм для создания карты классов приложения. Он сканирует указанные каталоги в поисках *.php файлов и составляет список всех найденных классов (в т.ч. абстрактных, а также интерфейсов и трейтов). Для каждого класса также определяется пространство имён, родительский класс, используемые интерфейсы и трейты, классы-потомки., _(*2)

Полученный массив данных можно использовать как для обычной автозагрузки, так и для поиска и анализа карты классов., _(*3)

Например, можно найти все классы, имеющие в дереве родительских классов указанный, или можно найти все классы, использующие определённый трейт и т.д., _(*4)

Это позволяет быстро анализировать код приложения и выполнять препроцессинг., _(*5)

Оглавление

• Установка
• Быстрый старт
• Автозагрузчик
• Обновление карты
• Настройки сканирования
• Особые случаи
  • Composer-пакеты
  • PHPUnit и библиотека Composer
  • Классы с возможными ошибками
• Поиск и анализ классов
• API Reference
  • Movephp\ClassLoader\Autoload
    • Конструктор
    • Методы
  • Movephp\ClassLoader\Map\Map
    • Конструктор
    • Методы
  • Movephp\ClassLoader\Map\Item
    • Методы
• TODO

Установка

Рекомендуемый способ установки - с использованием Composer. Добавьте следующую инструкцию в ваш composer.json файл:, _(*6)

"require": {
    "movephp/classloader": "~1.0"
}

Быстрый старт

Пример кода для быстрого старта:, _(*7)

include_once('vendor/autoload.php');
use Movephp\ClassLoader\{Autoload, Map};
$autoload = new Autoload(
    new Map\Map()
);
$autoload->setScanPaths(__DIR__ . '/src', __DIR__ . '/vendor');
$autoload->makeMap();
var_dump($autoload->map()->classes());

Автозагрузчик

Зарегистрировать функцию автозагрузки классов из составленной карты можно методом $autoload->register()., _(*8)

Для использования данной библиотеки в качестве автозагрузчика классов рекомендуется использовать кеширование (PSR-6)., _(*9)

$cachePool = new Symfony\Component\Cache\Adapter\FilesystemAdapter();
$autoload = new Autoload(
    new Map\Map(),
    $cachePool
);
$autoload->setScanPaths(__DIR__ . '/src', __DIR__ . '/vendor');
$autoload->makeMap();
$autoload->register();

При использовании кеширования карта классов будет сформирована только один раз, а при следующих обращениях данные будут быстро восстановлены из кеша., _(*10)

По-умолчанию библиотека использует ключ movephp_classloader для получения CacheItem из переданного CachePool. Для предотвращения возможных коллизий третьим аргументом в конструктор класса Autoload можно передать пространство имён для ключа CacheItem: $autoload = new Autoload($map, $cachePool, 'mynamespace') - в этом случае для получения CacheItem будет использован ключ mynamespace_movephp_classloader., _(*11)

Обновление карты

В dev-окружении или при работе над проектом может потребоваться обновить карту классов:, _(*12)

$cachePool = new Symfony\Component\Cache\Adapter\FilesystemAdapter();
$autoload = new Autoload(
    new Map\Map(),
    $cachePool
);
$autoload->setScanPaths(__DIR__ . '/src', __DIR__ . '/vendor');
$autoload->makeMap();
if (...some_сondition_here...) {
    $autoload->updateMap();
}
$autoload->register();

Другой вариант, более медленный, - полностью сбросить кеш и сформировать карту заново:, _(*13)

$cachePool = new Symfony\Component\Cache\Adapter\FilesystemAdapter();
if (...some_сondition_here...) {
    $cachePool->clear();
}
$autoload = new Autoload(
    new Map\Map(),
    $cachePool
);
$autoload->setScanPaths(__DIR__ . '/src', __DIR__ . '/vendor');
$autoload->makeMap();
$autoload->register();

Настройки сканирования

Помимо метода $autoload->setScanPaths() для указания того, какие файлы/каталоги должны быть просканированы, существует два дополнительных метода:, _(*14)

• $autoload->setExcludingPaths(string ...$excludePaths) - исключает указанные файлы и каталоги (и всё их содержимое) из процесса сканирования. Имеет смысл использовать эту возможность для каталогов с тестами.
• $autoload->setOverridePaths(string ...$overridePaths) - в случае, если при сканировании проекта будет обнаружено несколько классов с одинаковым именем (включая пространство имён), возникнет ошибка. Однако данный метод позволяет указать файлы/каталоги, в которых могут содержаться классы, заменяющие одноимённые классы в других сканируемых файлах. В этом случае не будет ошибки, а в карту попадут классы из $overridePaths.

Особые случаи

Composer-пакеты

При сканировании файлов проекта особое внимание уделяются файлам composer.json. При обнаружении такого файла, если он содержит директиву autoload, сканироваться будут только каталоги и файлы, описанные в ней., _(*15)

Остальные файлы в найденном composer-пакете будут пропущены, т.к., вероятно, нужны там лишь для тестов или просто являются мусором., _(*16)

PHPUnit и библиотека Composer

Класс не будет включён в карту классов и не будет доступен как для автозагрузки, так и для анализа, в следующих случаях:, _(*17)

• Если класс является тестом phpUnit, т.е. если он или один из его родителей унаследован от классов PHPUnit_Framework_TestCase или PHPUnit\Framework\TestCase;
• Если класс является частью библиотеки Composer, т.е. определён в пространстве имён Composer или в любом подпространстве Composer\....

Классы с возможными ошибками

Класс будет включен в карту классов, но не будет доступен для автозагрузки в следующих случаях:, _(*18)

• Если в коде файла с классом встречается оператор exit() (или die()) вне тела класса, т.е. он может быть вызван в момент подключения файла к приложению.
• Если класс унаследован от класса, который не представлен в общей карте классов и не является встроенным в PHP классом. Тоже касается используемых трейтов и интерфейсов.

Такой класс получит особую отметку $item->isSafeInclude() === false, которая означает, что подключение файла с данным классом может привести к ошибке или неожиданному завершению скрипта. Однако класс будет присутствовать в карте классов и будет доступен для анализа., _(*19)

Поиск и анализ классов

Сформированную карту классов - объект Map\Map - можно получить методом $autoload->map(). Также, если вам не нужны функции автозагрузки и кеширования, вы можете сразу напрямую использовать класс Map\Map и его метод scan():, _(*20)

$map = new Map\Map();
$map->scan([__DIR__ . '/src', __DIR__ . '/vendor']);

Метод Map\Map::classes() возвращает полный список всех классов в карте в виде массива объектов Map\Item., _(*21)

С помощью метода Map\Map::find() можно осуществлять поиск среди классов в карте по заданным параметрам. Пример поиска неабстрактных классов, реализующих интерфейс MyNamespace\MyInterface, а также потомков этих классов:, _(*22)

$map->find(Map\Item::TYPE_CLASS, MyNamespace\MyInterface::class);

Метод find() также возвращает массив объектов Map\Item., _(*23)

Объекты Map\Item - элементы карты - имеют много методов-геттеров для получения всевозможной информации о представляемом ими классе., _(*24)

API Reference

Movephp\ClassLoader\Autoload

Основной класс библиотеки. Используется для выполнения функции автозагрузчика на основе карты классов, а также для управления объектом карты и его кешированием., _(*25)

Конструктор

__construct(Movephp\ClassLoader\Map\MapInterface $cleanMap, Psr\Cache\CacheItemPoolInterface $cachePool = null, string $cacheKeyNamespace = '')

Методы

Movephp\ClassLoader\Map\Map

Объект данного класса представляет карту классов и используется для её составления (сканирования файлов проекта) и поиска по ней., _(*26)

Конструктор

__construct(string $itemClass = '')

Методы

Возможные значения аргумента $type метода find(): - Movephp\ClassLoader\Map\ItemInterface::TYPE_CLASS - Movephp\ClassLoader\Map\ItemInterface::TYPE_ABSTRACT - Movephp\ClassLoader\Map\ItemInterface::TYPE_INTERFACE - Movephp\ClassLoader\Map\ItemInterface::TYPE_TRAIT - или любая сумма этих констант (Movephp\ClassLoader\Map\ItemInterface::TYPE_ANY - это сумма их всех)., _(*27)

Movephp\ClassLoader\Map\Item

Объект данного класса представляет один элемент карты: класс, интерфейс или трейт, найденный при сканировании., _(*28)

Методы

TODO

• Сделать возможным использование спец. символов * и ? при указании списка сканируемых и исключаемых из сканирования директорий и файлов;
• Настройка расширений сканируемых файлов (по-умолчанию *.php);
• Избавиться от прямых обращений к функциям файловой системы (использовать Flysystem или аналог).