ucwords()
Функция ucwords() в PHP преобразует первый символ каждого слова в строке к верхнему регистру. Синтаксис, параметры и примеры.
Введение
Функция ucwords() в PHP преобразует первый символ каждого слова в строке к верхнему регистру и возвращает результат. Это незаменимый инструмент для преобразования пользовательского ввода, например "jane doe", в читаемый вид "Jane Doe" — удобно для имён, заголовков и подписей.
На этой странице описаны синтаксис, необязательный параметр разделителя, подводные камни, которые удивляют большинство разработчиков (функция не переводит остальные буквы в нижний регистр и по умолчанию делит строку только по пробельным символам), а также отличия ucwords() от родственных функций.
Синтаксис
ucwords(string $string, string $separators = " \t\r\n\f\v"): string| Параметр | Описание |
|---|---|
$string | Входная строка для преобразования. |
$separators | (Необязательный) Символы, обозначающие начало нового «слова». По умолчанию — пробельные символы: пробел, табуляция, возврат каретки, перевод строки, перевод формы и вертикальная табуляция. |
Функция возвращает новую строку — она не изменяет $string на месте, поскольку строки в PHP передаются по значению.
Базовый пример
Вывод:
Hello, World!ucwords() проходит по строке и переводит в верхний регистр любую букву, следующую за разделителем (или стоящую в самом начале). Здесь первые буквы слов hello и world преобразуются к верхнему регистру.
Подводный камень: остальные буквы не затрагиваются
Распространённая неожиданность состоит в том, что ucwords() изменяет только первую букву каждого слова. Буквы, уже находящиеся в верхнем регистре, остаются неизменными:
<?php
echo ucwords("hello WORLD"); // Hello WORLD — "WORLD" keeps its existing uppercase letters
echo "\n";
echo ucwords("MARY had a LITTLE lamb"); // MARY Had A LITTLE LambЕсли нужен чистый заголовок, где только первая буква каждого слова написана с заглавной, сначала приведите строку к нижнему регистру с помощью strtolower():
<?php
$title = "MARY HAD A LITTLE LAMB";
echo ucwords(strtolower($title)); // Mary Had A Little LambПользовательские разделители
По умолчанию слова разделяются только пробельными символами, поэтому дефисные или разделённые символом «|» значения считаются одним словом. Передайте необязательный аргумент $separators, чтобы делать заглавной первую букву после других символов тоже:
<?php
// Default: only the first letter is capitalized.
echo ucwords("hello-world|of-php"); // Hello-world|of-php
echo "\n";
// Treat "-" and "|" as word boundaries as well.
echo ucwords("hello-world|of-php", "-|"); // Hello-World|Of-PhpЭто полезно для слагов, имён вроде "o'brien" или любого текста с разделителями-токенами. Обратите внимание: если вы указываете $separators, пробел больше не является разделителем, если вы его явно не включите — поэтому типичный вызов выглядит как ucwords($name, " -").
ucwords() и родственные функции
| Функция | Что делает |
|---|---|
ucfirst() | Переводит в верхний регистр только первый символ всей строки. |
ucwords() | Переводит в верхний регистр первый символ каждого слова. |
strtoupper() | Переводит всю строку в верхний регистр. |
strtolower() | Переводит всю строку в нижний регистр. |
lcfirst() | Переводит в нижний регистр первый символ строки. |
Примечание о многобайтовых и акцентированных символах
ucwords() работает побайтово и надёжна для чистого ASCII. Она не корректно обрабатывает акцентированные или не-латинские буквы (например é, ñ или кириллицу). Для Unicode-совместимого преобразования заголовков используйте расширение mbstring с функцией mb_convert_case($string, MB_CASE_TITLE, "UTF-8").
Заключение
ucwords() — стандартный способ сделать заглавной первую букву каждого слова в строке. Помните о двух ключевых особенностях: она не изменяет остальные буквы (комбинируйте её с strtolower() для чистого регистра заголовка) и делит строку по пробельным символам, если не передать пользовательские $separators. Для текста с акцентированными символами используйте mb_convert_case().