PHPのstr_pad関数の使い方！文字列を指定した長さまで埋める

PHPのstr_pad関数は、文字列を指定した長さになるまで、別の文字列でパディング（埋め合わせ）するために使用されます。

この関数は、レポートやリスト、表形式のデータをきれいに整形したい場合や、固定長のデータ形式を扱う場合に便利です。
文字列の左右どちらから埋めるか、または両側から均等に埋めるか、そして何で埋めるか（パディング文字列）を細かく制御できます。

この記事では、str_pad関数の基本的な使い方、引数、戻り値、主要な使用例、そして使用する際の重要な注意点について解説します。

str_pad関数の基本的な構文

str_pad関数の基本的な構文は以下の通りです。

str_pad(string $string, int $length, string $pad_string = " ", int $pad_type = STR_PAD_RIGHT): string
  • $string: 必須。パディングを施したい元の文字列です。
  • $length: 必須。最終的な文字列の長さです。元の文字列がすでにこの長さ以上の場合、何も変更されません。
  • $pad_string: オプション。パディングに使用する文字列です。デフォルトはスペース（）です。
  • $pad_type: オプション。パディングの方向を指定する定数です。
    • STR_PAD_RIGHT: 右側を埋めます（デフォルト）。
    • STR_PAD_LEFT: 左側を埋めます。
    • STR_PAD_BOTH: 両側を均等に埋めます。

str_padの引数

str_pad関数の引数についてです。

第1引数(元の文字列)

  • パディングの対象となる文字列です。

第2引数(最終的な長さ)

  • パディング後の合計の文字列長を整数で指定します。
  • この値が元の文字列の長さ以下の場合、元の文字列はそのまま返されます。

第3引数(パディング文字列)

  • パディングに使用する文字列です。デフォルトはスペース1文字です。

第4引数(パディング方向)

  • STR_PAD_RIGHT: 文字列の右側にパディングを追加します。
  • STR_PAD_LEFT: 文字列の左側にパディングを追加します。
  • STR_PAD_BOTH: 文字列の両側にパディングを追加します。左右のパディング数が均等にならない場合は、右側が1文字多くなります。

str_padの戻り値

パディングされた新しい文字列が返されます。

重要な点

  • パディング文字列が1文字ではない場合、パディングは$pad_stringの文字を繰り返して行われます。
  • $pad_typeがSTR_PAD_BOTHの場合、左右のパディング文字数が均等にならない場合は、右側が余分な1文字を受け取ります。

str_pad関数を実際に使ってみる

str_pad関数を実際に使って、動作を確認してみます。

例1：デフォルトの右側パディング

最も一般的な使い方で、文字列の右側をスペースで埋めます。

<?php
$input = "Apple";
$padded = str_pad($input, 10);

echo "'{$padded}'" . PHP_EOL;
// 出力: 'Apple     '
echo strlen($padded) . PHP_EOL;
// 出力: 10

$input変数にAppleという文字列を入れて、次の処理でstr_pad関数を使っています。
第1引数に$input変数を渡して、第2引数に10を指定しています。

これで"Apple"が" "という5つのスペースで埋められ、合計10文字になっています。

例2：左側パディング（ゼロ埋め）

数値データの桁数を揃える際などによく使われる左側パディングです。

<?php
$input = "123";
// 5桁になるまで、左側を '0' で埋める
$padded = str_pad($input, 5, '0', STR_PAD_LEFT);

echo "'{$padded}'" . PHP_EOL;
// 出力: '00123'

$input変数に123という数字を入れて、次の処理でstr_pad関数を使っています。
STR_PAD_LEFTを指定しているので、左側から埋められます。

今回は5桁で、0埋めするように指定しているので、結果は「00123」となります。
左埋めは銀行口座番号や商品コードなど、固定長で扱いたい場合に非常に便利です。

例3：両側パディング（中央寄せ）

文字列を中央に配置したような効果を得たい場合に便利です。

<?php
$title = "Welcome";
// 20文字になるまで、両側を '-' で埋める
$paddedTitle = str_pad($title, 20, '-', STR_PAD_BOTH);

echo "'{$paddedTitle}'" . PHP_EOL;
// 出力: '------Welcome-------'
echo strlen($paddedTitle) . PHP_EOL;
// 出力: 20

$shortTitle = "Hi";

// 20文字になるまで、両側を '-' で埋める
$paddedShortTitle = str_pad($shortTitle, 20, '-', STR_PAD_BOTH);

echo "'{$paddedShortTitle}'" . PHP_EOL;
// 出力: '---------Hi---------'

echo strlen($paddedShortTitle) . PHP_EOL;
// 出力: 20

str_pad関数は、文字数が奇数と偶数で異なるパディングの振る舞いをします。
STR_PAD_BOTHで左右均等に埋める場合、パディングに必要な文字数が奇数であれば、右側が1文字多くなります。

「Welcome」は文字列が奇数なので、右側が1文字多くなっています。
それに比べて、「Hi」は偶数なので、左右を埋めるために使った文字が9文字ずつで揃っています。

例4：CSVファイルの整形

固定長のCSVファイルを作成する際など、データの長さを揃えたい場合にも便利です。

<?php
$items = [
    ['name' => 'Pen', 'price' => 1.50],
    ['name' => 'Notebook', 'price' => 3.25],
    ['name' => 'Eraser', 'price' => 0.75]
];

echo "Product    | Price " . PHP_EOL;
echo "-----------+-------" . PHP_EOL;

foreach ($items as $item) {
    $paddedName = str_pad($item['name'], 10, ' ', STR_PAD_RIGHT);
    $paddedPrice = str_pad($item['price'], 5, ' ', STR_PAD_LEFT);
    echo "{$paddedName} | {$paddedPrice}" . PHP_EOL;
}
/*
出力:
Product    | Price 
-----------+-------
Pen        |   1.5
Notebook   |  3.25
Eraser     |  0.75
*/

$itemsという二次元配列を作成して、内容をテーブル形式で出力しています。
$paddedNameに名前を右にスペースを埋めて、格納しています。
$paddedPriceに値段を左にスペースを埋めて、格納しています。

それぞれを出力すると、列がきれいに揃ったテキストベースの表を作成できます。

str_pad関数を使う際の重要な注意点

str_pad関数を使う際の注意点です。

マルチバイト文字（UTF-8など）

str_pad関数はバイト単位で動作し、マルチバイト文字エンコーディングを正しく認識しません。
例えば、UTF-8の日本語1文字を1バイトとして数えてしまうため、意図した長さにならないことがあります。

マルチバイト文字列を扱う場合は、mb_str_pad関数を使用する必要があります。
これはmbstringエクステンションに属します。

<?php
// mb_str_pad関数がない場合、このコードは動きません
// mbstringエクステンションをインストール・有効化する必要があります

$input_mb = "りんご"; // 日本語3文字
$padded_mb = mb_str_pad($input_mb, 10, ' ', MB_PAD_RIGHT, 'UTF-8');

echo "'{$padded_mb}'" . PHP_EOL;
// 出力: 'りんご      ' (正しく10文字にパディングされる)
echo mb_strlen($padded_mb, 'UTF-8') . PHP_EOL;
// 出力: 10
?>

パディング文字列が長い場合

$pad_stringが1文字以上の場合、str_pad関数はパディングに必要な部分だけを切り取って使用します。
例えば、'.-'でパディングしたい場合、必要なパディング文字数が3文字なら'.-.'のように使用されます。

$lengthが元の文字列より短い場合

$lengthが元の文字列の長さ以下の場合、str_pad関数は元の文字列をそのまま返し、切り捨ては行いません。
文字列を切り捨てたい場合は、substrなどの関数を使用する必要があります。

まとめ

PHPのstr_pad関数は、文字列を指定した長さまでパディングするためのシンプルで効果的なツールです。
データの整形、レポートの生成、固定長データの作成など、様々な場面で活用できます。

ただし、マルチバイト文字を扱う場合は、必ずmb_str_pad関数を使用するという点が最も重要です。
また、パディングの方向（左右・両側）を適切に指定することで、出力のフォーマットを細かく制御できます。

これらのポイントを踏まえ、str_pad関数を効果的に活用し、PHPアプリケーションにおける文字列の整形をより効率的に行いましょう。

PHP
yasuaki

コメント