문자열 조작 (Str 클래스) - Knowledge of Laravel

Str 클래스란

Illuminate\Support\Str 클래스는 문자열 조작을 위한 풍부한 메서드를 제공합니다. PHP의 표준 문자열 함수를 개별로 호출하는 대신에, 통일된 인터페이스로 직관적으로 문자열을 처리할 수 있습니다. Laravel의 문자열 조작에는 2개의 스타일이 있습니다.

정적 메서드 스타일: Str::slug($title, '-') — 단발의 조작에 적합합니다
Fluent 스타일 (메서드 체인): 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() 글로벌 헬퍼 함수는 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'

슬러그와 URL

`Str::slug()` — URL 프렌들리한 슬러그를 생성

기사나 페이지의 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'

한국어를 포함하는 경우는 슬러그가 비게 될 수 있습니다. 한국어의 슬러그를 사용하고 싶은 경우는, 별도 로마자 변환 라이브러리를 조합하거나, ID나 타임스탬프를 URL에 사용하는 것을 검토해 주세요.

`Str::of()`로 슬러그 생성부터 검증까지 일괄 처리

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은 아름다운 웹 애플리케이션을 만들기 위한 PHP 프레임워크입니다.';

// 20문자로 자르기 (기본으로 말미에 "..."를 추가)
Str::limit($text, 20);
// 'Laravel은 아름다운 웹 애플리케...'

// 말미 문자열을 커스터마이즈
Str::limit($text, 20, ' → 계속 읽기');
// 'Laravel은 아름다운 웹 애플리케 → 계속 읽기'

// 단어의 도중에 자르지 않음 (영어 텍스트용)
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]/', '', '(02) 1234-5678');
// '0212345678'

// 클로저로 치환 내용을 동적으로 생성
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('test@example.com', '@');
// 'test'

// 지정 문자열보다 뒤의 부분
Str::after('test@example.com', '@');
// 'example.com'

// 마지막의 출현 개소를 기준으로 함
Str::afterLast('App\Http\Controllers\UserController', '\\');
// 'UserController'

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

`Str::between()` — 2개의 문자열 사이를 취득

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()` — 문자열을 마스크

메일 주소나 전화번호의 일부를 감추는 처리에 사용합니다.

use Illuminate\Support\Str;

// 4문자째 이후를 '*'로 마스크
Str::mask('hong@example.com', '*', 4);
// 'hong************'

// 말미 4문자만 표시 (음의 값으로 오프셋)
Str::mask('1234-5678-9012-3456', '*', -4);
// '***************3456'

// 범위를 지정하여 마스크
Str::mask('hong@example.com', '*', 3, 5);
// 'hon*****xample.com'

`Str::excerpt()` — 문맥 첨부로 문자열을 뽑아냄

검색 결과의 스니펫 표시 등에 사용합니다.

use Illuminate\Support\Str;

$text = 'Laravel은 아름다운 웹 애플리케이션을 구축하기 위한 PHP 프레임워크입니다.';

Str::excerpt($text, 'PHP', ['radius' => 10]);
// '...위한 PHP 프레임워크입...'

랜덤 문자열과 식별자

`Str::random()` — 랜덤 문자열을 생성

토큰이나 비밀번호 리셋용의 키를 생성할 때에 사용합니다.

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 (메서드 체인)

Str::of() 또는 str()로 시작하면, Stringable 인스턴스가 반환되며, 메서드를 체인할 수 있습니다. 최종적으로 문자열로서 사용하고 싶은 경우는 (string)으로 캐스트하거나, 문자열 컨텍스트로 사용합니다.

use Illuminate\Support\Str;

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

실용적인 메서드 체인의 예

블로그 기사의 슬러그 생성

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'

사용자 입력의 새니타이즈

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'

조건부 메서드 체인 (`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()` — 임의의 콜백을 끼움

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 프렌들리한 슬러그 생성
`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)`	2문자열 사이를 취득
`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 표준 함수

PHP의 strtolower(), substr(), str_replace() 등의 표준 함수 대신에 Str 클래스를 사용함으로써:

멀티바이트 문자(한국어)를 안전하게 다룰 수 있음 (mb_* 함수를 내부에서 사용)
메서드 체인으로 처리를 정리할 수 있음
인수의 순서를 외우지 않아도 됨 (일관된 인터페이스)
Laravel의 코드 스타일에 통일할 수 있음

마지막 수정일 2026년 7월 13일

​Str 클래스란

​케이스 변환

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

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

​슬러그와 URL

​Str::slug() — URL 프렌들리한 슬러그를 생성

​Str::of()로 슬러그 생성부터 검증까지 일괄 처리

​문자열의 자르기

​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() — 2개의 문자열 사이를 취득

​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 (메서드 체인)

​실용적인 메서드 체인의 예

​조건부 메서드 체인 (when())

​pipe() — 임의의 콜백을 끼움

​Str::of()에서 사용할 수 있는 주요 메서드 일람

​정리

Str 클래스란

케이스 변환

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

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

슬러그와 URL

`Str::slug()` — URL 프렌들리한 슬러그를 생성

`Str::of()`로 슬러그 생성부터 검증까지 일괄 처리

문자열의 자르기

`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()` — 2개의 문자열 사이를 취득

`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 (메서드 체인)

실용적인 메서드 체인의 예

조건부 메서드 체인 (`when()`)

`pipe()` — 임의의 콜백을 끼움

`Str::of()`에서 사용할 수 있는 주요 메서드 일람

정리