include

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

include 식은 지정된 파일을 포함하고 평가합니다.

아래 문서는 require에도 적용됩니다.

파일은 지정된 파일 경로를 기반으로 포함되거나 지정되지 않은 경우 지정된 include_path를 기반으로 합니다. 파일이 include_path에 없으면 include는 실패하기 전에 호출 스크립트의 자체 디렉토리와 현재 작업 디렉토리를 최종적으로 확인합니다. include 구문은 파일을 찾을 수 없는 경우 E_WARNING을 내보냅니다. 이것은 E_ERROR를 발생시키는 require와는 다른 동작입니다.

파일에 액세스할 수 없는 경우 최종 E_WARNING 또는 E_ERROR를 각각 발생시키기 전에 include 및 require 모두 추가 E_WARNING을 발생시킵니다.

경로가 정의된 경우(Windows에서는 드라이브 문자 또는 \로 시작하거나 Unix/Linux 시스템에서는 /로 시작) 또는 현재 디렉토리(. 또는 ..로 시작)에 상대적인 경로가 정의된 경우 include_path는 완전히 무시됩니다. 예를 들어, 파일 이름이 ../로 시작하면 파서는 요청된 파일을 찾기 위해 상위 디렉토리를 찾습니다.

PHP가 포함 파일 및 포함 경로를 처리하는 방법에 대한 자세한 내용은 include_path 설명서를 참조하십시오.

파일이 포함될 때 포함된 코드는 포함이 발생한 줄의 변수 범위를 상속합니다. 호출 파일의 해당 행에서 사용할 수 있는 모든 변수는 해당 지점부터 호출된 파일 내에서 사용할 수 있습니다. 그러나 포함된 파일에 정의된 모든 함수와 클래스는 전역 범위를 갖습니다.

예제 #1 기본 include 예제

                  
vars.php
<?php

$color = 'green';
$fruit = 'apple';

?>

test.php
<?php

echo "A $color $fruit"; // A

include 'vars.php';

echo "A $color $fruit"; // A green apple

?>
                  
                

호출 파일 내의 함수 내부에서 포함이 발생하면 호출된 파일에 포함된 모든 코드는 마치 해당 함수 내부에 정의된 것처럼 작동합니다. 따라서 해당 함수의 변수 범위를 따릅니다. 이 규칙의 예외는 포함이 발생하기 전에 파서에 의해 평가되는 매직 상수입니다.

예제 #2 함수 내 포함

                  
<?php

function foo()
{
    global $color;

    include 'vars.php';

    echo "A $color $fruit";
}

/* vars.php is in the scope of foo() so     *
* $fruit is NOT available outside of this  *
* scope.  $color is because we declared it *
* as global.                               */

foo();                    // A green apple
echo "A $color $fruit";   // A green

?>
                  
                

파일이 포함되면 대상 파일의 시작 부분에서 구문 분석이 PHP 모드에서 HTML 모드로 떨어지고 끝 부분에서 다시 시작됩니다. 이러한 이유로 PHP 코드로 실행되어야 하는 대상 파일 내의 모든 코드는 유효한 PHP 시작 및 종료 태그로 묶어야 합니다.

PHP에서 "URL include wrappers"가 활성화된 경우 로컬 경로 이름 대신 URL(HTTP 또는 기타 지원되는 래퍼를 통해 - 프로토콜 목록은 지원되는 프로토콜 및 래퍼 참조)을 사용하여 포함할 파일을 지정할 수 있습니다. 대상 서버가 대상 파일을 PHP 코드로 해석하는 경우 HTTP GET과 함께 사용되는 URL 요청 문자열을 사용하여 포함된 파일에 변수를 전달할 수 있습니다. 이것은 파일을 포함하고 상위 파일의 변수 범위를 상속받는 것과 엄밀히 말하면 같은 것이 아닙니다. 스크립트는 실제로 원격 서버에서 실행되고 결과는 로컬 스크립트에 포함됩니다.

예제 #3 include through HTTP

                  
<?php

/* This example assumes that www.example.com is configured to parse .php
* files and not .txt files. Also, 'Works' here means that the variables
* $foo and $bar are available within the included file. */

// Won't work; file.txt wasn't handled by www.example.com as PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';

// Won't work; looks for a file named 'file.php?foo=1&bar=2' on the
// local filesystem.
include 'file.php?foo=1&bar=2';

// Works.
include 'http://www.example.com/file.php?foo=1&bar=2';
?>
                  
                

관련 정보는 원격 파일, fopen() 및 file()도 참조하십시오.

반환 처리: include는 실패 시 FALSE를 반환하고 경고를 발생시킵니다. 포함된 파일에 의해 재정의되지 않는 한 성공적인 포함은 1을 반환합니다. 포함된 파일 내에서 return 문을 실행하여 해당 파일에서 처리를 종료하고 이를 호출한 스크립트로 돌아갈 수 있습니다. 또한 포함된 파일에서 값을 반환할 수 있습니다. 일반 함수와 마찬가지로 포함 호출의 값을 취할 수 있습니다. 그러나 이것은 원격 파일의 출력에 유효한 PHP 시작 및 종료 태그(로컬 파일에서와 같이)가 없는 경우 원격 파일을 포함할 때 가능하지 않습니다. 해당 태그 내에서 필요한 변수를 선언할 수 있으며 파일이 포함된 모든 지점에서 도입됩니다.

include는 특수 언어 구성이므로 인수 주위에 괄호가 필요하지 않습니다. 반환 값을 비교할 때 주의하십시오.

예제 #4 include의 반환 값 비교

                  
<?php
// won't work, evaluated as include(('vars.php') == TRUE), i.e. include('1')
if (include('vars.php') == TRUE) {
    echo 'OK';
}

// works
if ((include 'vars.php') == TRUE) {
    echo 'OK';
}
?>
                  
                

예제 #5 include 및 return 문

                  
return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // prints 'PHP'

$bar = include 'noreturn.php';

echo $bar; // prints 1

?>
                  
                

include에 성공했기 때문에 $bar는 값 1입니다. 위의 예 사이의 차이점을 확인하십시오. 첫 번째는 포함된 파일 내에서 return을 사용하는 반면 다른 하나는 그렇지 않습니다. 파일을 포함할 수 없으면 false가 반환되고 E_WARNING이 발행됩니다.

인클루드 파일에 정의된 함수가 있다면 return 전이든 후이든 상관없이 메인 파일에서 독립적으로 사용할 수 있다. 파일이 두 번 포함되면 함수가 이미 선언되었기 때문에 PHP에서 치명적인 오류가 발생합니다. 파일이 이미 포함되어 있고 포함된 파일 내부에 조건부로 반환되는지 확인하는 대신 include_once를 사용하는 것이 좋습니다.

PHP 파일을 변수에 "include"하는 또 다른 방법은 include과 함께 출력 제어 함수를 사용하여 출력을 캡처하는 것입니다. 예를 들어:

예제 #6 출력 버퍼링을 사용하여 PHP 파일을 문자열에 포함

                  
<?php
$string = get_include_contents('somefile.php');

function get_include_contents($filename) {
    if (is_file($filename)) {
        ob_start();
        include $filename;
        return ob_get_clean();
    }
    return false;
}

?>
                  
                

스크립트 내에 파일을 자동으로 포함하려면 php.ini의 auto_prepend_file 및 auto_append_file 구성 옵션도 참조하십시오.

참고: 이것은 함수가 아닌 언어 구성이므로 변수 함수를 사용하여 호출할 수 없습니다.

require, require_once, include_once, get_included_files(), readfile(), virtual() 및 include_path도 참조하십시오.