Write a string produced according to format to the
stream resource specified by stream.
Parameters
stream
A file system pointer resource
that is typically created using fopen().
format
The format string is composed of zero or more directives:
ordinary characters (excluding %) that are
copied directly to the result and conversion
specifications, each of which results in fetching its
own parameter.
A conversion specification follows this prototype:
%[argnum$][flags][width][.precision]specifier.
Argnum
An integer followed by a dollar sign $,
to specify which number argument to treat in the conversion.
Flags
Flag
Description
-
Left-justify within the given field width;
Right justification is the default
+
Prefix positive numbers with a plus sign
+. By default only negative numbers
are prefixed with a negative sign.
(space)
Pads the result with spaces.
This is the default.
0
Only left-pads numbers with zeros.
With s specifiers this can
also right-pad with zeros.
'(char)
Pads the result with the character (char).
Width
Either an integer that says how many characters (minimum)
this conversion should result in, or *.
If * is used, then the width is supplied
as an additional integer value preceding the one formatted
by the specifier.
Precision
A period . optionally followed by
either an integer or *,
whose meaning depends on the specifier:
For e, E,
f and F
specifiers: this is the number of digits to be printed
after the decimal point (by default, this is 6).
For g, G,
h and H
specifiers: this is the maximum number of significant
digits to be printed.
For s specifier: it acts as a cutoff point,
setting a maximum character limit to the string.
Note:
If the period is specified without an explicit value for precision,
0 is assumed. If * is used, the precision is
supplied as an additional integer value preceding the one formatted
by the specifier.
Specifiers
Specifier
Description
%
A literal percent character. No argument is required.
b
The argument is treated as an integer and presented
as a binary number.
c
The argument is treated as an integer and presented
as the character with that ASCII value.
d
The argument is treated as an integer and presented
as a (signed) decimal number.
e
The argument is treated as scientific notation (e.g. 1.2e+2).
E
Like the e specifier but uses
uppercase letter (e.g. 1.2E+2).
f
The argument is treated as a float and presented
as a floating-point number (locale aware).
F
The argument is treated as a float and presented
as a floating-point number (non-locale aware).
g
General format.
Let P equal the precision if nonzero, 6 if the precision is omitted,
or 1 if the precision is zero.
Then, if a conversion with style E would have an exponent of X:
If P > X ≥ −4, the conversion is with style f and precision P − (X + 1).
Otherwise, the conversion is with style e and precision P − 1.
G
Like the g specifier but uses
E and f.
h
Like the g specifier but uses F.
Available as of PHP 8.0.0.
H
Like the g specifier but uses
E and F. Available as of PHP 8.0.0.
o
The argument is treated as an integer and presented
as an octal number.
s
The argument is treated and presented as a string.
u
The argument is treated as an integer and presented
as an unsigned decimal number.
x
The argument is treated as an integer and presented
as a hexadecimal number (with lowercase letters).
X
The argument is treated as an integer and presented
as a hexadecimal number (with uppercase letters).
Warning
The c type specifier ignores padding and width.
Warning
Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results.
Variables will be coerced to a suitable type for the specifier:
As of PHP 8.0.0, a ValueError is thrown if the number of arguments is zero.
Prior to PHP 8.0.0, an E_WARNING was emitted instead.
As of PHP 8.0.0, a ValueError is thrown if [width] is less than zero or bigger than PHP_INT_MAX.
Prior to PHP 8.0.0, an E_WARNING was emitted instead.
As of PHP 8.0.0, a ValueError is thrown if [precision] is less than zero or bigger than PHP_INT_MAX.
Prior to PHP 8.0.0, an E_WARNING was emitted instead.
As of PHP 8.0.0, an ArgumentCountError is thrown when less arguments are given than required.
Prior to PHP 8.0.0, false was returned and an E_WARNING emitted instead.
Changelog
Version
Description
8.5.0
A formatter that does not specify a precision now correctly treats
it as a precision of 0, instead of incorrectly resetting the precision.
Throws a ValueError if the number of arguments is zero;
previously this function emitted an E_WARNING instead.
8.0.0
Throws a ValueError if [width] is less than zero or bigger than PHP_INT_MAX;
previously this function emitted an E_WARNING instead.
8.0.0
Throws a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX;
previously this function emitted an E_WARNING instead.
8.0.0
Throws an ArgumentCountError when fewer arguments are given than required;
previously this function emitted an E_WARNING instead.
Examples
Example #1 fprintf(): zero-padded integers
<?php
if (!($fp = fopen('date.txt', 'w'))) {
return;
}
$year = 2005;
$month = 5;
$day = 6;
fprintf($fp, "%04d-%02d-%02d", $year, $month, $day);
// will write the formatted ISO date to date.txt
?>
Example #2 fprintf(): formatting currency
<?php
if (!($fp = fopen('currency.txt', 'w'))) {
return;
}
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
// echo $money will output "123.1";
$len = fprintf($fp, '%01.2f', $money);
// will write "123.10" to currency.txt
echo "wrote $len bytes to currency.txt";
// use the return value of fprintf to determine how many bytes we wrote
?>
explode
String Functions