Хэлпер text

Небольшая заметка-справка о возможностях стандартного хэлпера text. Хэлпер предназначен для работы с текстом (какая неожиданность! ), некоторые его функции могут оказаться весьма полезными для разрабатываемых вами проектов, если они работают с текстовыми ресурсами (статьи, форумы и т.д.).

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

• limit_words($str, $limit = 100, $end_char = NULL). Обрезает строку $str до $limit слов. В конец результирующей строки добавляет символы $end_char (по умолчанию символ «многоточие»). Например, если вы не хотите в RSS или на главной показывать полный текст статьи, данная функция может стать полезной для проведения «обрезания».
• limit_chars($str, $limit = 100, $end_char = NULL, $preserve_words = FALSE). Аналогична limit_words(), но в качестве единиц измерения длины строки выступают символы. Дополнительный параметр $preserve_words указывает, сохранять ли целыми слова (по умолчанию FALSE). Например:
  

  $str = 'Мама мыла раму'; echo text::limit_words($str, 7); // выведет 'Мама мы...' echo text::limit_words($str, 7, "!"); // выведет 'Мама мы!' echo text::limit_words($str, 7, NULL, TRUE); // выведет 'Мама мыла...'

• alternate(). Позволяет чередовать строки, переданные в качестве параметров функции. Реализуется с помощью встроенного счетчика (статическая переменная), который увеличивается каждый раз, когда вызывается данная функция. Например, так можно чередовать светлые и темные строки в таблице:
  

  foreach($rows as $row) { echo '<tr class="', text::alternate("light", "dark"), '"><td>', $row->value, '</td></tr>'; }

  А если надо обнулить счетчик, просто вызываем text::alternate() без параметров.

  К сожалению, функция не может принимать на входе массив строк, это было бы удобнее (ИМХО). Написал запрос разработчикам, может добавят такую возможность.

• random($type = ‘alnum’, $length = 8). Создает случайную строку указанного типа (параметр $type) и длины ($length). В качестве типа могут быть использованы: ‘alnum‘ (цифры и буквы латинского алфавита), ‘alpha‘ (буквы латинского алфавита), ‘hexdec‘ (цифры шестнадцатеричной системы счисления от 0 до f), ‘numeric‘ (цифры от 0 до 9), ‘nozero‘ (цифры от 1 до 9), ‘distinct‘ (цифры и числа, не имеющие схожих по начертанию аналогов, удобно для формирования текста т.н. капчи). Если строка $type не совпадает ни с одной из перечисленных, то она будет использована как список доступных символов (например, если вы захотите использовать не латинские символы, а кириллицу).
• reduce_slashes($str). Избавляет строку $str от повторяющихся слэшей. Работает только с прямым слэшем, т.е. с символом ‘/‘.
• censor($str, $badwords, $replacement = ‘#’, $replace_partial_words = FALSE). Функция-цензор, позволяет заменять в строке $str слова из «черного списка» $badwords на символы из параметра $replacement (по умолчанию символ «решетка»). Последний параметр $replace_partial_words указывает, заменять только целые слова, или любые вхождения данного шаблона. Для определения «целостности» слова используется псевдосимвол \b (описание).
  

  Будьте внимательны! Несмотря на название $replace_partial_words («заменять части слов«), использование значения FALSE приводит к полной замене всех вхождений шаблона в тексте. Вы же не захотите видеть на вашем сайте строки «застра*** братуху, застра***»
  Update. Имя параметра оперативно исправили, в 2.4 все будет ОК.

  Например, сравните эти два вызова:
  

  $str = 'Маленький переполох'; $bad =array('лох'); echo text::censor($str, $bad, '*'); // выведет 'Маленький перепо***' echo text::censor($str, $bad, '*', TRUE); // выведет исходную строку

• similar(array $words). Находит общую подстроку, присутствующую во всех словах массива $words. Алгоритм прост: берется первое слово из массива и посимвольно проверяется совпадение во всех остальных элементах $words. Таким образом, similar(array(‘test’, ‘test!’)) вернет слово ‘test‘, а similar(‘test’, ’1test’) вернет пустую строку.
• auto_link_urls($text). Как видно из названия, автоматически конвертирует в строке $text текстовые URL’ы в гиперссылки. Заменяет как ссылки с указанием протокола (http://, https://), так и без него (www.example.com). Уже оформленные ссылки не трогает. Для формирования тэгов использует html::anchor().
• auto_link_emails($text). Аналогична auto_link_urls(), но работает с почтовыми адресами (html::mailto()).
• auto_link($text). Два в одном: конвертирует и URL’ы, и email’ы. По сути просто последовательный вызов предыдущих двух функций.
• auto_p($str). Обрамляет абзацы текста тэгами

  . Двойные переводы каретки считаются за начало абзаца, одиночные заменяются на тэг
  . Многие html-тэги в тексте (типа TABLE, UL, DIV) в отдельные абзацы не выносятся. Удобна для автоматического форматирования текста, если вы не планируете использовать уже готовый текстовый редактор типа Tiny_MCE.

• bytes($bytes, $force_unit = NULL, $format = NULL, $si = TRUE). Преобразовывает $bytes (в байтах) в удобочитаемую строку с использованием более крупных единиц (Кб, Мб и т.д.). Параметр $force_unit определяет, в каких единицах вы хотели бы видеть результат (о допустимых единицах чуть ниже), если не указан — вычисляется автоматически. $format — аргумент, определяющий форматирование результата (синтаксис такой же, как в функции sprintf()), по умолчанию два знака после запятой, заполнение нулями. Последний параметр — выбор используемого стандарта, СИ (по умолчанию) или IEC.
  1. СИ. Доступны единицы: ‘B’, ‘kB’, ‘MB’, ‘GB’, ‘TB’, ‘PB’. 1 kB = 1000 B.
  2. IEC. Доступны единицы: ‘B’, ‘KiB’, ‘MiB’, ‘GiB’, ‘TiB’, ‘PiB’. 1KiB = 1024 B.

  Также, если вы указываете единицы вручную, выбор стандарта будет основываться на анализе этой единицы измерения (т.е. если вы хотите размер в ‘KiB‘, параметр $si можно не указывать).

  Будьте внимательны к подобным преобразованиям! Поскольку стандартная точность — два знака после запятой, 10 байт после явного преобразования в килобайты превратятся в ноль.

• widont($str). Предотвращает перенос строки перед последним словом в строке $str, заменяя пробел перед ним на символ «неразрывный пробел» ( ).

К чему я это все?

Самое интересное, что о функционале доброй половины хэлперов из дистрибутива фреймворка я и не подозревал, а ведь многие функции весьма полезны и актуальны. Меньше знаешь — лучше спишь?