Download the PHP package fi1a/format without Composer

PHP форматирование строковых шаблонов

Пакет предоставляет возможность форматирования строковых шаблонов с использованием функций спецификаторов.

Возможности пакета:

• форматирование строки и числа;
• форматирование даты и времени на русском языке (месяцы и дни недели);
• преобразование специальных символов в HTML-сущности;
• преобразование HTML-сущностей обратно в соответствующие символы;
• форматирование размера памяти;
• форматирование времени;
• склонение слов после числительных;
• форматирование номера телефона;
• форматирование цены;
• условные конструкции (if, elseif, else, endif);
• собственные функции спецификаторы;
• возможность задать сокращения для функций спецификаторов;
• применение функций спецификаторов цепочкой к одному значению.

Установка

Установить этот пакет можно как зависимость, используя Composer.

Использование

При отсутствии ключа в массиве значений выбрасывается исключение

Все значения преобразовываются в специальные символы HTML-сущности, с помощью функции htmlspecialchars. Для того чтобы преобразовать обратно, воспользуйтесь функцией спецификатором unescape или передайте четвертым аргументом значение false отменяющее автоматическое преобразование специальных символов в HTML-сущности.

C доступом по пути

Строковый шаблон содержит путь до значения в ассоциативном массиве.

C доступом по индексам

Строковый шаблон содержит индексы значений в массиве.

Экранирование спец. символов

Для экранирования спец. символов используется символ "\".

Для экранирования всех спец. символов в строке, можно воспользоваться функцией класса :

Для того чтобы убрать экранирование спец. символов в строке, можно воспользоваться функцией класса :

Использование функций спецификаторов

Доступные функции спецификаторов:

• date - форматирование даты и времени;
• sprintf - форматирование строки и чисел;
• escape - преобразует специальные символы в HTML-сущности;
• unescape - преобразует специальные HTML-сущности обратно в соответствующие символы;
• memory - форматирование размера памяти (x.x Б, x.x КБ, x.x МБ, x.x ГБ, x.x ТБ, x.x ПБ);
• time - форматирование времени (< 1 сек., x сек., x мин., x ч., x д.);
• declension - склонение слов после числительных;
• phone - форматирование номера телефона (+7(ddd)ddd-dddd);
• price - форматирование цены.

Указание функции спецификатора следует после указания ключа с разделителем "|".

Модификаторы функций спецификаторов можно динамически задавать через массив передаваемый третьим аргументом функции format.

Возможно указание функций спецификатора цепочкой с разделителем "|". Тогда значение будет передаваться последовательно, по цепочке, от одной функции спецификатора к другой.

PHP форматирование строки и числа с помощью sprintf

Спецификаторы функции sprintf. Указание функции спецификатора следует после указания ключа с разделителем "|".

Форматирование строк и чисел. Спецификаторы используемые в функци sprintf.

• b - Аргумент рассматривается как целое число и печатается в бинарном представлении.
• c - Аргумент рассматривается как целое число и печатается как символ из таблицы ASCII с соответствующим кодом.
• d - Аргумент рассматривается как целое число и печатается как целое число со знаком.
• e - Аргумент считается за число в научной нотации (т.е. 1.2e+2). Спецификатор точности задает количество цифр после десятичной запятой. В более ранних версиях он задавал общее количество значащих цифр (т.е. после запятой выводилось на 1 символ меньше).
• E - Аналогично спецификатору e, но использует заглавные символы (т.е. 1.2E+2).
• f - Аргумент считается за число с плавающей точкой (с учетом локали).
• F - Аргумент считается за число с плавающей точкой (без учета локали). Доступно с PHP 5.0.3.
• o - Аргумент рассматривается как целое число и печатается в восьмеричном представлении.
• s - Аргумент рассматривается и печатается как строка.
• u - Аргумент рассматривается как целое число и печатается как беззнаковое целое число.
• x - Аргумент рассматривается как целое число и печатается в шестнадцатеричном представлении (буквы будут в нижнем регистре).
• X - Аргумент рассматривается как целое число и печатается в шестнадцатеричном представлении (буквы будут в верхнем регистре).

Использование символа заполнения

Целое с лидирующими нулями

PHP форматирование даты и времени

Спецификаторы функции date, форматирование даты и времени. Указание функции спецификатора следует после указания ключа с разделителем "|".

Формат модификатора используемого в функции:

День

• d - День месяца, 2 цифры с ведущим нулём (от 01 до 31).
• D - Текстовое представление дня недели на русском языке (от Пн до Вс).
• j - День месяца без ведущего нуля (от 1 до 31).
• l - Полное наименование дня недели на русском языке (от Понедельник до Воскресенье).
• N - Порядковый номер дня недели в соответствии со стандартом ISO 8601 (от 1 (понедельник) до 7 (воскресенье)).
• S - Английский суффикс порядкового числительного дня месяца, 2 символа (st, nd, rd или th. Применяется совместно с j).
• w - Порядковый номер дня недели (от 0 (воскресенье) до 6 (суббота)).
• z - Порядковый номер дня в году (От 0 до 365).

Неделя

• W - Порядковый номер недели года в соответствии со стандартом ISO 8601; недели начинаются с понедельника, начиная с 0. Например: 42 (42-я неделя года).

Месяц

• F - Полное наименование месяца на русском языке, например, "Января" или "Марта" (от "Января" до "Декабря").
• f - Полное наименование месяца на русском языке, например, "Январь" или "Март" (от "Январь" до "Декабрь").
• m - Порядковый номер месяца с ведущим нулём (от 01 до 12).
• M - Сокращённое наименование месяца на русском языке, 3 символа (от "Янв" до "Дек").
• n - Порядковый номер месяца без ведущего нуля (от 1 до 12).
• t - Количество дней в указанном месяце (от 28 до 31).

Год

• L - Признак високосного года (1, если год високосный, иначе 0.).
• o - Номер года в соответствии со стандартом ISO 8601. Имеет то же значение, что и Y, кроме случая, когда номер недели ISO (W) принадлежит предыдущему или следующему году; тогда будет использован год этой недели. (Примеры: 1999 или 2003).
• X - Расширенное полное числовое представление года, не менее 4 цифр, с - для годов до нашей эры и + для годов нашей эры. (Примеры: -0055, +0787, +1999, +10191).
• x - Расширенное полное числовое представление, если требуется или стандартное полное числовое представление, если возможно (например, Y). Не менее четырёх цифр. Для годов до нашей эры указан префикс -. У годов после (и включая) 10000 префикс +. (Примеры: -0055, 0787, 1999, +10191).
• Y - Полное числовое представление года, не менее 4 цифр, с - для годов до нашей эры. (Примеры: -0055, 0787, 1999, 2003, 10191.).
• y - Номер года, 2 цифры (Примеры: 99, 03).

Время

• a - Ante meridiem (лат. "до полудня") или Post meridiem (лат. "после полудня") в нижнем регистре (am или pm).
• A - Ante meridiem или Post meridiem в верхнем регистре (AM или PM).
• B - Время в формате Интернет-времени (альтернативной системы отсчёта времени суток) (от 000 до 999).
• g - Часы в 12-часовом формате без ведущего нуля (от 1 до 12).
• G - Часы в 24-часовом формате без ведущего нуля (от 0 до 23).
• h - Часы в 12-часовом формате с ведущим нулём (от 01 до 12).
• H - Часы в 24-часовом формате с ведущим нулём (от 00 до 23).
• i - Минуты с ведущим нулём (от 00 до 59).
• s - Секунды с ведущим нулём (от 00 до 59).
• u - Микросекунды. (Например: 654321).
• v - Микросекунды. (Пример: 654).
• v - Микросекунды. (Пример: 654).

Часовой пояс

• e - Идентификатор часового пояса (Примеры: UTC, GMT, Atlantic/Azores).
• I - Признак летнего времени (1, если дата соответствует летнему времени, 0 в противном случае.).
• O - Разница с временем по Гринвичу без двоеточия между часами и минутами (Например: +0200).
• P - Разница с временем по Гринвичу с двоеточием между часами и минутами (Например: +02:00).
• p - То же, что и P, но возвращает Z вместо +00:00 (доступен, начиная с PHP 8.0.0) (Например: +02:00).
• T - Аббревиатура часового пояса, если известна; в противном случае смещение по Гринвичу. (Примеры: EST, MDT, +05).
• Z - Смещение часового пояса в секундах. Для часовых поясов, расположенных западнее UTC, возвращаются отрицательные числа, а для расположенных восточнее UTC - положительные. (от -43200 до 50400).

Полная дата/время

• c - Дата в формате стандарта ISO 8601 (2004-02-12T15:19:21+00:00).
• r - Дата в формате » RFC 222/» RFC 5322 (Например: Thu, 21 Dec 2000 16:01:07 +0200).
• U - Количество секунд, прошедших с начала Эпохи Unix (1 января 1970 00:00:00 GMT) (Смотрите также time()).

Ключи форматирования даты на русском языке

• F - Полное наименование месяца на русском языке, например, "Января" или "Марта" (от "Января" до "Декабря").
• f - Полное наименование месяца на русском языке, например, "Январь" или "Март" (от "Январь" до "Декабрь").
• M - Сокращённое наименование месяца на русском языке, 3 символа (от "Янв" до "Дек").
• D - Текстовое представление дня недели на русском языке (от "Пн" до "Вс").
• l - Полное наименование дня недели на русском языке (от "Понедельник" до "Воскресенье").

Установить используемый формат по умолчанию:

Функция спецификатор escape

Преобразует специальные символы в HTML-сущности {{|escape(flags, encoding, doubleEncode)}}

Функция спецификатор unescape

Преобразует специальные HTML-сущности обратно в соответствующие символы {{|escape(flags)}}

PHP форматирование размера памяти

Функция спецификатор memory. Форматирование размера памяти.

PHP форматирование времени

Функция спецификатор time, форматирование времени.

Доступные аргументы функции спецификатора:

• seconds - результат форматирования в секундах;
• minutes - результат форматирования в минутах;
• hours - результат форматирования в часах;
• days - результат форматирования в днях.

Если аргумент спецификатора не указан, форматирование осуществляется в наиболее подходящей размерности.

PHP склонение слов после числительных

С помощью функции спецификатора declension можно склонять существительные после чисел. Например: 1 год, 2 года, 5 лет.

Модификаторы функции спецификатора склонения существительного после числа:

• первый модификатор задает текст для единичных значений;
• второй для значений с 2-х до 4-х;
• третий для всех остальных.

Форматирование телефонных номеров

С помощью функции спецификатора phone можно форматировать номера телефонов по заданной маске (формату):

Форматирование числа

С помощью функции спецификатора number можно форматировать числа:

Модификаторы функции спецификатора форматирования числа:

• int decimals (2) - число знаков после запятой;
• string decimalSeparator ('.') - разделитель дробной части;
• string thousandsSeparator ('') - разделитель тысяч;
• bool allowZeroDecimal (false) - разрешить вывод 0 в конце дробной части.

Для упрощения ввода функций спецификаторов форматирования числа, воспользуйтесь сокращением.

PHP форматирование цены

С помощью функции спецификатора price можно форматировать цены:

Модификаторы функции спецификатора форматирования цены:

• int decimals (2) - число знаков после запятой;
• string decimalSeparator ('.') - разделитель дробной части;
• string thousandsSeparator ('') - разделитель тысяч;
• bool allowZeroDecimal (false) - разрешить вывод 0 в конце дробной части.
• int round (null) - округляет цену. Передавать константы: PHP_ROUND_HALF_UP - округляет от нуля, когда следующий знак находится посередине, PHP_ROUND_HALF_DOWN - округляет к нулю, когда следующий знак находится посередине.
• int roundPrecision (0) - количество десятичных знаков, до которых производится округление.
• bool floor (false) - округляет в меньшую сторону (до целового).

Для упрощения ввода функций спецификаторов форматирования цены, воспользуйтесь сокращением.

Условные конструкции

Доступны следующий условные конструкции: . При отсутствии ключа в массиве значений исключение не выбрасывается.

Возможно использование функций спецификаторов в условных конструкциях:

Добавление функций спецификаторов

Класс функции спецификатора должен реализовывать интерфейс

Добавление новой функции спецификатора осуществляется с помощью метода :

Сокращения

Для упрощения ввода функций спецификаторов можно использовать сокращения. Сокращения добавляются методом Formatter::addShortcut с указанием имени сокращения. Для использования сокращения, введите название начиная с символа "~".