String 関数
PHP マニュアル

substr

文字列の一部分を返す

説明

string substr(string $string, int $offset, intnull $length = null)

文字列 string の、offset で指定された位置から length バイト分の文字列を返します。

パラメータ

string

入力文字列。

offset

offset が正の場合、返される文字列は、 string の 0 から数えて offset番目から始まる文字列となります。 例えば、文字列'abcdef'において位置 0にある文字は、'a'であり、 位置2には'c'があります。

offset が負の場合、返される文字列は、 stringの後ろから数えて offset番目から始まる文字列となります。

string の長さが offset 文字より短い場合は、 空の文字列が返されます。

例1 負の offset の使用

<?php
$rest = substr("abcdef", -1);    // "f" を返す
$rest = substr("abcdef", -2);    // "ef" を返す
$rest = substr("abcdef", -3, 1); // "d" を返す
?>

length

length が指定され、かつ正である場合、 返される文字列は offset (string の長さに依存します) から数えてlength文字数分となります。

length が指定され、かつ負である場合、 string の終端からその文字数分の文字が省略されます (offset が負の場合は、 開始位置を算出したあとで)。 もし offset が切り出し位置を超える場合、 空の文字列が返されます。

length が指定され、かつ 0 であれば、空の文字が返されます。

length を省略した場合、または null の場合は、 offset の位置から文字列の最後までの部分文字列を返します。

例2 負の length の使用

<?php
$rest = substr("abcdef", 0, -1);  // "abcde" を返す
$rest = substr("abcdef", 2, -1);  // "cde" を返す
$rest = substr("abcdef", 4, -4);  // "" を返す。PHP 8.0.0 より前のバージョンでは、false を返していました。
$rest = substr("abcdef", -3, -1); // "de" を返す
?>

戻り値

string の一部を返すか、空文字列を返します。

変更履歴

バージョン 説明
8.0.0 length は、nullable になりました。 length に明示的に null を設定すると、 文字列の最後までを含む部分文字列を返すようになっています。 これより前のバージョンでは、空文字列を返していました。
8.0.0 この関数は、前のバージョンで false を返す場合に、空文字列を返すようになりました。

例

例3 基本的な substr の使用法

<?php
echo substr('abcdef', 1);     // bcdef
echo substr("abcdef", 1, null); // bcdef, PHP 8.0.0 より前のバージョンでは、空の文字列を返していました。
echo substr('abcdef', 1, 3);  // bcd
echo substr('abcdef', 0, 4);  // abcd
echo substr('abcdef', 0, 8);  // abcdef
echo substr('abcdef', -1, 1); // f

// 文字列中の 1 文字にアクセスすることも
// "角括弧" を使用することで可能
$string = 'abcdef';
echo $string[0];                 // a
echo $string[3];                 // d
echo $string[strlen($string)-1]; // f

?>

例4 substr でのキャストの挙動

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

上の例の出力は以下となります。

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

例5 文字列の範囲が不正な場合

指定された文字列の範囲が正しくない場合、 substr は PHP 8.0.0 以降では空文字列を返します。 それより前のバージョンでは、false を返していました。 

<?php
var_dump(substr('a', 2));
?>

上の例の PHP 8 での出力は、このようになります。:

string(0) ""

上の例の PHP 7 での出力は、このようになります。

bool(false)

参考