ucwords()

Introdução

A função ucwords() em PHP capitaliza o primeiro caractere de cada palavra em uma string e retorna o resultado. É o auxiliar ideal para transformar entradas do usuário como "jane doe" em um formato apresentável "Jane Doe" — útil para nomes, títulos, cabeçalhos e rótulos.

Esta página aborda a sintaxe, o parâmetro opcional de delimitador, as armadilhas que surpreendem a maioria dos desenvolvedores (ela não converte o restante da palavra para minúsculas, e divide apenas em espaços em branco por padrão), e como ucwords() difere de funções relacionadas.

Sintaxe

ucwords(string $string, string $separators = " \t\r\n\f\v"): string

Parâmetro	Descrição
`$string`	A string de entrada a ser transformada.
`$separators`	(Opcional) Os caracteres que marcam o início de uma nova "palavra". O padrão são espaços em branco: espaço, tab, retorno de carro, nova linha, form feed e tab vertical.

A função retorna uma nova string — ela não modifica $string no lugar, pois strings em PHP são passadas por valor.

Exemplo básico

php— editable, runs on the server

Saída:

Hello, World!

ucwords() percorre a string e converte para maiúscula qualquer letra que segue um delimitador (ou está no início). Aqui, tanto hello quanto world têm sua primeira letra capitalizada.

Atenção: ela não converte o restante para minúsculas

Uma surpresa comum é que ucwords() toca apenas a primeira letra de cada palavra. Letras já em maiúsculas são mantidas intocadas:

<?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

Se você quiser um título limpo onde apenas a primeira letra de cada palavra esteja em maiúscula, converta a string para minúsculas primeiro com strtolower():

<?php

$title = "MARY HAD A LITTLE LAMB";
echo ucwords(strtolower($title)); // Mary Had A Little Lamb

Delimitadores personalizados

Por padrão, apenas espaços em branco separam as palavras, portanto valores com hífen ou pipe são tratados como uma única palavra. Passe o argumento opcional $separators para capitalizar após outros caracteres também:

<?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

Isso é útil para slugs, nomes como "o'brien", ou qualquer texto separado por tokens. Observe que ao fornecer $separators, o espaço em branco não é mais um delimitador a menos que você o inclua — portanto uma chamada típica é ucwords($name, " -").

ucwords() vs. funções relacionadas

Função	O que ela faz
`ucfirst()`	Capitaliza apenas o primeiro caractere de toda a string.
`ucwords()`	Capitaliza o primeiro caractere de cada palavra.
`strtoupper()`	Converte a string inteira para maiúsculas.
`strtolower()`	Converte a string inteira para minúsculas.
`lcfirst()`	Converte o primeiro caractere da string para minúscula.

Observação sobre caracteres multibyte e acentuados

ucwords() funciona byte a byte e é confiável para ASCII simples. Ela não capitaliza corretamente letras acentuadas ou não-latinas (por exemplo é, ñ, ou cirílico). Para capitalização de título com suporte a Unicode, use a extensão mbstring com mb_convert_case($string, MB_CASE_TITLE, "UTF-8").

Conclusão

ucwords() é a maneira padrão de capitalizar a primeira letra de cada palavra em uma string. Lembre-se de seus dois comportamentos principais: ela deixa as letras restantes como estão (combine com strtolower() para um título limpo), e divide em espaços em branco a menos que você passe $separators personalizados. Para textos acentuados, use mb_convert_case().

Prática

Qual é a função de 'ucwords' em PHP?

Converte o primeiro caractere de cada palavra em uma string para maiúsculaConverte o primeiro caractere de uma string para maiúsculaConverte todos os caracteres de uma string para maiúsculaConverte o primeiro caractere de cada palavra em uma string para minúscula