PHPのsprintf関数の使い方！書式指定で文字列を整形する

2025.07.20

PHPのsprintf関数は、C言語のsprintfと同様に、フォーマット文字列と変数を組み合わせて整形済みの文字列を生成します。
この関数を使用することで、指定された書式文字列に基づいて「変数を整形し、新しい文字列を生成する」ために使用されます。

数値のゼロ埋め、小数点以下の桁数指定、文字列の左右寄せ、日付の整形など、複雑な文字列フォーマットを柔軟に制御したい場合に非常に強力で便利な関数です。
ログ出力、レポート生成、ユーザーへのメッセージ表示など、様々な場面で活用されます。

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

sprintf関数の基本的な構文

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

sprintf(string $format, mixed ...$values): string
  • $format: 書式指定子を含む文字列です。この文字列は、結果の文字列の構造と、$values引数がどのように整形されるかを定義します。
  • ...$values: $format文字列内の書式指定子に対応する値です。複数の値を渡すことができます。

第1引数($format)について

書式文字列は、リテラルテキストと1つ以上の書式指定子で構成されます。
書式指定子は % で始まり、その後にオプションのフラグ、幅、精度、型指定子などが続きます。

第2引数($values)について

書式指定子に対応する値です。
これらの値は、書式指定子によって期待される型（文字列、整数、浮動小数点数など）に自動的に変換されます。

主要な書式指定子

書式指定子は、以下の構造を持ちます。

%[argnum$][flags][width][.precision]type

  • argnum$: オプション。$values 引数の何番目の値を使用するかを指定します（例: 2$ は2番目の引数を使用）。これにより、引数の順序を入れ替えたり、同じ引数を複数回使用したりできます。
  • flags: オプション。出力の調整方法を指定します。
    • -: 左寄せ
    • +: 符号（+または-）を常に表示
    • (スペース): 正の数の前にスペースを挿入
    • 0: 左側をゼロ埋め
    • ': 数字の区切り文字（ロケールによる）
  • width: オプション。出力の最小幅を指定します。
  • .precision: オプション。小数点以下の桁数（浮動小数点数）や、文字列の最大長（文字列）を指定します。
  • type: 必須。引数の型と出力形式を指定します。
    • %: リテラルのパーセント記号
    • b: 整数をバイナリ（2進数）として出力
    • c: 整数をASCII値として文字に出力
    • d: 整数を符号付き10進数として出力
    • e: 浮動小数点数を科学的記法（小文字のe）で出力
    • E: 浮動小数点数を科学的記法（大文字のE）で出力
    • f: 浮動小数点数を浮動小数点数として出力（ロケール対応）
    • F: 浮動小数点数を浮動小数点数として出力（ロケール非対応）
    • g: 浮動小数点数をeまたはfの短い方で出力
    • G: 浮動小数点数をEまたはFの短い方で出力
    • o: 整数を8進数として出力
    • s: 引数を文字列として出力
    • u: 整数を符号なし10進数として出力
    • x: 整数を16進数（小文字）として出力
    • X: 整数を16進数（大文字）として出力

sprintf関数を使ってみる

sprintf関数を使って、動作を確認してみます。

例1：基本的な文字列と数値の整形

文字列に文字と数値を埋め込んだ例です。

<?php
$name = "Alice";
$age = 30;

// 文字列と整数を挿入
$message = sprintf("My name is %s and I am %d years old.", $name, $age);
echo $message . PHP_EOL;
// 出力: My name is Alice and I am 30 years old.
?>

sprintf関数の第1引数に渡している文字列が、基になる書式指定子込みの文字列です。
書式指定子の「%s」のところに$name変数(文字列)が埋め込まれて、「%d」のところに$age変数(数値)が埋め込まれます。

$message変数で、作成した文字列を受け取って、出力すると変数の内容が埋め込まれたことが確認できました。

例2：数値のゼロ埋めと小数点以下の桁数指定

数値のゼロ埋めと、小数点以下2桁表示を試してみました。

<?php
$id = 5;
$price = 123.456;

// IDを3桁でゼロ埋め、価格を小数点以下2桁で表示
$formattedOutput = sprintf("ID: %03d, Price: %.2f", $id, $price);
echo $formattedOutput . PHP_EOL;
// 出力: ID: 005, Price: 123.46
?>

書式指定子文字列として「%03d」と「3」の前に「0」を指定することで、3桁で0埋めとなります。
また、%.2fで小数点以下2桁までを表示するようにしています。

例3：文字列の幅指定と左右寄せ

文字列の左右寄せについてです。

<?php
$item = "Laptop";
$stock = 15;

// itemを左寄せ10文字、stockを右寄せ5文字で表示
$reportLine = sprintf("%-10s | %5d units", $item, $stock);
echo $reportLine . PHP_EOL;
// 出力: Laptop     |    15 units
?>

「%-10s」とすることで、10文字の幅で表示され、余った右のほうはスペースで埋められます。
「Laptop」を出力して、残った4文字分は右側がスペースで埋まりました。

また「%5d」とすることで、左からスペースで埋めて5文字の幅で文字が表示されます。
「15」を表示したあとに、左3文字分がスペースで埋まりました。

例4：引数の順序指定

同じ引数を複数回使用したり、引数の順序を入れ替えたりできます。

<?php
$product = "Widget";
$version = "1.2.3";

// 2番目の引数を最初に、1番目の引数を2番目に表示
$info = sprintf('Version %2$s of %1$s is available.', $product, $version);
echo $info . PHP_EOL;
// 出力: Version 1.2.3 of Widget is available.

// 同じ引数を複数回使用
$repeated = sprintf('The %1$s is great! I really love the %1$s.', "PHP");
echo $repeated . PHP_EOL;
// 出力: The PHP is great! I really love the PHP.
?>

この例では、書式指定子にargnum$という形式を使用しています。

「%2$s」は、sprintf関数の引数の2番目（この場合は$version）を文字列として埋め込むことを意味します。
「%1$s」は、引数の1番目（この場合は$product）を文字列として埋め込むことを意味します。
このようにargnum$を使うことで、引数を渡す順序とフォーマット文字列内で利用する順序を自由に指定できます。

また、2つ目の例では「%1$s」を複数回使用しています。
これは、同じ引数（この場合は”PHP”）をフォーマット文字列内で何度でも再利用できることを示しています。
このように同じものを使うことで、冗長な引数渡しを避けることができます。

また「%1$s」などと「$s」を使う場合に、ダブルコーテーションで文字列を囲むと、変数として判定されてしまうので注意が必要です。

例5：様々な数値形式

10進数を、異なる基数（16進数、8進数、2進数）で表示する例です。

<?php
$number = 255; // 10進数

// 10進数、16進数（小文字）、8進数、バイナリで表示
$formats = sprintf("Decimal: %d, Hex (lower): %x, Octal: %o, Binary: %b", $number, $number, $number, $number);
echo $formats . PHP_EOL;
// 出力: Decimal: 255, Hex (lower): ff, Octal: 377, Binary: 11111111
?>

この例では、同じ数値$number（10進数の255）を異なる数値形式で表示しています。
「%d」は、引数を符号付き10進数として表示します。
「%x」は、引数を小文字の16進数（hexadecimal）として表示します。
「%o」は、引数を8進数（octal）として表示します。
「%b」は、引数を2進数（binary）として表示します。

これらの書式指定子を使うことで、数値データを様々な基数で整形して出力することが可能になります。

sprintf関数を使う際の注意点

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

引数の数と型

$format文字列内の書式指定子の数と、$values 引数の数が一致している必要があります。
また、書式指定子と引数の型が一致しない場合、PHPは可能な限り型変換を試みますが、予期せぬ結果になる可能性があります（例: "%d" に文字列を渡すなど）。

セキュリティ

ユーザーからの入力を直接 $format文字列として使用しないでください。
悪意のある書式指定子を挿入されることで、情報漏洩やクラッシュにつながる可能性があります。
ユーザー入力は必ず $values 引数として渡すようにしてください。

ロケール依存

fやFなどの浮動小数点数書式指定子や、数字の区切り文字フラグ (') は、現在のロケール設定に影響されることがあります。
特定のロケールで表示したい場合は、setlocale関数でロケールを設定するか、NumberFormatterクラスのような国際化機能を検討してください。

エラーハンドリング

書式指定子が不正な場合や、引数の数が合わない場合、PHPは警告（Warning）を発します。
本番環境ではこれらの警告を適切に処理する必要があります。

まとめ

PHPのsprintf関数は、文字列の整形とフォーマットを強力に制御するための非常に便利なツールです。
数値のゼロ埋め、小数点以下の桁数指定、文字列の左右寄せ、異なる基数での数値表示など、多様なニーズに対応できます。

書式指定子の構造と意味を理解し、引数の数と型に注意しましょう。
特にセキュリティ上の考慮事項（ユーザー入力を$formatに直接使わない）を守ることで、sprintf関数を効果的に活用し、より見やすく、堅牢な出力を生成できるでしょう。

PHP
yasuaki

コメント