フォーマットされた文字列をストリームに書き込む

# vfprintf

(PHP 5, PHP 7, PHP 8)

vfprintf — フォーマットされた文字列をストリームに書き込む

### 説明

function vfprintf(resource `$stream`, string `$format`, array `$values`): int

`format` によって作成された文字列を `stream` で指定したストリームに書き込みます。

fprintf() と同様の動作をしますが、 可変引数ではなく引数の配列を受け取って処理します。

### パラメータ

`stream`

`format`
  0個以上のディレクティブで構成されるフォーマット文字列: 変換結果に直接コピーされる通常文字列 (`%` は除きます) と、変換仕様。 これらのいずれも、自分が持つパラメータを取得します。 変換の仕様は、以下のプロトタイプに従います: `%[argnum$][flags][width][.precision]specifier`.

  ##### Argnum

  何番目の引数を変換の対象にするかを指定するために、 数値の後にドル記号 `$` を続けます。

  ##### Flags

  フラグ | 説明
  --- | ---
  `-` | 与えられたフィールドの幅を左寄せにします。 右寄せがデフォルトです。
  `+` | 正の数値の前に付ける `+` 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
  `` (space) | スペースに変換される詰め物です。 これがデフォルトです。
  `0` | 数値の左側を0埋めします。 `s` 指定子を使うと、 右側にも0埋めできます。
  `'`(char) | 指定された (char) で埋めます。

  ##### Width

  (最小で)何文字がこの変換結果に含まれるかを数値で指定するか、 `*` を指定します。 `*` を指定した場合、 指定子によってフォーマットされる値の前に、 幅を追加の数値として指定します。

  ##### Precision

  ピリオド `.` の後に数値を続けるか、 `*` を続けますが、 その意味は指定子に依存します:

  - `e`, `E`, `f` と `F` 指定子の場合: 小数点の後に表示する桁数 (デフォルトでは、この値は6です)
  - `g`, `G`, `h`, `H` 指定子の場合: 表示する最大の有効桁数
  - `s` 指定子の場合: 文字列を切り捨てる時点、つまり、文字列の最大の長さを設定します。

  > 注意: 明示的に精度を指定せず、ピリオドを指定した場合、精度は0として扱われます。 `*` を使った場合、 精度は指定子によってフォーマットされる値の前に、 追加の数値として指定します。

  指定子の一覧
  指定子 | 説明
  --- | ---
  `%` | 文字通り、パーセント文字です。 引数は不要です。
  `b` | 引数は整数として扱われ、2進数値として表現されます。
  `c` | 引数は整数として扱われ、ASCII文字として表現されます。
  `d` | 引数は整数として扱われ、(符号付き)10進数値として表現されます。
  `e` | 引数は科学的記法で表現された値(e.g. 1.2e+2)として扱われます。
  `E` | `e` 指定子に似ていますが、 大文字を使います(e.g. 1.2E+2)
  `f` | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮します)。
  `F` | 引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮しません)。
  `g` | 汎用フォーマット P を精度を表す、ゼロでない値とします。 精度が省略された場合、Pの値は6です。 精度に0を指定した場合、Pの値は1になります。 この場合、 `E` 指定子の変換結果は、 X乗になります。 P > X ≥ −4 の場合、`E` 指定子の変換結果となり、精度は、P − (X + 1) になります。 そうでない場合、`e` 指定子の変換結果となり、 精度は、P - 1 になります。
  `G` | `g` 指定子に似ていますが、 `E` と `f` を使います。
  `h` | `g` 指定子に似ていますが、 `F` を使います。 PHP 8.0.0 以降で利用可能です。
  `H` | `g` 指定子に似ていますが、 `E` と `F` を使います。 PHP 8.0.0 以降で利用可能です。
  `o` | 引数は整数として扱われ、8進数値として表現されます。
  `s` | 引数は文字列として扱われ、文字列として表現されます。
  `u` | 引数は整数として扱われ、符号なし10進数値として表現されます。
  `x` | 引数は整数として扱われ、16進数値(小文字)として表現されます。
  `X` | 引数は整数として扱われ、16進数値(大文字)として表現されます。

  警告

  `c` 指定子はパディングと幅を無視します

  警告

  文字列と width 指定子を、1文字の表現に1バイト以上必要な文字セットと一緒に使おうとすると、 期待しない結果になるかもしれません。

  値は、指定子の型に合うように強制されます:

  型のハンドリング
  型 | 指定子
  --- | ---
  string | `s`
  int | `d`, `u`, `c`, `o`, `x`, `X`, `b`
  float | `e`, `E`, `f`, `F`, `g`, `G`, `h`, `H`

`values`

### 戻り値

出力された文字列の長さを返します。

### エラー / 例外

PHP 8.0.0 以降では、 引数の数が0の場合に ValueError がスローされます。 これより前のバージョンでは、代わりに `E_WARNING` を発生させていました。

PHP 8.0.0 以降では、 `[width]` の値が0より小さかったり、 `PHP_INT_MAX` より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに `E_WARNING` を発生させていました。

PHP 8.0.0 以降では、 `[precision]` の値が0より小さかったり、 `PHP_INT_MAX` より大きい場合に、 ValueError がスローされます。 これより前のバージョンでは、代わりに `E_WARNING` を発生させていました。

PHP 8.0.0 以降では、 引数が必要な数より少なかった場合、 ValueError がスローされます。 これより前のバージョンでは、代わりに `false` を返し、`E_WARNING` を発生させていました。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | この関数は、失敗時に `false` を返さなくなりました。
8.0.0 | 引数の数が0だった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに `E_WARNING` を発生させていました。
8.0.0 | `[width]` の値が0より小さかったり、 `PHP_INT_MAX` より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに `E_WARNING` を発生させていました。
8.0.0 | `[precision]` の値が0より小さかったり、 `PHP_INT_MAX` より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに `E_WARNING` を発生させていました。
8.0.0 | 引数が必要な数より少なかった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに `E_WARNING` を発生させていました。

### 例

例1 vfprintf(): 数値のゼロ埋め

    <?php
    if (!($fp = fopen('date.txt', 'w')))
        return;

    $year = 2025;
    $month = 5;
    $day = 6;
    vfprintf($fp, "%04d-%02d-%02d", array($year, $month, $day));
    // ISO 形式にフォーマットした日付を date.txt に書き込みます
    ?>

### 参考

- printf() - フォーマット済みの文字列を出力する
- sprintf() - フォーマットされた文字列を返す
- fprintf() - フォーマットされた文字列をストリームに書き込む
- vprintf() - フォーマットされた文字列を出力する
- vsprintf() - フォーマットされた文字列を返す
- sscanf() - フォーマット文字列に基づき入力を処理する
- fscanf() - フォーマットに基づきファイルからの入力を処理する
- number_format() - 数字を千の位毎にグループ化してフォーマットする
- date() - Unixタイムスタンプを書式化する

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open