정의 및 사용 방법

PHP 버전
4+

preg_match_all() 함수는 정규 표현식을 사용하여 주어진 문자열에서 일치하는 모든 부분을 찾아 그 결과를 반환합니다.

특징

  • 이 함수는 대소문자를 구분합니다.
  • 정규 표현식 패턴과 일치하는 모든 부분 문자열을 찾아 그 개수를 정수로 반환하며, 없으면 0을 반환합니다.
  • 일치하는 모든 부분 문자열을 각각의 요소들로 구성된 배열로도 저장할 수 있습니다. 매개변수에 할당할 변수를 지정하면 됩니다.
  • 이메일 주소, URL, HTML 태그와 같은 특정 패턴의 문자열을 검사할 때 유용합니다.

기본 예제

PHP 
/* 문자열에서
   모든 일치하는 정규 표현식 패턴의 문자열을 찾아서
   그 개수를 정수로 반환합니다. */

// 주어진 문자열
$str = 'apple orange banana apple';

// 검색할 정규 표현식 패턴
$pattern = '/apple/';

// 함수에 적용 및 결과 반환
$result = preg_match_all($pattern, $str);
var_dump($result); // 출력: int(2)

/* 일치하는 모든 부분 문자열을
   각각의 요소들로 구성된 배열로도 저장할 수 있습니다.
   세 번째 매개변수에 할당할 변수를 지정하면 됩니다. */

// 세 번째 매개변수에 할당할 변수($matches) 지정
$result = preg_match_all($pattern, $str, $matches);

// 할당된 배열 확인
print_r($matches);
/* 출력:
Array
(
    [0] => Array
        (
            [0] => apple
            [1] => apple
        )

)
*/

문자열 내에서 정규 표현식을 사용하여 특정 패턴을 찾아 다른 문자열로 바꾸려면 preg_replace() 함수를 사용하세요.

구문

PHP 
preg_match_all(
    string $pattern,
    string $subject,
    array &$matches = null,
    int $flags = 0,
    int $offset = 0
): int|false

/* preg_match_all(
	패턴,
	검색 대상이 되는 문자열[,
	일치하는 부분을 저장할 배열[, 
	추가적인 설정을 지정하는 플래그[, 
	검색을 시작할 문자열 내의 오프셋]]]
);
*/

매개변수

preg_match_all() 함수의 매개변수 설명
$pattern 필수. 검색할 정규 표현식 패턴입니다.
$subject 필수. 검색 대상이 되는 문자열입니다.
&$matches 옵션. 정규 표현식 패턴에 일치하는 결과를 저장할 배열입니다.
이 배열은 함수 호출 후에 채워집니다. (참조 변수입니다.)
  • $flags에 따라 정렬된 다차원 배열입니다.
  • $matches 배열은 함수가 실행된 후에 일치하는 부분 문자열들로 채워집니다.
  • $matches[0]: 정규 표현식 패턴과 일치하는 모든 부분 문자열을 각각의 요소들로 구성된 배열입니다.
    각 하위 요소($matches[0][0], $matches[0][1], ..., $matches[0][n])는 순서대로 매칭된 문자열입니다.
  • $matches[1], $matches[2], ..., $matches[n]: 정규 표현식에서 패턴에 괄호로 묶인 그룹(캡처 그룹)에 일치하는 문자열로 구성된 배열입니다. 예를 들어, $matches[1][0]은 첫 번째 그룹에 일치하는 첫 번째 문자열입니다. 만약 패턴에 캡쳐 그룹이 없다면 이러한 인덱스는 존재하지 않습니다.
$flags 옵션. 매칭 결과 배열의 정렬 방식을 지정하는 플래그입니다.
이 값을 생략하여 정렬 관련 플래그를 지정하지 않은 경우 기본값인 0이 지정되며, PREG_PATTERN_ORDER 방식이 기본으로 적용됩니다.
다음과 같은 플래그들을 조합하여 사용할 수 있습니다.
  • PREG_PATTERN_ORDER: 매칭 결과를 패턴 기준으로 정렬합니다. (캡처 그룹이 있다면 그룹 단위로 정렬)
    각 배열 $matches의 첫 번째 요소 $matches[0]에는 전체 패턴 매칭이 순서대로 들어갑니다.
    캡처 그룹이 있다면 $matches[1], $matches[2] ... 에 각 그룹에 매칭된 문자열들이 배열로 저장됩니다.
  • PREG_SET_ORDER: 매칭된 결과를 한 번의 매칭 단위로 묶어 정렬합니다.
    각 매칭 결과 배열의 첫 번째 요소 $matches[n][0]는 전체 패턴 매칭이며, 캡처 그룹이 있다면 $matches[n][1], $matches[n][2] ... 에 각 그룹에 매칭된 문자열이 들어갑니다.
    (PREG_PATTERN_ORDER와 함께 사용할 수 없습니다.)
  • PREG_OFFSET_CAPTURE: 각 매칭 결과에 문자열의 시작 위치(offset) 인덱스를 함께 저장합니다.
    이 경우 $matches의 각 요소는 [일치한 문자열, 시작 위치 인덱스] 형태의 배열이 됩니다.
    캡처 그룹이 있다면 각 그룹에도 동일하게 [문자열, 시작 위치] 배열이 적용됩니다.
  • PREG_UNMATCHED_AS_NULL: 정규 표현식에서 일치하지 않은 하위 패턴(subpattern)을 null로 처리합니다.
    이 플래그를 사용하지 않으면 일치하지 않은 하위 패턴은 빈 문자열('')로 처리됩니다.
    캡처 그룹이 없는 경우 이 플래그는 의미가 없습니다.
$offset 옵션. 검색을 시작할 문자열 내의 오프셋입니다. 0부터 시작합니다.
이 값을 지정하면 문자열의 해당 인덱스 위치(바이트 단위)부터 정규 표현식 검색이 수행됩니다.

참고하세요!
다른 언어(예: JavaScript)에서 전체 검색을 위해 사용하는 g (Global) 플래그가 있어야 모든 패턴의 매칭을 찾지만(예: JavaScript의 문자열 match() 함수), PHP의 정규 표현식과 관련된 PCRE 함수(예: preg_match(), preg_match_all())에서는 g 플래그를 사용하지 않습니다.

변경 이력

preg_match_all() 함수의 변경 이력
버전설명
7.2.0 이제는 $flags 매개변수의 값으로 PREG_UNMATCHED_AS_NULL 플래그를 사용할 수 있습니다.

반환 값

  • 정규 표현식 패턴과 일치하는 모든 부분 문자열을 찾아 그 개수를 정수로 반환합니다.
  • 일치하는 패턴을 찾지 못하면 0을 반환합니다.
  • 일치한 항목들을 담은 배열을 이 함수의 매개변수로 전달한 변수에 할당합니다.
  • 에러가 발생한 경우 false를 반환하며, 전달된 정규 표현식 패턴이 유효하지 않으면 E_ERROR가 발생합니다.

정규 표현식 패턴에 일치하는 결과와 반환 값 예시

일치하는 모든 부분의 개수를 반환

preg_match_all() 함수는 대상 문자열에서 모든 일치하는 부분을 찾습니다. 반환 값은 일치하는 부분의 총 개수가 됩니다.

PHP 
$pattern = '/apple/';
$subject = "apple orange banana apple";

$result = preg_match_all($pattern, $subject);

if ($result !== false) {
    var_dump($result); // 출력: int(2)
}

반면에 이 함수와 유사한 preg_match() 함수는
일치하는 패턴을 문자열에서 처음으로 발견되면 검색을 중단하고 1을 반환합니다.

일치하는 패턴을 찾지 못하면 0을 반환

일치하는 패턴을 찾지 못하면 0을 반환합니다. 여기에서 주의할 점은 false를 반환하지 않는다는 것입니다. false는 에러가 발생한 경우에 반환됩니다.

PHP 
$pattern = '/grape/';
$subject = "apple orange banana apple";

$result = preg_match_all($pattern, $subject);

if ($result !== false) {
    var_dump($result); // 출력: int(0)
}
에러가 발생하면 false를 반환
PHP 
error_reporting(0); // 에러 표시 비활성화

$pattern = '/apple'; // 유효하지 않은 정규 표현식을 사용
$subject = "apple orange banana apple";

$result = preg_match_all($pattern, $subject);

if ($result !== false) {
    var_dump($result);
} else {
	 echo '에러가 발생했습니다.';
}

// 출력: '에러가 발생했습니다.'
일치한 항목들을 담은 배열을 매개변수로 전달한 변수에 할당

preg_match_all() 를 사용하여 일치한 항목들을 담은 배열을 다른 변수에 할당하려면 해당 배열을 참조로 전달하면 됩니다.
먼저 예시를 통해 살펴보겠습니다.

PHP 
// 주어진 문자열에서 숫자 찾기
$string = '이것은 123과 456을 포함한 샘플 텍스트입니다.';

// 패턴: 숫자 찾기
$pattern = '/\d+/';

// $matches라는 빈 배열을 선언하여 할당할 공간을 마련합니다.
$matches = array();

// $matches를 매개변수에 할당합니다.
$num_of_matches = preg_match_all($pattern, $string, $matches);

// 결과 출력
if ($num_of_matches > 0) {
	var_dump($matches); // array(1) { [0]=> array(2) { [0]=> string(3) "123" [1]=> string(3) "456" } }
}

여기서 preg_match_all() 함수의 세 번째 매개변수로 $matches 배열을 전달하고 있습니다. 이때 $matches 배열은 함수 호출 후에 일치하는 부분 문자열들로 채워집니다. 코드에서 print_r($matches)를 통해 배열의 내용을 출력하고 있습니다.

이렇게 하면 $matches 배열에 일치한 항목들이 할당되며, 함수 외부에서도 이 값을 사용할 수 있습니다.

정규 표현식에 캡처 그룹이 있을 때 $flags와 반환 값 예시

preg_match_all() 함수는 단순히 모든 매칭을 찾아 반환할 뿐만 아니라, 매개변수에서 지정하는 $flags의 값과 지정하는 정규 표현식에 캡처 그룹의 유무에 따라 결과 배열 구조가 많이 달라집니다.

다음은 지정하는 정규 표현식에서 캡처 그룹이 있을 경우 $flags의 값에 따라 결과 배열이 달라지는 예시입니다.

PREG_PATTERN_ORDER

매칭 결과를 패턴의 캡쳐 그룹 기준으로 정렬합니다.
$matches[0]에는 전체 패턴에 일치한 문자열들이, $matches[1], $matches[2], … 에는 각 괄호 그룹에 일치한 문자열들이 배열로 저장됩니다. 캡처 그룹이 없다면 $matches[0]을 제외한 나머지 인덱스는 존재하지 않습니다.

PHP 
// 예제 문자열
$string = "apple orange banana apple";

// 정규식 패턴: 'apple' 또는 'orange'를 찾고 괄호 그룹으로 묶음
$pattern = '/(apple|orange)/';

// PREG_PATTERN_ORDER 사용
// - 매칭 결과를 패턴(캡처 그룹) 기준으로 정렬
// - $matches    : 결과를 할당할 배열 변수
// - $matches[0] : 전체 패턴에 일치한 문자열들
// - $matches[1] : 첫 번째 괄호 그룹에 일치한 문자열들
preg_match_all($pattern, $string, $matches, PREG_PATTERN_ORDER);

// 결과 출력
print_r($matches);

/*
출력:
Array
(
    [0] => Array ( [0] => apple [1] => orange [2] => apple )
    [1] => Array ( [0] => apple [1] => orange [2] => apple )
)
*/
PREG_SET_ORDER

매칭된 결과를 한 번의 매칭 단위로 묶어 정렬합니다.
각 매칭 결과 배열의 첫 번째 요소 $matches[n][0]는 전체 패턴 매칭이며, 캡처 그룹이 있다면 $matches[n][1], $matches[n][2] ... 에 각 그룹에 매칭된 문자열이 들어갑니다. 캡처 그룹이 없다면 $matches[n][1], $matches[n][2] ...은 존재하지 않습니다.
(PREG_PATTERN_ORDER와 함께 사용할 수 없습니다.)

PHP 
// 예제 문자열
$string = "apple orange banana apple";

// 정규식 패턴: 'apple' 또는 'orange'를 찾고 괄호 그룹으로 묶음
$pattern = '/(apple|orange)/';

// PREG_SET_ORDER 사용
// - 매칭된 결과를 한 번의 매칭 단위로 묶어 정렬
// - $matches                    : 결과를 할당할 배열 변수
// - $matches[0], $matches[1], … : 각각 한 번의 매칭 결과
preg_match_all($pattern, $string, $matches, PREG_SET_ORDER);

// 결과 출력
print_r($matches);

/*
출력:
Array
(
    [0] => Array ( [0] => apple [1] => apple )   // 첫 번째 매칭: 전체 + 첫 번째 그룹
    [1] => Array ( [0] => orange [1] => orange ) // 두 번째 매칭: 전체 + 첫 번째 그룹
    [2] => Array ( [0] => apple [1] => apple )   // 세 번째 매칭: 전체 + 첫 번째 그룹
)
*/
PREG_OFFSET_CAPTURE

각 매칭 결과에 문자열의 시작 위치(offset) 인덱스를 함께 저장합니다.
이 경우 $matches의 각 요소는 [일치한 문자열, 시작 위치 인덱스] 형태의 배열이 됩니다. 캡처 그룹이 있다면 각 그룹에도 동일하게 [문자열, 시작 위치] 배열이 적용됩니다.

PHP 
// 예제 문자열
$string = "apple orange banana apple";

// 정규식 패턴: 'apple' 또는 'orange'를 찾고 괄호 그룹으로 묶음
$pattern = '/(apple|orange)/';

// PREG_OFFSET_CAPTURE 사용
// - 각 매칭 결과에 문자열의 시작 위치(offset)를 함께 저장
// - $matches : 결과를 할당할 배열 변수
// - $matches의 각 요소는 [일치한 문자열, 시작 위치 인덱스] 형태
preg_match_all($pattern, $string, $matches, PREG_OFFSET_CAPTURE);

// 결과 출력
print_r($matches);

/*
출력:
Array
(
    [0] => Array ( 
        [0] => Array("apple", 0)    // 전체 패턴 첫 번째 매칭과 위치
        [1] => Array("orange", 6)   // 전체 패턴 두 번째 매칭과 위치
        [2] => Array("apple", 19)   // 전체 패턴 세 번째 매칭과 위치
    )
    [1] => Array ( 
        [0] => Array("apple", 0)    // 첫 번째 그룹 첫 번째 매칭과 위치
        [1] => Array("orange", 6)   // 첫 번째 그룹 두 번째 매칭과 위치
        [2] => Array("apple", 19)   // 첫 번째 그룹 세 번째 매칭과 위치
    )
)
*/
PREG_UNMATCHED_AS_NULL

정규 표현식에서 일치하지 않은 하위 패턴(subpattern)을 null로 처리합니다. 이 플래그를 사용하지 않으면 빈 문자열('')로 처리합니다. 캡처 그룹이 없는 경우 이 플래그는 의미가 없습니다.

PHP 
// 예제 문자열
$string = "apple banana";

// 정규식 패턴: 'apple', 'banana', 'orange' 세 그룹
$pattern = '/(apple)|(banana)|(orange)/';

// PREG_UNMATCHED_AS_NULL 사용
// - 일치하지 않은 하위 패턴(subpattern)을 null로 처리
// - $matches : 결과를 할당할 배열 변수
// - $matches[0], $matches[1], ... 각 그룹의 매칭이 null 또는 문자열로 저장
preg_match_all($pattern, $string, $matches, PREG_PATTERN_ORDER | PREG_UNMATCHED_AS_NULL);

// 결과 출력
print_r($matches);

/*
출력:
Array
(
    [0] => Array ( [0] => apple [1] => banana )   // 전체 패턴 매칭
    [1] => Array ( [0] => apple [1] => null )     // 첫 번째 그룹: 'apple'만 매칭
    [2] => Array ( [0] => null [1] => banana )    // 두 번째 그룹: 'banana'만 매칭
    [3] => Array ( [0] => null [1] => null )      // 세 번째 그룹: 'orange' 매칭 없음 → null
)
*/

활용 예제

preg_match_all() 함수는 이메일 주소, URL과 같은 특정 패턴의 문자열을 검사할 때 유용합니다. 또한, 다양한 상황에서 유용하게 활용될 수 있습니다. 여기에는 몇 가지 예제를 다룹니다.

이메일 주소 검사

PHP 
$string = '문의는 help@example.com 또는 support@example.org 으로 연락 주시기 바랍니다.';
$pattern = '/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/';
$matches = array();

$result = preg_match_all($pattern, $string, $matches);

if ($result !== false && $result > 0) {
    print_r($matches[0]);       // 모든 매칭 이메일 출력
    echo "\n첫 번째 이메일: " . $matches[0][0]; // 첫 번째 이메일만 출력
} else {
    echo '이메일 주소 형식이 없습니다.';
}

// 출력:
// Array ( [0] => help@example.com [1] => support@example.org )
// 첫 번째 이메일: 'help@example.com'

URL 검사

PHP 
$string = '더 많은 정보는 https://www.example.com에서 확인하세요.';
$pattern = '/\b(?:https?:\/\/)?(?:www\.)?[a-zA-Z0-9-]+(?:\.[a-z]{2,})+(?:\/[^\s]*)?\b/';
$matches = array();

$result = preg_match_all($pattern, $string, $matches);

if ($result !== false && $result > 0) {
    echo $matches[0][0]; // 첫 번째 매칭 URL 출력
} else {
    echo 'URL 형식이 없습니다.';
}

// 출력: 'https://www.example.com'

HTML에서 태그를 추출

PHP 
$html = '<div class="container"><p>Hello, <b>world!</b></p></div>';
$tagPattern = '/<[^>]+>/';  // HTML 태그를 찾는 정규식
$matches = array();

$result = preg_match_all($tagPattern, $html, $matches);

if ($result !== false && $result > 0) {
    print_r($matches[0]);  // 모든 매칭 태그 출력
} else {
    echo '태그를 찾지 못했습니다.';
}

// 출력:
// Array ( [0] => <div class="container"> [1] => <p> [2] => <b> [3] => </b> [4] => </p> [5] => </div> )

CSS 클래스 선택자 추출

PHP 
$css = '.header { color: #333; } .main-content { font-size: 16px; }';
$classPattern = '/\.([a-zA-Z0-9_-]+)/'; // CSS 클래스 선택자 패턴
$matches = array();

$result = preg_match_all($classPattern, $css, $matches);

if ($result !== false && $result > 0) {
    print_r($matches[0]);  // 매칭된 클래스 선택자 전체 출력
} else {
    echo 'CSS 클래스 선택자를 찾지 못했습니다.';
}

// 출력:
// Array ( [0] => .header [1] => .main-content )

참고문헌

같이 보기