정의 및 사용 방법

PHP 버전
4+

strpos() 함수는 문자열에서 인수로 전달된 문자열를 찾아 첫 번째로 검색된(등장한) 위치의 인덱스를 반환합니다.
인수로 전달된 문자열를 찾을 수 없다면 false를 반환합니다.

이 함수는 문자열에서 문자의 위치를 찾거나, 포함하는지 확인할 때 유용합니다.

특징

  • 대소문자를 구분합니다.
  • 한글과 같은 multi-byte(멀티바이트) 문자열을 지원하지 않습니다.
  • str_contains() 함수가 도입되기 전(PHP 8.0.0 이전)에는, 문자열 포함 여부를 확인할 때 주로 strpos() 함수가 사용되었습니다.

부연설명
PHP 8.0.0에 도입된 str_contains() 함수는 대소문자를 구분해서 문자열에 주어진 문자가 포함되어 있으면 true를 그렇지 않으면 false를 반환합니다.

기본 예제

PHP 
$str = 'Hello, World!';
$substring = 'World';

$pos = strpos($str, $substring);

if ($pos !== false) {
    echo "찾은 위치: $pos";
} else {
    echo '찾을 수 없습니다.';
}

// 출력: 찾은 위치: 7

/*
 * 주의하세요!
 * 문자열에서 인덱스는 0부터 시작합니다.
 * 첫 번째 문자열의 인덱스는 0이고, 두 번째 문자열의 인덱스는 1입니다.
*/

구문

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

매개변수

strpos() 함수의 매개변수 설명
$haystack 검색 대상이 되는 문자열입니다.
$needle 검색할 문자열입니다.
  • 대소문자를 구분합니다.
  • PHP 8 이전의 버전에서는 빈 문자열('')을 허용하지 않습니다. 경고(Warning)를 발생시킵니다.
$offset 옵션. 검색을 시작할 0 기반의 인덱스입니다.
  • 생략하면 기본값으로 0이 사용됩니다.
  • PHP 7.1.0부터는 음수 값을 사용할 수 있으며, 음수인 경우 문자열 끝부터 계산된 문자 수만큼 검색이 시작됩니다.

반환 값

대상 문자열에서 인수로 전달된 문자열($needle)이 처음 나타나는 위치(인덱스)를 반환합니다.
문자열 위치(인덱스)는 1이 아닌 0부터 시작한다는 점에 유의하세요.

주어진 문자열($needle)이 포함되어 있지 않으면 false를 반환합니다.

$offset 값이 검색 대상 문자열($haystack)의 길이를 초과하면 검색을 시작할 위치가 존재하지 않기 때문에 ValueError 예외가 발생합니다.

변경 이력

strpos() 함수의 변경 이력
버전설명
8.0.0 $needle에 빈 문자열('')을 허용합니다.
8.0.0 $needle에 정수형(int) 값을 전달하는 기능이 완전히 지원되지 않게 되었습니다.
7.3.0 $needle에 정수형(int) 값을 전달하는 기능이 사용 중단(deprecated) 처리되었습니다.
7.1.0 $offset에 음수를 전달할 수 있게 되었습니다.

주의할 점

strpos() 함수는 대소문자를 구분합니다.

PHP 
$str = 'Hello, World!';
$substring = 'world';

$pos = strpos($str, $substring);

if ($pos !== false) {
    echo "문자열에 'world!'가 포함되어 있습니다.";
} else {
    echo "대소문자가 일치하지 않아 'world'를 찾을 수 없습니다.";
}

// 출력: "대소문자가 일치하지 않아 'world'를 찾을 수 없습니다."

만약 대소문자를 구분하지 않고 문자열에서 특정 문자열의 위치를 찾고자 한다면, stripos() 함수를 사용하세요.

문자열에서 인덱스는 0부터 시작합니다.
첫 번째 문자의 인덱스는 0이고, 두 번째 문자의 인덱스는 1입니다.

PHP 
$newstring = 'abcdef ghijk';
$pos = strpos($newstring, 'a');

var_dump($pos); // int(0)

PHP 8 이전의 버전에서는 검색할 문자열에 빈 문자열('')을 허용하지 않습니다.

PHP 
$str = 'Hello, World!';
$substring = '';

$pos = strpos($str, $substring); // Warning: strpos(): Empty needle in

PHP 8.0.0 버전부터는 빈 문자열('')을 허용합니다.

strpos() 함수의 반환 값을 조건식에서 사용할 때에는 주의가 필요합니다.
이 함수는 문자열의 위치를 정수로 반환하며, 첫 번째 위치에 문자열이 존재하는 경우 반환 값은 0입니다.
PHP에서 0은 느슨한 비교(==)에서 false로 평가되므로, 반환 값을 확인할 때는 엄격한 타입 비교 연산자인 === 또는 !==를 사용해야 합니다.

대상 문자열에서 주어진 문자열의 위치가 첫 번째에 위치하고 있다고 가정해 보겠습니다.

이 경우 반환 값은 0이 됩니다.

0은 == 연산자로 평가하면 false를 반환하게 됩니다.
실제 주어진 문자열이 존재하지만 false를 반환하기 때문에 부울(boolean) 타입으로 반환 값을 평가하려면 엄격한 타입 비교가 수행되어 하기 때문에 === 연산자를 사용해야 합니다.

PHP 
$str = 'Hello, World!';
$substring = 'Hello';

$pos = strpos($str, $substring);

var_dump($pos); // int(0)

if ($pos === false) {
    echo "문자열에 'Hello'를 찾을 수 없습니다.";
} else {
    echo "문자열에 'Hello'가 포함되어 있습니다.";
}

// 출력: "문자열에 'Hello'가 포함되어 있습니다."

/* 또는 */

if ($pos !== false) {
    echo "문자열에 'Hello'가 포함되어 있습니다.";
} else {
    echo "문자열에 'Hello'를 찾을 수 없습니다.";
}

// 출력: "문자열에 'Hello'가 포함되어 있습니다."

strpos() 함수는 한글과 같은 multi-byte 문자열을 문자 단위가 아닌 바이트 단위로 처리하기 때문에 원하지 않는 결과가 발생할 수 있습니다.

부연설명
UTF-8 인코딩에서 영어와 숫자 같은 ASCII 문자는 1 byte로 표현되지만, 한글이나 일본어, 중국어 등은 여러 byte를 사용합니다.
이처럼 하나의 문자를 표현하기 위해 2 byte 이상을 사용하는 문자를 multi-byte(멀티바이트) 문자열이라고 합니다.

PHP 
$str = '반갑습니다. 환영합니다!';
$substring = '환영';

$pos = strpos($str, $substring);

if ($pos !== false) {
    echo "찾은 위치: $pos";
} else {
    echo '찾을 수 없습니다.';
}

// 출력: 찾은 위치: 17 <= 원하지 않는 결과가 발생합니다.

mb_strpos() 함수는 strpos() 함수와 거의 동일한 기능을 하지만, 한글과 같은 multi-byte 문자열에서 안전하게 작동하는 기능을 제공한다는 큰 차이점이 있습니다.

활용 예제

strpos() 함수는 대소문자를 구분하여 문자열을 검색할 때 사용됩니다.
여기에서 몇 가지 strpos() 함수의 활용 사용 사례를 살펴보겠습니다.

파일 시스템 및 경로

대부분의 파일 시스템은 대소문자를 구분합니다. 따라서 파일 이름이나 경로를 정확하게 입력하려면 대소문자를 구분해야 합니다.

PHP 
$file_path = '/var/www/html/project/files/document.txt';
$directory_name = '/var/www/html/project';

// 파일 경로에서 특정 디렉토리가 포함되어 있는지 확인
if (strpos($file_path, $directory_name) !== false) {
    echo '파일은 지정된 디렉토리에 속해 있습니다.';
} else {
    echo '파일은 지정된 디렉토리에 속해 있지 않습니다.';
}

// 출력: '파일은 지정된 디렉토리에 속해 있습니다.'

// 파일 경로에서 파일 이름 추출
$file_name = substr($file_path, strrpos($file_path, '/') + 1);
echo "파일 이름: $file_name";

// 출력: "파일 이름: document.txt"

이 예제에서는 strpos() 함수를 사용하여 파일 경로가 특정 디렉토리를 포함하는지를 확인하고, substr() 함수와 strrpos() 함수를 조합하여 파일 경로에서 파일 이름을 추출하고 있습니다.

일러두기
파일 경로와 관련된 작업에서는 실제 경로에 대해 정확한 문자열 처리가 필요하며, 경로 조작에 대한 안전한 방법을 사용하는 것이 좋습니다. 또한 PHP에서는 파일 경로를 다룰 때 realpath() 함수를 사용하여 정규화하고, pathinfo() 함수를 사용하여 파일 경로의 정보를 얻는 등의 방법이 더 안전하고 신뢰성이 있습니다.

참고문헌

같이 보기