Тема: Работа с пакетами (Composer)
Цель:
-
Научиться создавать свои пакеты и подключать их как Composer-зависимости.
-
Описание/Пошаговая инструкция выполнения домашнего задания:
-
Необходимо создать свой пакет. В pull-request прислать composer.json, в котором приводится пример подключения Вашего пакета.
Критерии оценки:
Пакет должен ставиться при помощи composer require package-name Пакет должен отвечать PSR-4 Пакет может подключаться в Composer либо с packagist, либо из GitHub 4 балла за соответствие PSR-4 3 балла успешное подключение к пакету 3 балла за корректность содержимого пакета
Рекомендуем сдать до: 16.02.2022
Будем делать все по этому гайду:
“Ваш первый composer пакет” https://ctrlv.me/you-first-composer-package/
Только напишем что-то полезнее HelloWorld, что можно реально использовать в проектах ….
Давайте это будет … ТРАНСЛИТЕРАТОР: пакет, который будет транслитерировать текст на указанном языке, в его эквивалент на английском языке
Структура нашего будущего пакета
-
composer-package/ — корневая папка для пакета;
-
composer-package/examples/ — папка, в которой будут храниться примеры использования нашей библиотеки;
-
composer-package/examples/example.php — файл, который демонстрирует функциональность;
-
-
composer-package/src/ — папка, где будет храниться наша библиотека;
-
composer-package/src/Transliterator.php — тот самый код, который мы хотим распространять через composer;
-
-
composer.json — текстовый файл, в котором описаны все дополнительные библиотеки, которые мы можем использовать в нашем пакете. Так-же в этом файле хранится информация о нашем пакете;
-
README.md — Здесь хранится вербальное описание нашей библиотеки, которое выводится на GITHUB
Предварительные шаги
Ставим пакет “intl”
нужен для работы функций транлитерации: в php.ini правим:
Ставим Composer
В корне проекта запускаем:
composer install
Шаг 1: Создайте файл composer.json
Как упоминалось выше, composer.json — текстовый файл, в котором описаны все сторонние библиотеки, от которых зависит наш проект (пакет). Создать файл можно двумя способами:
Создание при помощи консольной команды
Файл composer.json создается автоматически при вводе консольной команды composer init в папке проекта. После ввода команды будет предложено ввести информацию об основных характеристиках пакета, таких как название и описание.
Создание composer.json вручную
Для создания файла вручную следует создать новый файл, назвать его composer.json и заполнить следующим содержимым.
{
"name": "nujensait/translit",
"description": "Strings transliterator",
"authors": [
{
"name": "Mishaikon",
"email": "mishaikon@gmail.com"
}
],
"require": {
"php": ">=7.3.9"
},
"require-dev": {
},
"minimum-stability": "dev",
"autoload": {
"psr-4": {
"nujensait\Translit\": "src/"
}
}
}
Обратите внимание на секцию autoload, это один из важнейших моментов здесь, вокруг которого и строится магия. В ней находится указание того, что все файлы с пространством имен ctrlvHelloWorld внутри папки src должны быть загружены автоматически в проект.
Шаг 2: Написание библиотеки
Теперь, когда у нас есть подключенный composer к нашему проекту, можно приступать к написании самой библиотеки. Для этого в файле Translit.php, который находится в папке src напишем вот такой простой класс:
<?php
namespace nujensaitTranslit;
/**
* Class Translit
* transliterate string to it's english equivalent
* @author Mikhail <mishaikon@gmail.com>
* @see usage example here: ./examples/example.php
*/
class Translit
{
/**
* Transform text to translit
* @see #SPUTNIKSITE-2863
* @param string $text
* @param string $charset
* @return string
*/
public function transliterateText($text, $charset = 'Russian-Latin/BGN')
{
switch($charset) {
case 'big5':
$transliterator = 'Hex-Any;Simplified-Traditional';
break;
case 'serbian-latin':
/**
* @see #SPUTNIKSITE-2115
* Транслитератор два символа - ћ, Ћ - каждый превращает в 2 символа вместо ć, Ć
* Imagick затем некрасиво накладывает это на изображение, поэтому здесь это исправляем
*/
$cyr = ['ћ', 'Ћ', 'я', 'Я'];
$lat = ['ć','Ć', 'ja', 'JA'];
$text = str_replace($cyr, $lat, $text);
$transliterator = 'Serbian-Latin/BGN';
break;
case 'uzbek-latin':
$transliterator = 'uz_Cyrl-uz_Latn';
break;
default:
$locales = $this->getLocales();
if(in_array($charset, $locales)) {
$transliterator = $charset;
} else {
throw new Exception("Error: locale $charset is not found/supported by transliterator.");
}
}
if($transliterator && $text && function_exists('transliterator_transliterate')) {
$text = transliterator_transliterate($transliterator, $text);
} else {
throw new Exception("Error: transliterator_transliterate is not allowed; enable it's usage by setting intl library in php.ini: extension=intl");
}
return $text;
}
/**
* Allowed locales list
*/
public function getLocales()
{
$list = transliterator_list_ids();
natcasesort ($list);
return $list;
}
}
Шаг 3: Пишем пример использования пакета
Наш пакет готов. Писать пример не обязательно, но крайне желательно
Для начала, давайте выполним консольную команду composer install, которая создаст (обновит) папку vendor в нашем текущем проекте. Это нужно сделать для того, чтобы мы могли подключить автозагрузку composer и пользоваться пространством имен внутри файла examples/example.php.
Следующим шагом будет написание самого файла с примером examples/example.php, который выглядит так, как показано ниже:
<?php
/**
* Translit class usage example
*/
require __DIR__ . '/../vendor/autoload.php';
use nujensaitTranslitTranslit;
$transl = new Translit();
// OK: Known locale
$str = "Текст на русском";
$str = $transl->transliterateText($str, 'Russian-Latin/BGN');
echo $str;
echo "nn";
// Error: Unkonwn locale
$str = "Текст на русском";
try {
$str = $transl->transliterateText($str, 'asdfasfas');
echo $str;
} catch(Exception $e) {
echo $e->getMessage();
}
echo "nn";
Остается только проверить, чтобы все работало так, как мы это и задумали, для этого выполним консольную команду php examples/example.php, результатом работы которой будет вывод приветствия на экран.
php ./examples/example.php
Tekst na russkom Error: locale asdfasfas is not found/supported by transliterator.
Шаг 4: Публикуем на github
Прежде чем опубликовать проект на github, давайте выполним конфигурацию проекта, а именно:
-
Создадим файл .gitignore, в который пропишем какие файлы не нужно отслеживать, чтобы лишнее не попало в репозиторий
-
Напишем описание проекта в файле README.md
Файл .gitigonore
/.idea /vendor /composer.lock
Файл README.md
# What is it Texts/strings chars transliterator # Task source Experimental task on [Otus PHP professional course](https://fas.st/wRyRs), Lesson 4: "Composer usage". # Author Mikhail Ikonnikov <mishaikon@gmail.com> # Usage examples See in file: ./examples/example.php
Теперь, когда все готово, можем загрузить наш код на github.
Публикация пакета
Загрузка на github
-
Заходим на github, создаем новый репозиторий
-
Инициализируем git внутри своего проекта, добавляем файлы, коммитим и пушим на github при помощи команд:
Создаем новый репозитарий, в своем профиле:
Указываем данные о нем:
Коммитим все сюда
cd lesson4_composer git clone https://github.com/nujensait/translit.git git add * git commit -m "Otus php pro, Lesson 4: Composer / Tranliterator class" git push
Проверяем коммит
Все запушилось сюда:
https://github.com/nujensait/translit
В результате наша библиотека будет опубликована на github, и все что нам осталось сделать — добавить ее в сервис packagist.
Загрузка в Packagist
Регимся/логинимся
Переходим сюда: https://packagist.org/login/
Сабмитим наш пакет
Указываем полный путь к пакету:
https://github.com/nujensait/translit
Можно юзать пакет через:
composer require nujensait/translit
Нет комментариев