정의 및 사용 방법

PHP 버전
8.3.0

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

이 함수는 str_pad() 함수와 거의 동일한 기능을 하지만, 한글, 일본어, 중국어와 같은 multi-byte 문자열에서 안전하게 작동하는 기능을 제공한다는 큰 차이점이 있습니다.

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

특징

  • multi-byte(멀티바이트)를 지원합니다.
  • 주로 멀티바이트 문자열로 된 데이터 정렬이나 특정 멀티바이트 문자열의 길이 형식 맞추기에 유용하게 사용됩니다.
  • PHP 8.3.0에서 도입된 함수로 PHP 8.3.0 이전의 버전에서는 호환되지 않습니다.
이 함수의 구문을 시각화하면 다음과 같습니다. 
mb_str_pad(주어진_문자열, 지정한_길이[, 채우길_원하는_문자열[, 채우는_위치][, 인코딩]]);

기본 예제

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

$str = '안녕하세요';  // 주어진 문자열(문자열의 길이: 5)

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

// 지정한 길이: 10, 채우길 원하는 문자열: "*", 채우는_위치: 왼쪽, 인코딩: UTF-8
echo mb_str_pad($str, 10, '*', STR_PAD_LEFT, 'UTF-8'); // 출력: '*****안녕하세요'

// 지정한 길이: 10, 채우길 원하는 문자열: "*", 채우는_위치: 오른쪽, 인코딩: UTF-8
echo mb_str_pad($str, 10, '*', STR_PAD_RIGHT, 'UTF-8'); // 출력: '안녕하세요*****'

// 지정한 길이: 10, 채우길 원하는 문자열: "*", 채우는_위치: 양쪽, 인코딩: UTF-8
echo mb_str_pad($str, 10, '*', STR_PAD_BOTH, 'UTF-8'); // 출력: '**안녕하세요***'

// 지정한 길이: 10, 채우길 원하는 문자열: 공백 문자, 채우는_위치: 왼쪽, 인코딩: UTF-8
echo mb_str_pad($str, 10, ' ', STR_PAD_LEFT, 'UTF-8'); // 출력: '     안녕하세요'

// 지정한 길이: 10, 채우길 원하는 문자열: '*@', 채우는_위치: 왼쪽, 인코딩: UTF-8
echo mb_str_pad($str, 10, '*@', STR_PAD_LEFT, 'UTF-8'); // 출력: '*@*@*안녕하세요'

// 지정한 길이: 4, 채우길 원하는 문자열: "*", 채우는_위치: 왼쪽, 인코딩: UTF-8
// 지정한 길이가 문자열 길이보다 작으면 주어진 문자열이 그대로 반환됩니다.
echo mb_str_pad($str, 4, '*', STR_PAD_LEFT, 'UTF-8'); // 출력: '안녕하세요'

구문

PHP 
mb_str_pad(
    string $string,
    int $length,
    string $pad_string = " ",
    int $pad_type = STR_PAD_RIGHT,
    ?string $encoding = null
): string

매개변수

mb_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가 지정됩니다.
$encoding 옵션. 문자열의 인코딩을 지정합니다.
기본값은 null이며, 생략하거나 null을 전달하면 내부 문자 인코딩 값이 사용됩니다.
  • 내부 문자 인코딩이 표준 인코딩인 'UTF-8'일 경우에는 별도로 지정하지 않아도 됩니다.
  • 내부 인코딩이 다른 값이라면, 일관된 처리 결과를 위해 표준 인코딩인 'UTF-8'을 명시적으로 지정하세요.

반환 값

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

매개변수와 반환 값 예시

$pad_string의 기본 동작 한눈에 보기
PHP 
mb_str_pad('안녕하세요', 10, '0', STR_PAD_LEFT, 'UTF-8');
// '00000안녕하세요'
// 왼쪽에서부터 $pad_string('0')을 반복하여 목표 길이를 맞춥니다.

mb_str_pad('안녕하세요', 10, '123', STR_PAD_LEFT, 'UTF-8');
// '123123안녕하세요' → X
// 실제 결과: '12312안녕하세요'
// $pad_string은 필요한 길이만큼만 잘려서 사용됩니다.

mb_str_pad('안녕하세요', 4, '*', STR_PAD_LEFT, 'UTF-8');
// '안녕하세요'
// 지정한 길이가 문자열 길이보다 작으면 주어진 문자열이 그대로 반환됩니다.
$pad_string에 여러 문자로 구성된 문자열

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

PHP 
$str = '안녕하세요'; // 주어진 문자열(문자열의 길이: 5)

// 지정한 길이: 10, 채우길 원하는 문자열: "*@"
$result_str = mb_str_pad($str, 10, '*@', STR_PAD_LEFT, 'UTF-8');
echo $result_str; // 출력: '*@*@*안녕하세요'

활용 예제

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

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

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

PHP 
// 제품 리스트 예제
$items = [
    [ 'name' => '커피', 'price' => 4500 ],
    [ 'name' => '도넛',  'price' => 2000 ],
    [ 'name' => '라떼',  'price' => 5000 ]
];

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

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

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

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

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

/*
출력:
--- PRODUCT LIST ---
커피........  4500원
도넛........  2000원
라떼........  5000원
*/

참고문헌

같이 보기