ave-cms/help/helpers/Str.md

Str — строки (UTF-8)

App\Helpers\Str — работа со строками в кодировке UTF-8. Все методы под капотом используют mbstring, поэтому корректно считают длину и режут кириллицу. Класс статический, инстанс не создаётся.

use App\Helpers\Str;

Почему не встроенные strlen/substr? Они считают байты, а не символы: strlen('Привет') вернёт 12, а Str::length('Привет') — 6. Для любого текста с кириллицей используйте Str.

---

Базовые операции

length($str): int

Длина строки в символах.

Str::length('Привет');        // 6

upper($str) / lower($str)

Регистр с учётом кириллицы.

Str::upper('привет');         // ПРИВЕТ
Str::lower('ТОВАР');          // товар

ucfirst($str) — первая буква заглавная, title($str) — каждое слово с заглавной

Str::ucfirst('кресло-коляска');   // Кресло-коляска
Str::title('медицинское оборудование'); // Медицинское Оборудование

trim / ltrim / rtrim ($str, $characters = null)

Как встроенные, но безопасно приводят к строке. Второй аргумент — список символов.

Str::trim('  текст  ');          // 'текст'
Str::trim('/catalog/', '/');     // 'catalog'

nullIfEmpty($str)

Триммит и возвращает null, если осталась пустая строка. Удобно для записи в nullable-поля БД.

Str::nullIfEmpty('   ');   // null
Str::nullIfEmpty(' abc '); // 'abc'

substr($str, $start, $length = null), pos($haystack, $needle, $offset = 0)

Многобайтовые аналоги substr/strpos.

Str::substr('Привет мир', 0, 6);   // 'Привет'
Str::pos('Привет', 'вет');         // 3 (в символах, не байтах)

pad, repeat, replace

Обёртки над str_pad / str_repeat / str_replace.

---

Поиск и проверки

contains($haystack, $needle): bool

if (Str::contains($title, 'УЗИ')) { ... }

startsWith($str, $prefix) / endsWith($str, $suffix): bool

Str::startsWith('/catalog/1', '/catalog');  // true
Str::endsWith('photo.JPG', '.JPG');         // true

is($pattern, $value): bool

Соответствие маске с wildcards * (любые символы) и ? (один символ).

Str::is('doc_*', 'doc_37');     // true
Str::is('img?.png', 'img5.png'); // true

---

Обрезка текста

limit($str, $limit = 100, $end = '...')

Обрезает по количеству символов, добавляет суффикс, только если реально обрезал. Может разорвать слово посередине.

Str::limit('Длинное описание товара', 10);   // 'Длинное оп...'

words($str, $words = 10, $end = '...')

Обрезает по количеству слов.

Str::words('один два три четыре', 2);   // 'один два...'

truncateSmart($string, $length = 80, $suffix = '...', $breakWords = false, $middle = false)

«Умная» обрезка. По умолчанию не рвёт слова (обрезает до последнего целого). $middle = true — вырезает середину, оставляя начало и конец.

Str::truncateSmart('Кресло-коляска электрическая Model X', 20);
// 'Кресло-коляска...'   (не рвёт слово)
Str::truncateSmart('очень_длинное_имя_файла.pdf', 18, '…', false, true);
// 'очень_д…йла.pdf'    (середина вырезана)

truncateText($string, $length = 100, $suffix = '…')

Обрезает по первому целому слову после заданной длины (т.е. не короче $length). Суффикс по умолчанию — HTML-мнемоника многоточия.

truncate() — устаревший алиас limit().

---

Маскирование

mask($str, $start, $length = 0, $char = '*')

Заменяет часть строки символами маски. $start < 0 — отсчёт от конца, $length = 0 — до конца строки.

Str::mask('4111111111111234', 0, 12);  // '************1234'
Str::mask('secret', -3);               // 'sec***'

maskEmail($email)

Маскирует локальную часть e-mail, показывая ~⅓ символов.

Str::maskEmail('ivanov@mail.ru');  // 'iv****@mail.ru'
Str::maskEmail('ab@x.ru');         // '**@x.ru' (короткое имя скрывается полностью)

---

Именование и slug

camel / studly / snake ($str, $delimiter = '_')

Преобразование стилей именования.

Str::camel('rubric_field_id');    // 'rubricFieldId'
Str::studly('rubric_field_id');   // 'RubricFieldId'
Str::snake('rubricFieldId');      // 'rubric_field_id'

slug($str, $separator = '-')

Текст → URL-slug. Транслитерирует кириллицу, чистит спецсимволы, схлопывает разделители.

Str::slug('Кресло-коляска ЕК-6012');   // 'kreslo-kolyaska-ek-6012'
Str::slug('Маски (упаковка 50 шт.)');  // 'maski-upakovka-50-sht'

machineAlias($str, $separator = '-')

Для технических ключей: не транслитерирует, только чистит до a-z0-9_.- и схлопывает разделители. Кириллица будет удалена — применяйте к латинским ключам.

Str::machineAlias('My Cache.Key v2');  // 'my-cache.key-v2'

---

Генерация

random($length = 16, $chars = 'a-z0-9')

Криптографически стойкая случайная строка (использует random_bytes).

Str::random(32);                       // 'k3f9...'
Str::random(6, '0123456789');          // '481902' (только цифры)

uuid()

UUID версии 4.

Str::uuid();   // '3f2504e0-4f89-41d3-9a0c-0305e82c3301'

---

Безопасность и вывод

equals($a, $b): bool

Сравнение строк, устойчивое к timing-атакам (hash_equals). Для токенов/подписей.

if (Str::equals($providedToken, $expected)) { ... }

sha256($str) — SHA-256 хеш строки.

Для паролей это не подходит — используйте password_hash().

stripTags($str, $allowedTags = '')

Убирает HTML-теги и декодирует сущности.

Str::stripTags('<b>Цена</b>&nbsp;100');   // 'Цена 100'

escape($str)

Экранирует для безопасного вывода в HTML (htmlspecialchars, ENT_QUOTES|ENT_HTML5).

echo Str::escape($userInput);   // < > " ' & становятся безопасными

---

Рецепты

ЧПУ из заголовка документа:

$alias = Str::slug($input['title']);
if ($alias === '') { $alias = 'doc-' . Str::random(6); }

Короткий анонс для карточки без разрыва слов:

$teaser = Str::truncateSmart(Str::stripTags($html), 140);

Безопасный вывод пользовательского текста:

echo Str::escape($comment);