From 8757ae8a9b085ad5f6be0c809921f42b561f6094 Mon Sep 17 00:00:00 2001 From: vinogradsoft Date: Sun, 15 Oct 2023 02:02:22 +0300 Subject: [PATCH] Created README.md --- README.md | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..877075e --- /dev/null +++ b/README.md @@ -0,0 +1,161 @@ +# Compass + +> Библиотека работает с URL-адресами и с путями к файлам на диске. Compass написана на PHP и предлагает набор методов +> для обработки этих двух типов данных. Она может быть использована в различных приложениях, таких как веб-приложения +> для формирования и обработки путей к файлам или системы управления контентом для создания URL-адресов. + +## Общая информация + +Эта библиотека предназначена для использования в более высокоуровневых PHP-проектах и включает в себя два основных +компонента: для работы с путями к файлам (`\Compass\Path`) и для работы с URL (`\Compass\Url`). Оба эти +компонента представлены отдельными объектами и предлагают набор методов, упрощающих манипуляции с путями и URL-адресами. + +`\Compass\Path` помогает упростить работу с директориями и файлами, позволяя находить и заменять определенные +директории по указанному шаблону, а также проверять наличие директорий в пути и изменять их порядок. Этот компонент +предоставляет возможность быстро и эффективно выполнять различные манипуляции с путями. + +В свою очередь, `\Compass\Url` позволяет работать с URL, предоставляя набор методов для создания, получения и +изменения различных частей URL-адреса. Особенностью этого компонента является то, что он создает URL оптимальным +образом, изменяя только те части адреса, которые требуется изменить, при создании множества URL одного домена. + +Схема показывает какие данные можно получить и модифицировать: + +``` + |---------------------------------------absolute url---------------------------------| + | | + |-----------------base url----------------|------------------relative url------------| + | | | + | authority | path query fragment| + | /‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾\|/‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾\ /‾‾‾‾‾‾‾‾\ /‾‾‾‾‾‾\| + |http://grigor:password@vinograd.soft:8080/path/to/resource.json?query=value#fragment| + \__/ \___/ \_____/ \___________/ \__/ \___/ + scheme user password host port suffix +``` + +Оба компонента работают по схожему принципу, сначала собирая необходимые параметры, а затем применяя их к +результату с помощью специального метода `updateSource()`. + +## Установка + +Предпочтительный способ установки - через [composer](http://getcomposer.org/download/). + +Запустите команду + +``` +php composer require vinogradsoft/compass "^1.0" +``` + +Требуется PHP 8.0 или новее. + +## Компонент URL + +### Быстрый старт + +```php +setScheme('https') + ->setUser('grigor') + ->setPassword('pass@word') + ->setHost('host.ru') + ->setPort('8088') + ->setPath('/user/index') + ->setSuffix('.php') + ->setArrayQuery([ + 'key1' => 'value1', + 'key2' => 'value2' + ])->setFragment('fragment'); + +$url->updateSource(); + +printUrl($url); + +$url = new Url('https://grigor:pass%40word@host.ru:8088/user/index?key1=value1&key2=value2#fragment'); +$url->setSuffix('.php'); +$url->updateSource(); + +printUrl($url); + +function printUrl($url) +{ + echo '

Authority: ', $url->getAuthority(); + echo '
BaseUrl: ', $url->getBaseUrl(); + echo '
RelativeUrl: ', $url->getRelativeUrl(); + echo '
AbsoluteUrl: ', $url; //$url->getSource(); + echo '
'; + + echo '
getScheme: ', $url->getScheme(); + echo '
getUser: ', $url->getUser(); + echo '
getPassword: ', $url->getPassword(); + echo '
getHost: ', $url->getHost(); + echo '
getPort: ', $url->getPort(); + echo '
getPath: ', $url->getPath(); + echo '
getSuffix: ', $url->getSuffix(); + echo '
getQuery: ', $url->getQuery(); + echo '
getFragment: ', $url->getFragment(); +} +``` + +Класс `\Compass\Url` может быть создан путем вызова статического метода `createBlank()` либо созданием нового +объекта оператором `new`. Метод `createBlank` примечателен тем, что в своей работе применяет клонирование своего же +прототипа. У данного метода есть два необязательных параметра: `$isIdnToAscii`, `$updateStrategy` - они определяют, +будет ли происходить преобразование хоста в `punycode`, и какую стратегию обновления/создания URL применять. + +Первый параметр, `$isIdnToAscii` - определяет необходимость преобразования хоста при создании URL. Если он принимает +значение `true`, хост преобразуется, если же `false` - преобразование хоста не происходит. Этот параметр можно изменить +после создания экземпляра класса через метод `setConversionIdnToAscii()` - ему нужно передать новое значение. + +Второй параметр, `$updateStrategy` - определяет стратегию обновления URL или его создания. Он включает в себя выбор +метода создания URL и его составляющих. + +Чтобы создать новый экземпляр класса `\Compass\Url` с помощью оператора `new` необходимо передать один +обязательный параметр - это исходный URL в виде строки. + +После настройки всех параметров для внесения изменений необходимо вызвать метод `updateSource();`. + + +--- + +## Компонент PATH + +### Быстрый старт + +```php +replaceAll([ + '__NAME__' => 'User', + '__NAME2__' => 'Filesystem', +]); +$path->updateSource(); +echo '
', $path; +$path->setAll(['path','to','file.txt']); + +$path->updateSource(); +echo '
', $path; +``` + +Результат вывода: + +``` +/User/UserScanner/FilesystemDriver +path/to/file.txt +``` + +--- + +## Тестировать + +``` php composer tests ```