정의 및 사용 방법

PHP 버전
4.0.1+

str_pad() 함수는 주어진 문자열이 지정한 길이보다 짧으면, 부족한 길이만큼 원하는 문자열을 채워(padding, 속을 채우다) 지정한 길이로 맞춥니다.

주로 문자열로 된 데이터 정렬이나 특정 문자열의 길이 형식 맞추기에 유용하게 사용됩니다.

이 함수의 구문을 시각화하면 다음과 같습니다. 
str_pad(주어진_문자열, 지정한_길이[, 채우길_원하는_문자열[, 채우는_위치]]);

기본 예제

PHP 
/* str_pad(주어진_문자열, 지정한_길이[, 채우길_원하는_문자열[, 채우는_위치]]); */

$str = 'hello';  // 주어진 문자열(문자열의 길이: 5)

/////////////////////////////////////////////////

// 지정한 길이: 10, 채우길 원하는 문자열: "*", 채우는_위치: 왼쪽
echo str_pad($str, 10, '*', STR_PAD_LEFT); // 출력: '*****hello'

// 지정한 길이: 10, 채우길 원하는 문자열: "*", 채우는_위치: 오른쪽
echo str_pad($str, 10, '*', STR_PAD_RIGHT); // 출력: 'hello*****'

// 지정한 길이: 10, 채우길 원하는 문자열: "*", 채우는_위치: 양쪽
echo str_pad($str, 10, '*', STR_PAD_BOTH); // 출력: '**hello***'

// 지정한 길이: 10, 채우길 원하는 문자열: 공백 문자 (" ", U+0020), 채우는_위치: 왼쪽
echo str_pad($str, 10, ' ', STR_PAD_LEFT); // 출력: '     hello'

// 지정한 길이: 10, 채우길 원하는 문자열: '*@', 채우는_위치: 왼쪽
echo str_pad($str, 10, '*@', STR_PAD_LEFT); // 출력: '*@*@*hello'

// 지정한 길이: 4, 채우길 원하는 문자열: "*", 채우는_위치: 왼쪽
// 지정한 길이가 문자열 길이보다 작으면 주어진 문자열이 그대로 반환됩니다.
echo str_pad($str, 4, '*', STR_PAD_LEFT); // 출력: 'hello'

주의하세요!
str_pad() 함수는 주어진 문자열이나 채우길 원하는 문자열이 한글과 같은 multi-byte 문자열일 경우 올바르게 처리되지 않습니다. 이런 경우에는 mb_str_pad() 함수를 사용하세요.

부연설명
영어, 숫자 등은 1 byte이지만, 한글이나 일본어, 중국어 등은 2 byte 이상입니다. 2 byte 이상의 바이트로 표현되는 것을 "multi-byte(멀티바이트)"라고 합니다.

구문

PHP 
str_pad(
    string $string,
    int $length,
    string $pad_string = " ",
    int $pad_type = STR_PAD_RIGHT
): string

매개변수

str_pad() 함수의 매개변수
$string str_pad() 함수를 적용할 주어진 문자열입니다.
$length 반환될 문자열이 가져야 하는 최종 목표 길이입니다. 이 길이는 정수 타입으로 지정해야 합니다.
길이 값이 음수이거나 $string의 길이보다 작거나 같으면 $string이 그대로 반환됩니다.
$pad_string 옵션.
채우길 원하는 문자열입니다.
  • $pad_string에는 하나 이상의 문자로 구성된 문자열을 지정할 수 있습니다.
  • 주어진 문자열($string)과 합친 길이가 $length에 도달할 때까지, 지정된 채우는 위치에 $pad_string이 반복해서 추가됩니다.
  • 합친 길이가 $length를 초과하면, 초과되는 부분은 $pad_string의 끝에서 자릅니다.
  • $pad_string을 지정하지 않으면 기본값은 공백 문자 ('', U+0020)입니다.
$pad_type 옵션.
채우는 위치에 대한 상수 옵션입니다. 옵션은 다음과 같습니다.
  • STR_PAD_LEFT: $string의 왼쪽을 채웁니다.
  • STR_PAD_RIGHT: $string의 오른쪽을 채웁니다.
  • STR_PAD_BOTH: $string의 양쪽을 채웁니다. 단, 채워야 할 패딩 개수가 홀수일 경우 (예: 5개), 오른쪽(RIGHT)에 한 문자가 더 추가됩니다.
$pad_type를 지정하지 않으면 기본값으로 STR_PAD_RIGHT가 지정됩니다.

반환 값

주어진 문자열($string)이 지정한 길이($length)보다 짧으면, 지정된 채우는 위치에 부족한 길이만큼 원하는 문자열($pad_string)을 채워 지정한 길이로 맞춘 문자열로 반환합니다. 그렇지 않으면 주어진 문자열($string)을 그대로 반환합니다.

매개변수와 반환 값 예시

$pad_string의 기본 동작 한눈에 보기
PHP 
str_pad('hello', 10);
// 'hello     '
// $pad_string을 생략하면 공백으로 채웁니다.
// $pad_type을 생략하면 오른쪽을 채웁니다.

str_pad('hello', 10, '0', STR_PAD_LEFT);
// '00000hello'
// 왼쪽에서부터 $pad_string('0')을 반복하여 목표 길이를 맞춥니다.

str_pad('hello', 10, '123', STR_PAD_LEFT);
// '123123hello' → X
// 실제 결과: '12312hello'
// $pad_string은 필요한 길이만큼만 잘려서 사용됩니다.

str_pad('hello', 4, '*', STR_PAD_LEFT);
// 'hello'
// 지정한 길이가 문자열 길이보다 작으면 주어진 문자열이 그대로 반환됩니다.
$pad_string에 여러 문자로 구성된 문자열

$pad_string에 여러 문자로 구성된 문자열로 지정할 경우 주어진 문자열($string)과 합친 길이가 $length에 도달할 때까지 주어진 문자열의 시작 부분부터 반복해서 채웁니다. 합친 길이가 $length를 초과하면, 초과되는 부분은 $pad_string의 끝에서 자릅니다.

PHP 
$str = 'hello'; // 주어진 문자열(문자열의 길이: 5)

// 지정한 길이: 10, 채우길 원하는 문자열: "*@"
$result_str = str_pad($str, 10, '*@', STR_PAD_LEFT);
echo $result_str; // 출력: '*@*@*hello'
$pad_string을 지정하지 않았을 경우

$pad_string을 지정하지 않으면 기본값은 공백 문자 ('', U+0020)입니다.

PHP 
$str = 'hello'; // 주어진 문자열(문자열의 길이: 5)

// 지정한 길이: 10, 채우길 원하는 문자열을 지정하지 않음
$result_str = str_pad($str, 10);
echo $result_str; // 출력: 'hello     '

활용 예제

str_pad() 함수는 주로 문자열로 된 데이터 정렬이나 특정 문자열의 길이 형식 맞추기에 유용하게 사용됩니다.

숫자 앞에 0을 채워 고정 길이 형식 만들기

(예: 주문번호, 회원번호 등)

PHP 
// 주문 번호를 항상 6자리로 맞추기
$order_id = '351';
echo str_pad($order_id, 6, '0', STR_PAD_LEFT); 
// 출력: '000351'

목록 또는 테이블 데이터 정렬 (컬럼 너비 맞추기)

데이터 목록이나 테이블을 콘솔 또는 고정 폭 글꼴(Monospace) 환경에 출력할 때, 각 항목의 길이를 str_pad() 함수를 사용하여 맞추면 깔끔하게 정렬된 형태로 표시할 수 있습니다. 이는 특히 파일 목록이나 콘솔 애플리케이션의 UI를 만들 때 유용합니다.

PHP 
// 제품 리스트 예제
$items = [
    [ 'name' => 'Coffee', 'price' => 4500 ],
    [ 'name' => 'Donut',  'price' => 2000 ],
    [ 'name' => 'Latte',  'price' => 5000 ]
];

// 컬럼 너비 지정 (제품명 10자, 가격 5자)
$nameWidth  = 10;
$priceWidth = 5;
$fillChar   = '.';

echo '--- PRODUCT LIST ---' . "\n";

foreach ($items as $item) {
    // 제품명: 뒤쪽을 '.'으로 채워 10자 확보
    $paddedName = str_pad($item['name'], $nameWidth, $fillChar, STR_PAD_RIGHT);

    // 가격: 앞쪽을 공백으로 채워 5자 확보
    $paddedPrice = str_pad((string)$item['price'], $priceWidth, ' ', STR_PAD_LEFT);

    // 출력: "Coffee.... 4500원" 형태
    echo $paddedName . ' ' . $paddedPrice . '원' . "\n";
}

/*
출력:
--- PRODUCT LIST ---
Coffee....  4500원
Donut.....  2000원
Latte.....  5000원
*/

참고문헌

같이 보기