Merge pull request #6 from ElForastero/develop

Release 2.0.0

.gitignore

@@ -1 +1,3 @@
-.idea/
+.idea/
+vendor
+.php_cs.cache

CHANGELOG.md

@@ -0,0 +1,15 @@
+## Release notes
+
+## [v2.0.0](https://github.com/elforastero/transliterate/releases/tag/2.0.0)
+
+## Added
+- Added Package Discovery support
+- Added configuration file transliterate.php
+- Added ability to define custom transliteration maps
+- Added ability to define transformers
+- Added optional removing accents using ICU
+- Added tests
+
+## Removed
+- Removed all default text transformations
+- Removed config option from Transliteration::make

Dockerfile

@@ -0,0 +1,8 @@
+FROM php:7.1
+
+RUN apt-get update && \
+    apt-get install -y git zip unzip && \
+    php -r "readfile('http://getcomposer.org/installer');" | php -- --install-dir=/usr/bin/ --filename=composer && \
+    apt-get -y autoremove && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

README.md

@@ -1,69 +1,139 @@
-# Transliterate
-Небольшой пакет для транслитерации кирилицы :poop:
+## Transliterate
 
-### Дисклеймер
->Работать - работает. Сорян, если что не так.
+![GitHub](https://img.shields.io/github/license/mashape/apistatus.svg)
+![GitHub release](https://img.shields.io/github/release/elforastero/transliterate.svg)
+![Packagist](https://img.shields.io/packagist/dt/elforastero/transliterate.svg)
 
-Умеет:
-* строку в url ```['type' => 'url']```
-* строку в имя файла ```['type' => 'filename']```
+Небольшой пакет для транслитерации кириллицы с возможностью создания своих собственных карт транслитерации.
 
-### Установка:
+![Code example](example.png)
+
+- [Предустановленные карты](#Предустановленные-карты)
+- [Системные требования](#Системные-требования)
+- [Установка](#Установка)
+- [Конфигурация](#Конфигурация)
+- [Использование](#Использование)
+- [Создание карт транслитерации](#Создание-карт-транслитерации)
+- [Создание трансформеров](#Создание-трансформеров)
+
+## Предустановленные карты
+
+- Русский
+    - Дефолтная
+    - ГОСТ 7.79 2000
+- Украинский
+    - Национальная
+
+
+## Системные требования
+- laravel >= 5.6
+- ext-intl
+
+## Установка
 ```
-composer require elforastero/transliterate
+> composer require elforastero/transliterate
+```
+
+Laravel начиная с версии *5.5* не нуждается в дополнительной конфигурации благодаря механизму Package Discovery.
+
+Если вы не используте Package Discovery, необходимо зарегистрировать `Service Provider`, добавив его в массив `providers`, конфигурационного файла `app.php`.
+
+```php
+ElForastero\Transliterate\ServiceProvider::class,
 ```
 
+Если вы хотите использовать алиас, добавьте его в массив `facades` в `app.php`.
+
+Рекомендую в качестве алиаса использовать `Transliterate`, чтобы избежать конфликтов с Transliterator классом из расширения Intl.
+
 ```php
-//config/app.php
+'Transliterate' => ElForastero\Transliterate\Facade::class,
+```
 
-'providers' => [
-  //...
-  ElForastero\Transliterate\TransliterationServiceProvider::class,
-],
+## Конфигурация
 
-'aliases' => [
-  //...
-  'Transliterate' => ElForastero\Transliterate\TransliterationFacade::class,
-],
+Для копирования конфига `transliterate.php` в директорию `configs` выполните
+
+```
+> php artisan vendor:publish --provider="ElForastero\Transliterate\ServiceProvider"
 ```
 
-### Использование:
+## Использование
+
+Вы можете использовать фасад для транслитерации строк.
+
 ```php
 use Transliterate;
-...
 
-$string = '\'"#^_^ Если б мишки были пчёлами, то они бы нипочем, никогда и не подумали так высо́ко строить дом.';
+Transliterate::make('Двадцать тысяч льё под водой');
+// "Dvadcat tisyach lyo pod vodoy"
+```
 
-$string = Transliterate::make($string);
-// Esli b mishki bili pchyolami to oni bi nipochem nikogda i ne podumali tak visoko stroit dom
+Альтернативная карта транслитерации может быть передана вторым параметром.
 
-$string = Transliterate::make($string, ['type' => 'url', 'lowercase' => true]);
-// esli-b-mishki-bili-pchyolami-to-oni-bi-nipochem-nikogda-i-ne-podumali-tak-visoko-stroit-dom
+```php
+use ElForastero\Transliterate\Transliterator;
+
+$transliterator = new Transliterator(Map::LANG_RU, Map::GOST_7_79_2000);
+$transliterator->make('Двадцать тысяч льё под водой');
+// "Dvadcat` ty'syach l`yo pod vodoj"
+```
 
-$string = Transliterate::make($string, ['type' => 'filename', 'lowercase' => true]);
-// esli_b_mishki_bili_pchyolami_to_oni_bi_nipochem_nikogda_i_ne_podumali_tak_visoko_stroit_dom
+## Генерация URL
 
-$string = Transliterate::make($string, ['type' => 'url', 'lowercase' => true, 'map' => 'gost2000']);
-// esli-b-mishki-by'li-pchyolami-to-oni-by'-nipochem-nikogda-i-ne-podumali-tak-vy'soko-stroit`-dom
+Метод `slugify` генерирует URL, убирая из строки все знаки препинания и заменяя пробелы на "-".
+
+```php
+Transliterate::slugify('Съешь еще этих мягких французских булок, да выпей чаю!');
+// sesh-eshhe-etih-myagkih-francuzskih-bulok-da-vipey-chayu
 ```
 
-### Доступные параметры:
+## Создание карт транслитерации
+
+Каждая карта представляет собой ассоциативный массив с символами подлежащими замене в качестве ключей, и значениями на которые они будут заменены.
+
+Карта создается в виде отдельного файла с возвращаемым массивом:
+
 ```php
-[
-  'type' => 'url',
-  // 'url', 'filename' или 'text'. Первым заменяем пробелы на '-', вторым на '_'.
-  // По дефолту 'text', который ничего не заменяет.
-
-  'lowercase' => true, // Преобразовать строку в нижний регистр.
-  'map' => 'gost2000', // Транслитерация по ГОСТ 7.79-2000.
+// /resources/maps/uk/ukraine.php
+
+return [
+    'ї' => 'i',
+    'і' => 'i',
+    'є' => 'ie',
+];
+```
+
+Добавьте путь к созданной карте в массив `maps`, конфига `transliterate.php`:
+
+```php
+'uk' => [
+    'ukraine' => dirname(__DIR__) . '/resources/maps/uk/ukraine.php',
 ]
 ```
 
-### Дополнительно
+После этого карту можно использовать.
+
 ```php
-// Получить карту транслитерации, используемую по-умолчанию
-Transliteration::getDefaultMap();
+$transliterator = new Transliterator('uk', 'ukraine');
+$transliterator->make('Ваша транслітерація');
+```
+
+## Создание трансформеров
+
+Трансформеры - функции которые будут автоматически применены к результату транслитерации. Полезно если вам необходимо каждый раз производить одни и те же действия с транслитерируемой строкой. Регистрируется трансформер в массиве `transformers`.
+
+Например, можно автоматечески убирать конечные пробелы.
+
+```php
+ElForastero\Transliterate\Transformer::register(\Closure::fromCallable('trim')),
+```
+
+Или дополнительно приводить строки к нижнему регистру.
 
-// Карта по ГОСТ 2000
-Transliteration::getGost2000Map();
+```php
+ElForastero\Transliterate\Transformer::register(\Closure::fromCallable('trim')),
+ElForastero\Transliterate\Transformer::register(\Closure::fromCallable('strtolower')),
 ```
+
+> Будьте внимательны, поскольку трансформеры применяются при каждом вызове `Transliterator::make`.

composer.json

@@ -1,20 +1,53 @@
 {
-    "name": "elforastero/transliterate",
-    "version": "1.1.0",
-    "description": "Transliteration package for laravel 5",
-    "license": "MIT",
-    "authors": [
-        {
-            "name": "Eugene Dzhumak",
-            "email": "[email protected]"
-        }
-    ],
-    "autoload": {
-        "psr-4": {
-            "ElForastero\\Transliterate\\": "src/"
-        }
+  "name": "elforastero/transliterate",
+  "description": "Transliteration package for laravel 5",
+  "version": "2.0.0",
+  "type": "library",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Eugene Dzhumak",
+      "email": "[email protected]"
+    }
+  ],
+  "autoload": {
+    "psr-4": {
+      "ElForastero\\Transliterate\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "ElForastero\\Transliterate\\Tests\\": "tests/"
+    }
+  },
+  "require": {
+    "php": ">=7.1",
+    "ext-intl": "*",
+    "illuminate/support": "~5"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^7.4",
+    "orchestra/testbench": "^3.7",
+    "friendsofphp/php-cs-fixer": "^2.13",
+    "brainmaestro/composer-git-hooks": "^2.6"
+  },
+  "extra": {
+    "laravel": {
+      "providers": [
+        "ElForastero\\Transliterate\\ServiceProvider"
+      ],
+      "aliases": {
+        "Transliterate": "ElForastero\\Transliterate\\Facade"
+      }
     },
-    "require": {
-        "illuminate/support": "~5"
+    "hooks": {
+      "pre-commit": [
+        "php-cs-fixer fix ."
+      ]
     }
+  },
+  "scripts": {
+    "test": "phpunit",
+    "check-style": "php-cs-fixer fix src/ --dry-run --diff"
+  }
 }