substr

Return part of a string

&reftitle.description; `string` `substr` `string` `string` `int` `offset` ``int``null```length`&null;

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

&reftitle.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.

  ### 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.

  ### 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"
      ?>

&reftitle.returnvalues;

Returns the extracted part of `string`, or an empty string.

&reftitle.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;.

&reftitle.examples;

### 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

    ?>

### `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;
    ?>

&example.outputs;

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

### 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));
    ?>

&example.outputs.8;

    string(0) ""

&example.outputs.7;

    bool(false)

&reftitle.seealso;

- `strrchr`
- `substr_replace`
- `preg_match`
- `trim`
- `mb_substr`
- `wordwrap`
- String access and modification by character