Записывает отформатированную строку в поток

# fprintf

(PHP 5, PHP 7, PHP 8)

fprintf — Записывает отформатированную строку в поток

### Описание

function fprintf(resource `$stream`, string `$format`, mixed `...$values`): int

Функция записывает строку, которую создала по условиям строки формата `format`, в ресурс поток, дескриптор которого передали в параметр `stream`.

### Список параметров

`stream`
  Ресурс (resource) указателя файловой системы, который обычно создают функцией fopen().
`format`
  Строка формата состоит из нуля или большего количества директив: стандартных символов, кроме `%`, которые выводятся без изменений, и спецификаторов преобразования, каждому из которых требуется параметр. Спецификация преобразования соответствует прототипу: `%[argnum$][flags][width][.precision]specifier`.

  ##### Argnum

  Целое число, за которым идёт знак доллара `$`. Число указывает порядковый номер аргумента, который требуется преобразовать.

  ##### Флаги

  Флаг | Описание
  --- | ---
  `-` | Выравнивает значение по левому краю в пределах заданной ширины поля; по умолчанию значение выравнивается по правому краю.
  `+` | Выводит знак `+` перед неотрицательными числами; по умолчанию только к отрицательным числам добавляется знак минус.
  `` (пробел) | Дополняет результат пробелами, которыми также при заданной ширине значение дополняется по умолчанию.
  `0` | Дополняет числа нулями, но только слева. Со спецификатором `s` и флагом левостороннего выравнивания значение дополняется нулями справа.
  `'`символ | Дополняет результат символом, который указали после апострофа.

  ##### Ширина

  Ширина задаётся либо целым числом — минимум символов, который выводится в результате преобразования, либо символом `*`. При передаче символа `*` ширина задаётся в списке аргументов дополнительным целым числом перед значением, которое относится к спецификатору.

  ##### Точность

  Символ `.`, за которым необязательно идёт целое число или символ `*`. Значение точности зависит от спецификатора:

  - Для спецификаторов `e`, `E`, `f` и `F`: задаёт количество цифр после десятичной запятой. Значение по умолчанию — 6.
  - Для спецификаторов `g`,`G`, `h` и `H`: задаёт предельное количество значащих цифр для вывода.
  - Для спецификатора `s`: устанавливает точку отсечения для ограничения количества символов в строке.

  > Замечание: При пропуске явного значения точности после точки за точность принимается значение 0. Точность задаётся дополнительным целочисленным аргументом перед значением, к которому относится спецификатор, если вместо значения точности в строке формата указали символ `*`.

  Спецификаторы
  Спецификатор | Описание
  --- | ---
  `%` | Символ процента. Аргументы не требуются.
  `b` | Аргумент рассматривается как целое число и печатается в бинарном представлении.
  `c` | Аргумент рассматривается как целое число и печатается как символ из таблицы ASCII с соответствующим кодом.
  `d` | Аргумент рассматривается как целое число и печатается как целое число со знаком.
  `e` | Аргумент считается за число в научной нотации (т. е. 1.2e+2).
  `E` | Аргумент аналогичен спецификатору `e`, но с заглавным символом (т. е. 1.2E+2).
  `f` | Аргумент считается за число с плавающей точкой (с учётом локали).
  `F` | Аргумент считается за число с плавающей точкой (без учёта локали).
  `g` | Общий формат. Пусть P равно точности, если точность не равна нулю, 6, если точность не задали, или 1, если точность равна 0. Тогда, если преобразование со стилем «E» будет иметь показатель степени X: Если P > X ≥ −4, преобразование будет в стиле «f» и точность будет 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` | Аргумент рассматривается как целое число и печатается в восьмеричном представлении.
  `s` | Аргумент рассматривается и печатается как строка.
  `u` | Аргумент рассматривается как целое число и печатается как беззнаковое целое число.
  `x` | Аргумент рассматривается как целое число и печатается в шестнадцатеричном представлении (буквы будут в нижнем регистре).
  `X` | Аргумент рассматривается как целое число и печатается в шестнадцатеричном представлении (буквы будут в верхнем регистре).

  Внимание

  Спецификатор `c` игнорирует спецификаторы преобразования дополнения и ширины.

  Внимание

  Попытка использовать комбинацию спецификаторов строки и ширины с кодировками, которые требуют больше одного байта на символ, иногда даёт неожиданные результаты.

  Функция приведёт переменные к типу, который соответствует спецификатору:

  Обработка типов
  Тип | Спецификатор
  --- | ---
  string | `s`
  int | `d`, `u`, `c`, `o`, `x`, `X`, `b`
  float | `e`, `E`, `f`, `F`, `g`, `G`, `h`, `H`

`values`

### Возвращаемые значения

Функция возвращает длину записанной строки.

### Ошибки

Начиная с PHP 8.0.0, если количество аргументов равно нулю, выбрасывается исключение ValueError. До PHP 8.0.0 вместо этого выдавалась ошибка уровня `E_WARNING`.

Начиная с PHP 8.0.0, если `[width]` меньше нуля или больше `PHP_INT_MAX`, выбрасывается исключение ValueError. До PHP 8.0.0 вместо этого выдавалась ошибка уровня `E_WARNING`.

Начиная с PHP 8.0.0, если `[precision]` меньше нуля или больше `PHP_INT_MAX`, выбрасывается исключение ValueError. До PHP 8.0.0 вместо этого выдавалась ошибка уровня `E_WARNING`.

Начиная с PHP 8.0.0, если аргументов задано меньше, чем требуется, выбрасывается исключение ArgumentCountError. До PHP 8.0.0 вместо этого выдавалась ошибка уровня `E_WARNING`.

### Список изменений

Версия | Описание
--- | ---
8.0.0 | Функция больше не возвращает `false`, если возникла ошибка.
8.0.0 | Выбрасывает исключение ValueError, если количество аргументов равно нулю; раньше функция выдавала ошибку уровня `E_WARNING`.
8.0.0 | Выбрасывает исключение ValueError, если `[width]` меньше нуля или больше `PHP_INT_MAX`; раньше функция выдавала ошибку уровня `E_WARNING`.
8.0.0 | Выбрасывает исключение ValueError, если `[precision]` меньше нуля или больше `PHP_INT_MAX`; раньше функция выдавала ошибку уровня `E_WARNING`.
8.0.0 | Выбрасывает исключение ArgumentCountError, если аргументов задано меньше, чем требуется; раньше функция выдавала ошибку уровня `E_WARNING`.

### Примеры

Пример #1 Дополнение целочисленных значений ведущими нулями функцией fprintf()

    <?php

    if (!($fp = fopen('date.txt', 'w'))) {
        return;
    }

    $year = 2005;
    $month = 5;
    $day = 6;

    fprintf($fp, "%04d-%02d-%02d", $year, $month, $day);
    // Функция запишет дату, которую отформатировала по стандарту ISO, в файл date.txt

    ?>

Пример #2 Пример форматирования денежных сумм функцией fprintf()

    <?php

    if (!($fp = fopen('currency.txt', 'w'))) {
        return;
    }

    $money1 = 68.75;
    $money2 = 54.35;
    $money = $money1 + $money2;
    // Конструкция echo $money выведет "123.1";
    $len = fprintf($fp, '%01.2f', $money);
    // Функция записала строку "123.10" в файл currency.txt

    echo "Функция записала $len байтов в файл currency.txt";
    // Значение, которое возвращает функция fprintf, содержит количество записанных байтов

    ?>

### Смотрите также

- printf() - Выводит отформатированную строку
- sprintf() - Возвращает отформатированную строку
- vprintf() - Выводит отформатированную строку
- vsprintf() - Возвращает отформатированную строку
- vfprintf() - Записывает отформатированную строку в поток
- sscanf() - Разбирает строку по условиям формата
- fscanf() - Обрабатывает данные из файла по условиям формата
- number_format() - Форматирует число с группировкой классов многозначного числа
- date() - Форматирует метку времени эпохи Unix

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