Str::headline
Converts camelCase, snake_case or kebab-case strings into space-separated Title Cased words.
Str::headline(string $value): stringParameters
| Parameter | Type | Description |
|---|---|---|
$$value | string | The string to convert. Whitespace, hyphens, underscores and case transitions are all treated as word boundaries. |
Return value
stringA space-delimited string with each word title-cased, derived by splitting the input on whitespace, hyphens, underscores and upper-case letter boundaries.
Errors
Nothing.
Str::headline is the humanising counterpart to Str::camel() and Str::snake(). Given a single token it splits on upper-case boundaries with Str::ucsplit(); given something already spaced it title-cases each word. Either way, hyphens, underscores and spaces all collapse to a single space, and empty segments are dropped.
When to reach for it
Use it wherever an identifier must be shown to a person: form labels derived from column names, notification subjects derived from event class names, admin table headers, or the fallback title in a generated UI. Laravel itself uses it to turn validation attribute names into readable messages.
What trips people up
Runs of consecutive capitals are split letter by letter, because ucsplit() inserts a break before every upper-case character. Str::headline('HTTPRequest') is 'H T T P Request', and 'PDFExport' becomes 'P D F Export'. Acronyms are the reliable way to get ugly output.
The fix is to give it an explicit delimiter: Str::headline('pdf_export') is 'Pdf Export', which is at least sane, and a small replacement map applied afterwards restores PDF. Digits are also not word boundaries, so 'address2' stays 'Address2'.
Example
When to use it
- Generate a readable form label from a database column name such as email_verified_at.
- Turn an event or job class name into a notification subject line.
- Build admin table headers from an array of attribute keys.
Frequently asked questions
How do I turn a snake_case column name into a readable label in Laravel?
Str::headline('email_verified_at') returns 'Email Verified At'. It handles snake_case, kebab-case, camelCase and already-spaced input the same way.
Why does Str::headline split my acronym into single letters?
Because it splits before every upper-case character, so 'HTTPRequest' becomes 'H T T P Request'. Pass a delimited form such as 'http_request' and repair the casing afterwards.
What is the difference between Str::headline and Str::title?
Str::title only changes case; it does not insert word boundaries. Str::headline first splits the identifier on underscores, hyphens and case transitions, then title-cases the pieces.
More examples
Form labels from column names
All four naming conventions converge on the same readable form, which is why headline is the usual default label generator in generated admin screens. Note that no dictionary is applied — 'at' stays capitalised as a word.
<?php
use Illuminate\Support\Str;
$columns = ['first_name', 'email_verified_at', 'isAdmin', 'billing-address'];
foreach ($columns as $column) {
printf("%-18s %s\n", $column, Str::headline($column));
}
// first_name First Name
// email_verified_at Email Verified At
// isAdmin Is Admin
// billing-address Billing AddressRescuing acronyms
The first line shows the failure mode directly. Feeding headline a delimited form gives a merely-wrong-cased word rather than scattered letters, and a small replacement map restores the acronyms in one pass.
<?php
use Illuminate\Support\Str;
// Raw headline mangles the acronym.
echo Str::headline('PDFExportJob'), "\n";
// P D F Export Job
// Snake-case the acronym first, then repair it afterwards.
$label = Str::headline('pdf_export_job');
echo $label, "\n";
// Pdf Export Job
echo Str::replace(['Pdf', 'Api', 'Url'], ['PDF', 'API', 'URL'], $label), "\n";
// PDF Export Job
Discussion