substr
(PHP 4, PHP 5, PHP 7, PHP 8)
substr — Return part of a string
Description
$string, int $offset, ?int $length = null): string
Returns the portion of string specified by the
offset and length parameters.
Parameters
-
string -
The input string.
-
offset -
If
offsetis non-negative, the returned string will start at theoffset'th position instring, counting from zero. For instance, in the string 'abcdef', the character at position0is 'a', the character at position2is 'c', and so forth.If
offsetis negative, the returned string will start at theoffset'th character from the end ofstring.If
stringis less thanoffsetcharacters 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
lengthis given and is positive, the string returned will contain at mostlengthcharacters beginning fromoffset(depending on the length ofstring).If
lengthis given and is negative, then that many characters will be omitted from the end ofstring(after the start position has been calculated when aoffsetis negative). Ifoffsetdenotes the position of this truncation or beyond, an empty string will be returned.If
lengthis given and is0, an empty string will be returned.If
lengthis omitted ornull, the substring starting fromoffsetuntil 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"
?>
Return Values
Returns the extracted part of string, or
an empty string.
Changelog
| 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.
|
Examples
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)
See Also
- strrchr() - Find the last occurrence of a character in a string
- substr_replace() - Replace text within a portion of a string
- preg_match() - Perform a regular expression match
- trim() - Strip whitespace (or other characters) from the beginning and end of a string
- mb_substr() - Get part of string
- wordwrap() - Wraps a string to a given number of characters
- String access and modification by character
