ConFoo 2025

fprintf

(PHP 5, PHP 7, PHP 8)

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

Описание

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;
}

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

Добавить

Примечания пользователей 1 note

up
1
Julien MOREAU
3 years ago
If you use the command line interface (CLI SAPI), you may be interested by the 3 standard input/output streams (STDIN, STDOUT & STDERR) described at: https://www.php.net/manual/en/features.commandline.io-streams.php
To Top