ucwords
Converts the first character of each word in a string to uppercase.
ucwords(string $string, string $separators = " \t\r\n\f\v"): string- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$string | string | The input string. |
$separatorsoptional | string= " \t\r\n\f\v" | The characters that mark a word boundary. Each character is treated individually. A word is any run of characters not listed here. |
Return value
stringThe string with the first ASCII letter of each word uppercased.
Changelog
- PHP 8.2.0Case conversion no longer depends on the locale set with setlocale(). Only ASCII characters are converted.
ucwords uppercases the first byte of every word, where a word is any run of characters not present in the separators list. By default the separators are the six ASCII whitespace characters, so hyphens and apostrophes do not start a new word unless you say so.
When to reach for it
It is fine for tidying single-line machine data: a city name typed in lowercase, a column heading built from a snake_case key, a short label in an admin table. Pass a custom separator set to handle hyphenated or dotted input, for example ucwords($name, " -'").
What trips people up
Like ucfirst, it never lowercases anything, so ucwords('JOHN SMITH') stays in caps; the usual idiom is ucwords(strtolower($s)). Passing a custom separator list replaces the default whitespace set, so ucwords($s, '-') stops capitalising after spaces.
Since PHP 8.2 it is ASCII-only. More importantly, it is not a title-case algorithm and it is not a name formatter: it produces Mcdonald, O'neil and Van Der Berg, all wrong. Storing the result of ucwords over a user's name destroys information you cannot recover. Capitalise for display if you must, and use mb_convert_case($s, MB_CASE_TITLE, 'UTF-8') for anything non-ASCII.
Example
When to use it
- Turn a snake_case database column into a readable table heading.
- Tidy up a city or country name that was entered in all lowercase.
- Capitalise a hyphenated identifier for display by passing " -" as the separators.
Frequently asked questions
Why does ucwords not capitalise after a hyphen?
Because the default separator list is whitespace only. Pass a custom list such as " -" as the second argument to treat hyphens as word boundaries too.
How do I convert a string to proper title case?
For ASCII, use ucwords(strtolower($string)) — ucwords alone leaves existing capitals in place. For Unicode text use mb_convert_case($string, MB_CASE_TITLE, 'UTF-8').
Should I use ucwords on people's names?
No. It produces Mcdonald instead of McDonald and Van Der Berg instead of van der Berg, and storing the result loses the original spelling. Save names as the user typed them.
More examples
Making column names readable
Prints 'First Name', 'Created At' and 'Total Amount Due'. Underscores are converted to spaces first because ucwords treats only whitespace as a boundary by default.
<?php
$columns = ['first_name', 'created_at', 'total_amount_due'];
foreach ($columns as $col) {
echo ucwords(str_replace('_', ' ', $col)), "\n";
}Why it is a poor name formatter
Prints "O'Neil", 'Mcdonald', 'Van Der Berg' and 'De La Cruz'. Only the first is right: 'McDonald' needs an interior capital, and the Dutch and Spanish particles are conventionally lowercase. Store names exactly as entered rather than running them through ucwords.
<?php
$names = ["o'neil", 'mcdonald', 'van der berg', 'de la cruz'];
foreach ($names as $n) {
echo ucwords($n, " -'"), "\n";
}
Discussion