(PHP 4, PHP 5, PHP 7, PHP 8)
substr — Return part of a string
$string
, int $offset
, ?int $length
= null
): string
Returns the portion of string
specified by the
offset
and length
parameters.
string
The input string.
offset
If offset
is non-negative, the returned string
will start at the offset
'th position in
string
, counting from zero. For instance,
in the string 'abcdef
', the character at
position 0
is 'a
', the
character at position 2
is
'c
', and so forth.
If offset
is negative, the returned string
will start at the offset
'th character
from the end of string
.
If string
is less than
offset
characters long, an empty string will be returned.
Example #1 Using a negative offset
<?php
$rest = substr("abcdef", -1); // returns "f"
$rest = substr("abcdef", -2); // returns "ef"
$rest = substr("abcdef", -3, 1); // returns "d"
?>
length
If length
is given and is positive, the string
returned will contain at most length
characters
beginning from offset
(depending on the length of
string
).
If length
is given and is negative, then that many
characters will be omitted from the end of string
(after the start position has been calculated when a
offset
is negative). If
offset
denotes the position of this truncation or
beyond, an empty string will be returned.
If length
is given and is 0
,
an empty string will be returned.
If length
is omitted or null
, the substring starting from
offset
until the end of the string will be
returned.
Example #2 Using a negative length
<?php
$rest = substr("abcdef", 0, -1); // returns "abcde"
$rest = substr("abcdef", 2, -1); // returns "cde"
$rest = substr("abcdef", 4, -4); // returns ""; prior to PHP 8.0.0, false was returned
$rest = substr("abcdef", -3, -1); // returns "de"
?>
Returns the extracted part of string
, or
an empty string.
Version | Description |
---|---|
8.0.0 |
length is nullable now.
When length is explicitly set to null ,
the function returns a substring finishing at the end of the string, when it previously returned an empty string.
|
8.0.0 |
The function returns an empty string where it previously returned false .
|
Example #3 Basic substr() usage
<?php
echo substr('abcdef', 1); // bcdef
echo substr("abcdef", 1, null); // bcdef; prior to PHP 8.0.0, empty string was returned
echo substr('abcdef', 1, 3); // bcd
echo substr('abcdef', 0, 4); // abcd
echo substr('abcdef', 0, 8); // abcdef
echo substr('abcdef', -1, 1); // f
// Accessing single characters in a string
// can also be achieved using "square brackets"
$string = 'abcdef';
echo $string[0]; // a
echo $string[3]; // d
echo $string[strlen($string)-1]; // f
?>
Example #4 substr() casting behaviour
<?php
class apple {
public function __toString() {
return "green";
}
}
echo "1) ".var_export(substr("pear", 0, 2), true).PHP_EOL;
echo "2) ".var_export(substr(54321, 0, 2), true).PHP_EOL;
echo "3) ".var_export(substr(new apple(), 0, 2), true).PHP_EOL;
echo "4) ".var_export(substr(true, 0, 1), true).PHP_EOL;
echo "5) ".var_export(substr(false, 0, 1), true).PHP_EOL;
echo "6) ".var_export(substr("", 0, 1), true).PHP_EOL;
echo "7) ".var_export(substr(1.2e3, 0, 4), true).PHP_EOL;
?>
The above example will output:
1) 'pe' 2) '54' 3) 'gr' 4) '1' 5) '' 6) '' 7) '1200'
Example #5 Invalid Character Range
If an invalid character range is requested, substr() returns
an empty string as of PHP 8.0.0; previously, false
was returned instead.
<?php
var_dump(substr('a', 2));
?>
Output of the above example in PHP 8:
string(0) ""
Output of the above example in PHP 7:
bool(false)