Fatal error: Call to undefined function mb_strpos() 오류 해결법

mb_strpos 는 PHP에서 다국어 문자열을 처리할 때 자주 사용하는 함수 중 하나 입니다. 그런데 php 코드를 실행했을 때 다음과 같은 오류 메시지가 나타난다면:

/var/log/apache2/error.log 에러로그에 이런 메세지가 나온다면

Fatal error: Call to undefined function mb_strpos()

이는 PHP 환경에서 mbstring 확장 모듈이 비활성화되었거나 설치되지 않았을 때 발생하는 오류입니다.

이 글에서는 mb_strpos 함수의 개념, 오류 발생 원인, 그리고 해결 방법을 단계별로 정리하여, PHP에서 멀티바이트 문자열 기능을 정상적으로 사용할 수 있도록 설정하는 방법을 안내합니다.

1. mb_strpos() 함수란?

mb_strpos 는 PHP의 mbstring(Multibyte String) 확장에서 제공하는 함수로, 문자열 내 특정 문자의 위치를 반환합니다.
기본적인 strpos()는 ASCII 문자 기준으로 동작하지만, 한글·일본어·중국어 등 UTF-8과 같은 멀티바이트 문자열에서는 정확하지 않은 결과를 줄 수 있습니다.

📌 예시:

$str = "안녕하세요, PHP!";
echo mb_strpos($str, "P");  // 결과: 7

이처럼 mb_strpos()는 멀티바이트 문자열에서도 정확하게 위치를 계산해주기 때문에, 다국어 사이트에서는 거의 필수적인 함수입니다.

2. 오류 원인: mbstring 모듈 미설치 또는 미활성화

PHP는 기본 설치 시 일부 확장을 포함하지 않습니다. mb_strpos()는 mbstring 모듈에 포함되어 있기 때문에, 해당 모듈이 누락되거나 비활성화된 경우 위와 같은 오류가 발생합니다.

3. 에러 발생 시 점검 사항

✅ 에러 로그 확인

tail -f /var/log/apache2/error.log

Uncaught Error: Call to undefined function mb_strpos()

이 메시지가 보이면, mbstring 확장 모듈이 작동하지 않고 있다는 신호입니다.

4. PHP mbstring 활성화 방법 (Ubuntu 기준)

🔧 1단계: mbstring 확장 설치

sudo apt-get install php8.3-mbstring

※ PHP 버전에 따라 php8.2-mbstring, php7.4-mbstring 등으로 다를 수 있습니다.

🔧 2단계: php.ini 파일 수정

sudo vi /etc/php/8.3/apache2/php.ini

해당 파일에서 아래 항목을 찾습니다:

;extension=mbstring

👉 앞의 세미콜론(;)을 제거해 주석을 해제합니다:

extension=mbstring

🔧 3단계: Apache 또는 PHP-FPM 재시작

sudo systemctl restart apache2

또는 PHP-FPM 사용 시:

sudo systemctl restart php8.3-fpm

5. PHP에서 mbstring이 정상적으로 작동하는지 확인하기

php -m | grep mbstring

→ mbstring이 출력되면 정상 설치된 것입니다.

또는 아래처럼 PHP 파일을 만들어 확인할 수 있습니다:

<?php
phpinfo();
?>

브라우저에서 열었을 때 mbstring 섹션이 보이면 정상입니다.

6. 자주 묻는 질문 (FAQ)

❓ strpos() 대신 꼭 써야 하나요?

👉 멀티바이트 문자가 포함된 문자열(예: 한글, 일본어)을 처리할 경우 strpos()는 인덱스를 잘못 계산할 수 있습니다.
이런 경우 정확한 처리를 위해 mb_strpos()를 반드시 사용해야 합니다.

❓ CLI에선 되는데 웹에선 안 돼요

PHP는 CLI(터미널 실행)와 Apache 환경에서 php.ini 파일을 따로 관리합니다.
웹에서만 에러가 난다면, Apache용 php.ini 경로를 수정해야 합니다.

php -i | grep php.ini

❓ Windows에서는 어떻게 하나요?

1. php.ini 파일 열기
2. ;extension=mbstring → 앞 세미콜론 제거
3. Apache 또는 Nginx 재시작

7. 요약 정리

나의 문제 해결 과정

php 파일 실행 중 에러가 발생하여 로그를 확인했습니다:

tail -f /var/log/apache2/error.log

에러 메시지:

Uncaught Error: Call to undefined function mb_strpos()

해결 절차:

sudo apt-get install php8.3-mbstring

sudo vi /etc/php/8.3/apache2/php.ini
extension=mbstring ;주석제거(맨앞 세미콘론 제거 후 저장)

sudo systemctl restart apache2

이후 PHP에서 정상적으로 mb_strpos()가 작동함을 확인

✅ 결론: mb_strpos() 오류는 환경 설정 문제

이 오류는 PHP 코드의 문제가 아니라, PHP 환경에서 mbstring 확장이 누락되었을 때 발생하는 설정 문제입니다.
특히 다국어 웹사이트, 한글 기반 CMS, 문자 인코딩이 중요한 환경이라면 반드시 mbstring 확장을 활성화해야 합니다.

관련 내용

php.ini 설정 완전 정리

Fatal error: Call to undefined function curl_init() 오류 해결법

PHP 파일 업로드 오류 해결법