Тема: Работа с пакетами (Composer)

Цель:

  • Научиться создавать свои пакеты и подключать их как Composer-зависимости.

  • Описание/Пошаговая инструкция выполнения домашнего задания:

  • Необходимо создать свой пакет. В pull-request прислать composer.json, в котором приводится пример подключения Вашего пакета.

Критерии оценки:

Пакет должен ставиться при помощи composer require package-name Пакет должен отвечать PSR-4 Пакет может подключаться в Composer либо с packagist, либо из GitHub 4 балла за соответствие PSR-4 3 балла успешное подключение к пакету 3 балла за корректность содержимого пакета

Рекомендуем сдать до: 16.02.2022


(warning) Будем делать все по этому гайду:

“Ваш первый 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

Tags

Нет комментариев

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Этот сайт использует Akismet для борьбы со спамом. Узнайте, как обрабатываются ваши данные комментариев.