strpos

(PHP 4, PHP 5, PHP 7, PHP 8)

strpos — Ищет позицию первого вхождения подстроки

Описание

strpos(string $haystack, string $needle, int $offset = 0): int|false

Функция ищет в строке haystack позицию первого вхождения подстроки needle.

Список параметров

haystack

Строка, в которой выполняется поиск.

needle

Строка, которую требуется найти.

До PHP 8.0.0 нестроковый аргумент needle преобразовывался в целое число и заменялся на символ с этим порядковым значением в однобайтовой таблице символов. Начиная с PHP 7.3.0 передача нестроковых значений устарела и полагаться на него настоятельно не рекомендуют. Перед вызовом функции нестроковый аргумент needle требовалось либо приводить к строке, либо получать строковое значение символа функцией chr().

offset

При установке параметра функция начнёт поиск с заданного количества символов с начала строки. При отрицательном значении функция отсчитывает позицию начала поиска с конца строки.

Возвращаемые значения

Функция возвращает позицию искомой подстроки относительно начала строки haystack независимо от значения параметра offset. Обратите также внимание, что позиция строки отсчитывается с 0, а не с 1.

Функция возвращает значение false, если не нашла строку.

Внимание

Функция возвращает как логическое значение false, так и нелогическое значение, которое приводится к false. Прочитайте раздел «Логический тип», чтобы получить дополнительную информацию. Используйте оператор === для проверки значения, которое возвращает функция.

Ошибки

Функция выбросит ошибку ValueError, если значение параметра offset превысит длину строки haystack.

Список изменений

Версия	Описание
8.0.0	Параметр `needle` теперь разрешает пустую строку.
8.0.0	Функция больше не поддерживает передачу целого числа (int) в параметр `needle`.
7.3.0	Передача целого числа (int) в параметр `needle` устарела.
7.1.0	Добавили поддержку отрицательных значений параметром `offset`.

Примеры

Пример #1 Пример строго сравнения значений оператором ===

<?php

$mystring = 'abc';
$findme   = 'a';
$pos = strpos($mystring, $findme);

// Обратите внимание, что значения сравниваются оператором ===. Оператор == не будет работать
// как ожидается, поскольку позиция символа «a» — первого по счёту символа — равнялась 0.
if ($pos === false) {
    echo "Функция не нашла подстроку «{$findme}» в строке «{$mystring}»";
} else {
    echo "Функция нашла подстроку «{$findme}» в строке «{$mystring}»";
    echo " в позиции $pos";
}

?>

Пример #2 Пример проверки результата оператором !==

<?php

$mystring = 'abc';
$findme   = 'a';
$pos = strpos($mystring, $findme);

// Оператором !== тоже проверяют результат поиска позиции подстроки. Оператор != не сработает
// как ожидается, поскольку позиция подстроки 'a' равна 0. Инструкция (0 != false) вычисляется
// как false, поскольку при нестрогом сравнении false неявно приводится к 0
if ($pos !== false) {
     echo "Функция нашла подстроку «{$findme}» в строке «{$mystring}»";
         echo " в позиции {$pos}";
} else {
     echo "Функция не нашла подстроку «{$findme}» в строке «{$mystring}»";
}

?>

Пример #3 Пример установки смещения

<?php

// Игнорируем символы до значения смещения, а затем находим символ
$newstring = 'abcdef abcdef';
$pos = strpos($newstring, 'a', 1); // Переменная $pos = 7, а не 0

echo $pos, PHP_EOL;

?>

Примечания

Замечание: Функция безопасна для обработки данных в двоичной форме.

Смотрите также

stripos() - Возвращает позицию первого вхождения подстроки без учёта регистра
str_contains() - Определяет, содержит ли строка подстроку
str_ends_with() - Проверяет, заканчивается ли строка подстрокой
str_starts_with() - Проверяет, начинается ли строка с подстроки
strrpos() - Возвращает позицию последнего вхождения подстроки в строку
strripos() - Ищет в строке позицию последнего вхождения подстроки, без учёта регистра
strstr() - Находит первое вхождение подстроки
strpbrk() - Ищет в строке символ из набора
substr() - Возвращает подстроку
preg_match() - Выполняет проверку на соответствие регулярному выражению