Php/docs/function.substr

• PHP Manual
• String Functions
• Return part of a string

substr

(PHP 4, PHP 5, PHP 7)

substr — Return part of a string

Description

substr ( string $string , int $offset [, int|null $length = NULL ] ) : string

Returns the portion of string specified by the offset and length parameters.

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, FALSE 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, FALSE will be returned.

If length is given and is 0, FALSE or NULL, an empty string will be returned.

If length is omitted, 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 false$rest = substr("abcdef", -3, -1); // returns "de"?>

Return Values

Returns the extracted part of string; or FALSE on failure, or an empty string.

Changelog

Version	Description
8.0.0	length is nullable now.
8.0.0	The function returns an empty where it previously returned FALSE.

Examples

Example #3 Basic substr() usage

<?phpecho substr('abcdef', 1);     // bcdefecho substr('abcdef', 1, 3);  // bcdecho substr('abcdef', 0, 4);  // abcdecho substr('abcdef', 0, 8);  // abcdefecho substr('abcdef', -1, 1); // f// Accessing single characters in a string// can also be achieved using "square brackets"$string = 'abcdef';echo $string[0];                 // aecho $string[3];                 // decho $string[strlen($string)-1]; // f?>

Example #4 substr() casting behaviour

<?phpclass 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;?>

Output of the above example in PHP 7:

1) 'pe'
2) '54'
3) 'gr'
4) '1'
5) ''
6) ''
7) '1200'

Output of the above example in PHP 5:

1) 'pe'
2) '54'
3) 'gr'
4) '1'
5) false
6) false
7) '1200'

Errors/Exceptions

Returns FALSE on error.

<?phpvar_dump(substr('a', 2)); // 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