字串操作（Str 類別） - Knowledge of Laravel

什麼是 Str 類別

Illuminate\Support\Str 類別提供豐富的字串操作方法。相較於個別呼叫 PHP 的標準字串函式，可用統一介面直覺處理字串。 Laravel 的字串操作有兩種風格：

靜態方法風格：Str::slug($title, '-') — 適合單次操作
Fluent 風格（method chain）：Str::of($title)->slug('-')->limit(50) — 可將多個操作串起來寫

use Illuminate\Support\Str;

// 靜態方法
$slug = Str::slug('My New Blog Post', '-');
// 'my-new-blog-post'

// Fluent（Str::of）
$result = Str::of('  My New Blog Post: Part 1  ')
    ->trim()
    ->slug('-')
    ->limit(30);
// 'my-new-blog-post-part-1'

str() 全域 helper 函式與 Str::of() 等效。可寫成 str('hello')->upper()。

大小寫轉換

轉換字串大小寫（大寫、小寫、命名法）的方法。常用於資料庫欄位名或 API 回應鍵值的轉換。

`Str::camel()` / `Str::snake()` / `Str::kebab()` / `Str::studly()`

use Illuminate\Support\Str;

// camelCase（開頭小寫）
Str::camel('foo_bar');        // 'fooBar'
Str::camel('user_profile_id'); // 'userProfileId'

// snake_case
Str::snake('fooBar');         // 'foo_bar'
Str::snake('UserProfile');    // 'user_profile'

// kebab-case
Str::kebab('fooBar');         // 'foo-bar'

// StudlyCase（PascalCase）
Str::studly('foo_bar');       // 'FooBar'
Str::studly('user-profile');  // 'UserProfile'

`Str::lower()` / `Str::upper()` / `Str::title()`

use Illuminate\Support\Str;

Str::lower('LARAVEL');         // 'laravel'
Str::upper('laravel');         // 'LARAVEL'
Str::title('hello world');     // 'Hello World'

Slug 與 URL

`Str::slug()` — 產生 URL 友善的 slug

產生文章或頁面 URL 時的必備方法。將空格與特殊字元轉換為 URL 安全的字串。

use Illuminate\Support\Str;

Str::slug('Laravel フレームワーク', '-');
// 'laravel'（日文不會被轉為 ASCII 而被移除）

Str::slug('My New Blog Post', '-');
// 'my-new-blog-post'

Str::slug('Hello World!', '_');
// 'hello_world'

包含中文／日文時 slug 可能為空。若想使用中文 slug，可另外搭配羅馬拼音轉換函式庫，或考慮使用 ID、時間戳作為 URL。

用 `Str::of()` 從 slug 產生到驗證一次完成

use Illuminate\Support\Str;

$title = '  My New Blog Post: Part 1!  ';

$slug = Str::of($title)
    ->trim()
    ->slug('-')
    ->limit(50);
// 'my-new-blog-post-part-1'

字串截斷

`Str::limit()` — 依字元數截斷

在列表顯示文章內文或留言時產生預覽文字的方法。

use Illuminate\Support\Str;

$text = 'Laravelは美しいWebアプリケーションを作るためのPHPフレームワークです。';

// 截斷至 20 字元（預設會於尾端加上 "..."）
Str::limit($text, 20);
// 'Laravelは美しいWebアプリケー...'

// 自訂尾端字串
Str::limit($text, 20, ' → 続きを読む');
// 'Laravelは美しいWebアプリケー → 続きを読む'

// 不在單字中間切斷（英文文字用）
Str::limit('The quick brown fox jumps over the lazy dog', 20, preserveWords: true);
// 'The quick brown fox...'

`Str::words()` — 依單字數截斷

use Illuminate\Support\Str;

Str::words('Perfectly balanced, as all things should be.', 3, ' >>>');
// 'Perfectly balanced, as >>>'

字串搜尋與確認

`Str::contains()` — 是否包含子字串

use Illuminate\Support\Str;

Str::contains('This is my name', 'my');
// true

// 以陣列檢查多個候選（包含任一即可）
Str::contains('This is my name', ['my', 'your']);
// true

// 忽略大小寫
Str::contains('This is my name', 'MY', ignoreCase: true);
// true

`Str::startsWith()` / `Str::endsWith()`

use Illuminate\Support\Str;

Str::startsWith('https://laravel.com', 'https://');
// true

Str::startsWith('https://laravel.com', ['https://', 'http://']);
// true

Str::endsWith('photo.jpg', '.jpg');
// true

Str::endsWith('photo.jpg', ['.jpg', '.png', '.gif']);
// true

`Str::is()` — 萬用字元樣式比對

use Illuminate\Support\Str;

Str::is('foo*', 'foobar');
// true

Str::is('*/user/*', '/admin/user/profile');
// true

// 忽略大小寫
Str::is('F*', 'foo', ignoreCase: true);
// true

字串轉換與置換

`Str::replace()` — 置換字串

use Illuminate\Support\Str;

Str::replace('8.x', '13.x', 'Laravel 8.x');
// 'Laravel 13.x'

// 忽略大小寫置換
Str::replace('laravel', 'Symphony', 'I love Laravel', caseSensitive: false);
// 'I love Symphony'

`Str::replaceArray()` — 依序以陣列置換

use Illuminate\Support\Str;

$string = '預定為 ? 至 ?';

$result = Str::replaceArray('?', ['上午9點', '下午5點'], $string);
// '預定為 上午9點 至 下午5點'

`Str::replaceMatches()` — 以正則表達式置換

use Illuminate\Support\Str;

// 從電話號碼移除非數字
Str::replaceMatches('/[^0-9]/', '', '(03) 1234-5678');
// '0312345678'

// 以 closure 動態產生置換內容
Str::replaceMatches('/\d+/', fn ($matches) => '[' . $matches[0] . ']', '1つ 2個 3本');
// '[1]つ [2]個 [3]本'

`Str::remove()` — 移除字串

use Illuminate\Support\Str;

Str::remove('e', 'Peter Piper picked a peck of pickled peppers.');
// 'Ptr Pipr pickd a pck of pickld ppprs.'

// 以陣列刪除多個字串
Str::remove(['foo', 'bar'], 'foo and bar and baz');
// ' and  and baz'

`Str::squish()` — 移除多餘空白

use Illuminate\Support\Str;

Str::squish('  Laravel   Framework  ');
// 'Laravel Framework'

字串前後操作

`Str::before()` / `Str::after()`

use Illuminate\Support\Str;

// 指定字串之前的部分
Str::before('[email protected]', '@');
// 'test'

// 指定字串之後的部分
Str::after('[email protected]', '@');
// 'example.com'

// 以最後出現的位置為基準
Str::afterLast('App\Http\Controllers\UserController', '\\');
// 'UserController'

Str::beforeLast('App\Http\Controllers\UserController', '\\');
// 'App\Http\Controllers'

`Str::between()` — 取得兩字串之間

use Illuminate\Support\Str;

Str::between('[debug] Error occurred in module', '[', ']');
// 'debug'

`Str::start()` / `Str::finish()` — 確保以特定字元開頭／結尾

若已經以該字元開頭，不會重複加入（不會加倍）。

use Illuminate\Support\Str;

// 確保以 '/' 開頭
Str::start('users/profile', '/');
// '/users/profile'

Str::start('/users/profile', '/');
// '/users/profile'（不會加倍）

// 確保以 '/' 結尾
Str::finish('https://example.com', '/');
// 'https://example.com/'

`Str::chopStart()` / `Str::chopEnd()` — 移除特定前綴／後綴

use Illuminate\Support\Str;

Str::chopStart('https://laravel.com', 'https://');
// 'laravel.com'

// 以陣列處理多個樣式
Str::chopStart('http://laravel.com', ['https://', 'http://']);
// 'laravel.com'

Str::chopEnd('UserController.php', '.php');
// 'UserController'

遮罩與安全性

`Str::mask()` — 遮罩字串

用於隱藏 email 或電話號碼的部分。

use Illuminate\Support\Str;

// 從第 4 字元起以 '*' 遮罩
Str::mask('[email protected]', '*', 4);
// 'yama**************'

// 只顯示尾端 4 字元（以負值指定 offset）
Str::mask('1234-5678-9012-3456', '*', -4);
// '***************3456'

// 指定範圍遮罩
Str::mask('[email protected]', '*', 3, 5);
// 'yam*****example.com'

`Str::excerpt()` — 依上下文取出字串

用於搜尋結果的 snippet 顯示。

use Illuminate\Support\Str;

$text = 'Laravelは美しいWebアプリケーションを構築するためのPHPフレームワークです。';

Str::excerpt($text, 'PHP', ['radius' => 10]);
// '...ためのPHPフレームワー...'

隨機字串與識別碼

`Str::random()` — 產生隨機字串

用於產生 token 或密碼重設用金鑰。

use Illuminate\Support\Str;

Str::random(32);
// 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'（32 字元英數字）

`Str::uuid()` / `Str::ulid()` — 產生 UUID／ULID

use Illuminate\Support\Str;

(string) Str::uuid();
// '550e8400-e29b-41d4-a716-446655440000'

// 依時序可排序的 UUID (UUIDv7)
(string) Str::uuid7();

// ULID（可排序的 ID）
(string) Str::ulid();
// '01ARZ3NDEKTSV4RRFFQ69G5FAV'

`Str::password()` — 產生安全密碼

use Illuminate\Support\Str;

Str::password(12);
// 包含大寫、小寫、數字、符號的 12 字元隨機字串

`Str::counted()` — 帶數量的單數／複數

依數值轉為單複數，並連同格式化後的數值一併回傳。

use Illuminate\Support\Str;

Str::counted('order', 1);
// '1 order'

Str::counted('order', 1000);
// '1,000 orders'

Fluent 風格也可同樣使用：

Str::of('order')->counted(3);
// '3 orders'

在英文 UI 中顯示筆數（分「1 件」與「2 件以上」）時很方便。逗號分隔的格式會自動套用。

Fluent Strings（method chain）

以 Str::of() 或 str() 起頭會回傳 Stringable 實例，可鏈式呼叫方法。最後要作為字串使用時，用 (string) 轉換或在字串上下文中使用。

use Illuminate\Support\Str;

$result = Str::of('  hello world  ')
    ->trim()
    ->title()
    ->append('!')
    ->toString();
// 'Hello World!'

實用的 method chain 範例

產生部落格文章 slug

use Illuminate\Support\Str;

$slug = Str::of('  My New Blog Post: Part 1  ')
    ->trim()
    ->lower()
    ->slug('-')
    ->limit(50);
// 'my-new-blog-post-part-1'

從 URL 擷取網域

use Illuminate\Support\Str;

$domain = Str::of('https://www.example.com/path/to/page')
    ->after('//')
    ->before('/')
    ->chopStart('www.');
// 'example.com'

使用者輸入的 sanitize

use Illuminate\Support\Str;

$clean = Str::of($userInput)
    ->squish()          // 移除多餘空白
    ->limit(255)        // 限制長度
    ->toString();

從類別名稱產生檔案路徑

use Illuminate\Support\Str;

$path = Str::of('App\Http\Controllers\UserController')
    ->replace('\\', '/')
    ->append('.php')
    ->toString();
// 'App/Http/Controllers/UserController.php'

條件式 method chain（`when()`）

use Illuminate\Support\Str;

$result = Str::of('Laravel')
    ->when($isUppercase, fn ($str) => $str->upper())
    ->append(' Framework');
// $isUppercase 為 true 則 'LARAVEL Framework'
// 為 false 則 'Laravel Framework'

`pipe()` — 插入任意 callback

use Illuminate\Support\Str;

$result = Str::of('my-slug')
    ->pipe(fn ($str) => $str->replace('-', '_'))
    ->upper()
    ->toString();
// 'MY_SLUG'

`Str::of()` 可用主要方法一覽

Fluent Strings 可用的方法與靜態方法幾乎相同。以下為代表性的方法：

use Illuminate\Support\Str;

$str = Str::of('Hello, World!');

$str->length();           // 13
$str->upper();            // 'HELLO, WORLD!'
$str->lower();            // 'hello, world!'
$str->trim();             // 'Hello, World!'
$str->slug();             // 'hello-world'
$str->camel();            // 'hello,World!'（不移除符號）
$str->contains('World'); // true
$str->startsWith('Hello'); // true
$str->endsWith('!');      // true
$str->replace(',', '');   // 'Hello World!'
$str->prepend('>>> ');    // '>>> Hello, World!'
$str->append(' <<<');     // 'Hello, World! <<<'
$str->reverse();          // '!dlroW ,olleH'
$str->wordCount();        // 2

總結

常用 Str 方法一覽

方法	用途
`Str::slug($str)`	產生 URL 友善的 slug
`Str::limit($str, $n)`	依字元數截斷
`Str::contains($str, $needle)`	是否包含字串
`Str::startsWith($str, $needle)`	是否以指定字串開頭
`Str::endsWith($str, $needle)`	是否以指定字串結尾
`Str::replace($search, $replace, $str)`	置換字串
`Str::camel($str)`	轉為 camelCase
`Str::snake($str)`	轉為 snake_case
`Str::kebab($str)`	轉為 kebab-case
`Str::studly($str)`	轉為 StudlyCase
`Str::upper($str)`	轉為大寫
`Str::lower($str)`	轉為小寫
`Str::squish($str)`	移除多餘空白
`Str::after($str, $search)`	取得指定字串之後
`Str::before($str, $search)`	取得指定字串之前
`Str::between($str, $from, $to)`	取得兩字串之間
`Str::mask($str, '*', $index)`	遮罩字串
`Str::random($length)`	產生隨機字串
`Str::uuid()`	產生 UUID
`Str::of($str)`	開始 Fluent 風格

靜態方法 vs Fluent（Str::of）

使用靜態方法的時機：

只做 1〜2 次轉換
簡潔易讀的程式碼

$slug = Str::slug($title);

使用 Fluent（Str::of）的時機：

要一次做 3 個以上的轉換
需含條件分支（when()）
想讓處理由上至下順讀

$slug = Str::of($title)
    ->trim()
    ->lower()
    ->slug()
    ->limit(50);

Str 類別 vs PHP 標準函式

以 Str 類別取代 PHP 的 strtolower()、substr()、str_replace() 等標準函式可獲得：

安全處理多位元組字元（中文／日文）（內部使用 mb_* 函式）
以 method chain 整合處理
不用記引數順序（一致的介面）
統一使用 Laravel 的撰寫風格

​什麼是 Str 類別

​大小寫轉換

​Str::camel() / Str::snake() / Str::kebab() / Str::studly()

​Str::lower() / Str::upper() / Str::title()

​Slug 與 URL

​Str::slug() — 產生 URL 友善的 slug

​用 Str::of() 從 slug 產生到驗證一次完成

​字串截斷

​Str::limit() — 依字元數截斷

​Str::words() — 依單字數截斷

​字串搜尋與確認

​Str::contains() — 是否包含子字串

​Str::startsWith() / Str::endsWith()

​Str::is() — 萬用字元樣式比對

​字串轉換與置換

​Str::replace() — 置換字串

​Str::replaceArray() — 依序以陣列置換

​Str::replaceMatches() — 以正則表達式置換

​Str::remove() — 移除字串

​Str::squish() — 移除多餘空白

​字串前後操作

​Str::before() / Str::after()

​Str::between() — 取得兩字串之間

​Str::start() / Str::finish() — 確保以特定字元開頭／結尾

​Str::chopStart() / Str::chopEnd() — 移除特定前綴／後綴

​遮罩與安全性

​Str::mask() — 遮罩字串

​Str::excerpt() — 依上下文取出字串

​隨機字串與識別碼

​Str::random() — 產生隨機字串

​Str::uuid() / Str::ulid() — 產生 UUID／ULID

​Str::password() — 產生安全密碼

​Str::counted() — 帶數量的單數／複數

​Fluent Strings（method chain）

​實用的 method chain 範例

​條件式 method chain（when()）

​pipe() — 插入任意 callback

​Str::of() 可用主要方法一覽

​總結

什麼是 Str 類別

大小寫轉換

`Str::camel()` / `Str::snake()` / `Str::kebab()` / `Str::studly()`

`Str::lower()` / `Str::upper()` / `Str::title()`

Slug 與 URL

`Str::slug()` — 產生 URL 友善的 slug

用 `Str::of()` 從 slug 產生到驗證一次完成

字串截斷

`Str::limit()` — 依字元數截斷

`Str::words()` — 依單字數截斷

字串搜尋與確認

`Str::contains()` — 是否包含子字串

`Str::startsWith()` / `Str::endsWith()`

`Str::is()` — 萬用字元樣式比對

字串轉換與置換

`Str::replace()` — 置換字串

`Str::replaceArray()` — 依序以陣列置換

`Str::replaceMatches()` — 以正則表達式置換

`Str::remove()` — 移除字串

`Str::squish()` — 移除多餘空白

字串前後操作

`Str::before()` / `Str::after()`

`Str::between()` — 取得兩字串之間

`Str::start()` / `Str::finish()` — 確保以特定字元開頭／結尾

`Str::chopStart()` / `Str::chopEnd()` — 移除特定前綴／後綴

遮罩與安全性

`Str::mask()` — 遮罩字串

`Str::excerpt()` — 依上下文取出字串

隨機字串與識別碼

`Str::random()` — 產生隨機字串

`Str::uuid()` / `Str::ulid()` — 產生 UUID／ULID

`Str::password()` — 產生安全密碼

`Str::counted()` — 帶數量的單數／複數

Fluent Strings（method chain）

實用的 method chain 範例

條件式 method chain（`when()`）

`pipe()` — 插入任意 callback

`Str::of()` 可用主要方法一覽

總結