Parser + Composer

n3o 21.11.2016 21:46 / 21.11.2016 21:47

Всем привет.

У Парсера появился свой репозиторий пакетов: https://pkg.parser.ru

Сделан он на базе стандартного репозитория PHP-пакетов Packagist. Это означает, что теперь пакеты и их зависимости для Парсера можно устанавливать используя стандартный PHP-шный Composer.

Те, кто работал с PHP-проектами, скорее всего знают, что такое Composer, остальные могут ознакомиться с ним на официальном сайте https://getcomposer.org


Как установить Composer.
Для установки Composer, необходимо перейти в корневую директорию проекта (там где лежит или будет лежать composer.json) и выполнить в командной строке:

curl -sS https://getcomposer.org/installer | php

или

wget -qO- https://getcomposer.org/installer | php

или скачать Composer по ссылке: https://getcomposer.org/composer.phar

Более подробно про установку на разных платформах, или о том, как установить Composer глобально, можно почитать по ссылке: https://getcomposer.org/doc/00-intro.md

Чтобы Composer начал устанавливать пакеты для Парсера, ему необходимо сказать о новом репозитории пакетов. Для того, чтобы это сделать, надо, либо в своём composer.json добавить строчки:

"repositories": [
    {"type": "composer", "url": "https://pkg.parser.ru"}
]

либо, добавить репозиторий в глобальные настройки Composer, выполнив команду:

php composer.phar config --global repositories.parser composer https://pkg.parser.ru

или, если Composer установлен глобально:

composer config --global repositories.parser composer https://pkg.parser.ru

После этого Composer будет искать запрашиваемые пакеты в том числе и на https://pkg.parser.ru


Что, на счет автозагрузки классов как в PHP?
Для того, чтобы использовать удобный автозагрузчик классов, необходимо в composer.json своего проекта добавить плагин для Composer:

"require": {
    "parser/autoload": "^1.0"
}

Этот плагин содержит в себе класс автозагрузчика для Парсера, а также автоматически генерирует файл: autoload.p который регистрирует установленные пакеты. После этого достаточно в корневом auto.p своего проекта, написать:

@USE
/path/to/vendor/autoload.p

и в проекте можно использовать установленные пакеты.

Автозагрузка и основные её принципы были заимствованы из Рекомендованных стандартов для PHP (http://www.php-fig.org/psr/), в частности стандарт PSR-0 (уже depricated в php-проектах, но мы его поддерживаем в силу отсутствия в Парсере неймспейсов для классов) и PSR-4.

PSR-0 позволяет нам именовать классы следующим образом:
<Vendor name>_<Namespace(s)>_<Class name>

Например: Als_Config_Reader
Als_Config - это префикс/неймспейс, Reader - это название класса

PSR-4 позволяет нам именовать классы следующим образом:
<Vendor name>/<Namespace(s)/<Class name>

Например: Als/Config/Reader
Als/Config - это префикс/неймспейс, Reader - это название класса

Для регистрации префиксов и неймспейсов в автозагрузке используется секция “autoload”: {} в composer.json
Про неё можно почитать в официальной документации: https://getcomposer.org/doc/04-schema.md#autoload

Сейчас поддерживается: “PSR-0”, “PSR-4” и “files”

“PSR-0”, “PSR-4” - используются для регистрации префиксов/неймспесов в автозагрузчике, подключение файла с классом происходит только когда это необходимо, например, когда мы создаем объект класса.

“files” - используется, чтобы подключать файлы из пакета непосредственно в момент загрузки. Использование можно посмотреть, например в пакете: als/debug

Например, если в composer.json указать:

"require-dev": {
    "als/debug": "^1.0"
}

то, Composer установит пакет als/debug и автоматически подключит его.

Надо учесть, что Composer предназначен для PHP классов, поэтому при регистрации PSR-4 префиксов и неймспейсов надо учитывать, что там в качестве разделителя используются обратный слеш ‘\’. Так же, Composer почему-то требует, чтобы префикс или неймспейс в секции “autoload” заканчивался разделителем, для PSR-0 это подчеркивание ‘_’, для PSR-4 это слэш ‘\’.

Пример: Допустим нам в проекте надо подключить два пакета (als/test1 и als/test2), для примера один из них написан по стандарту PSR-0, второй по стандарту PSR-4.

Первый пакет:

{
    "name": "als/test1",
    "autoload": {
        "psr-0": {
            "Als_Test1_": "src/"
        }
    }
}

Второй пакет:

{
    "name": "als/test2",
    "autoload": {
        "psr-4": {
            "Als\\Test1\\": "src/"
        }
    }
}

В файле composer.json своего проекта, мы пишем:

"require": {
    "als/test1": "^1.0",
    "als/test2": "^1.0"
}

(про версии можно почитать в официальной документации: https://getcomposer.org/doc/articles/versions.md)

И выполняем команду:

php composer.phar install

После этого Composer устанавливает наши зависимости (по-умолчанию в папку /vendor/) и генерирует файл autoload.p

Далее, мы в корневом auto.p своего проекта, подключаем автозагрузчик:

@USE
/vendor/autoload.p

И далее в любом месте своего проекта, мы можем использовать подключенные библиотеки:

$test1[^Als_Test1_MyClass::create[]]
$test2[^Als/Test2/MyClass::create[]]

Как написать свой пакет.
Достаточно в папку со своим пакетом положить файл composer.json с минимальным его содержимым, опубликовать пакет, например, в GitHub и добавить ссылку на репозиторий с пакетов тут: https://pkg.parser.ru/packages/submit


Что, сейчас есть на https://pkg.parser.ru/
В данный момент в репозиторий переносятся классы и библиотеки опубликованные в разделе “Библиотека”
Некоторые из них уже перенесены, например als/sql и als/debug, некоторые готовятся к переносу.

Следующим шагом, будет рефакторинг этих библиотек. Например, вынос какого-то функционала в отдельные пакеты, и подключение их в качестве зависимостей.

Все вопросы про именования классов, автозагрузку, структуру пакетов, как и где autoload ищет файлы, про класс Parser/Autoload можно задавать тут, постараюсь оперативно отвечать.

---