include deyimi belirtilen dosyayı betiğe ekler ve içeriğini değerlendirir.
Betiğe dahil edilecek dosyalar önce belirtilen dizinde aranır, eğer bir dizin belirtilmemişse include_path yönergesinde belirtilen yollarda aranır. include dosyayı bulamazsa bir uyarı çıktılar; require için bu davranış bir ölümcül hata olarak kendini gösterir.
Bir dizin belirtilmişse (göreli veya mutlak) include_path yönergesine bakılmaz. Örneğin bir dosya ../ ili başlıyorsa PHP çözümleyicisi dosyayı betiğin bulunduğu dizinin üst dizininde arayacaktır.
PHP'nin dahil edilen dosyaları nasıl ele aldığı include_path yönergesinin açıklamasında ayrıntılı olarak anlatılmıştır.
Bir dosya bir betiğe dahil edildiğinde, bu dosyanın içerdiği kod, dosyanın dahil edildiği satır itibariyle ana betikte geçerli olan değişken uzayını miras alır. Yani, dosyanın dahil edildiği satıra kadar mevcut değişkenlerin hepsi dahil edilen dosyanın içinde kullanılabilir olacaktır. Bunun yanında, dahil edilen dosyada tanımlanmış işlevlerin ve sınıfların tamamı ana betiğin genelinde tanımlanmış sayılır.
Örnek 1 - Basit bir include örneği
vars.php
<?php
$renk = 'yeşil';
$meyve = 'elma';
?>
dnm.php
<?php
echo "Bir $renk $meyve"; // -> Bir
include 'vars.php';
echo "Bir $renk $meyve"; // -> Bir yeşil elma
?>
include deyimi, bir işlevin içinde kullanılırsa dahil edilmek istenen dosyanın içindeki tüm kodlar sanki o işlev içinde tanımlanmış gibi çalıştırılacaktır. Bu durumda dahil edilen dosyadaki kodlar, işlevin, dosyanın dahil edildiği noktadaki değişken uzayını miras alacaktır. Bu kuralın istisnası dosya dahil edilmeden önce çözümleyici tarafından işleme sokulan sihirli sabitlerdir.
Örnek 2 - İşlev içi include kullanımı
<?php
function foo()
{
global $renk;
include 'vars.php';
echo 'Bir $renk $meyve';
}
/* vars.php, foo() işlevinin etki alanındadır
* dolayısıyla $meyve bu alanın dışında
* kullanılamamaktadır. $renk ise global olarak
* tanımlandığından kullanılabilir
*/
foo(); // Bir yeşil elma
echo 'Bir $renk $meyve'; // Bir yeşil
?>
Bir dosya bir betiğe dahil edildiğinde, çözümleme işlemi PHP kipinden çıkıp hedef dosyanın başlangıcında HTML kipine geçer ve dosyanın sonuna kadar HTML kipinde kalır. Bu sebeple, hedef dosyanın içindeki kodlardan PHP kodları olarak çalıştırılacaklar PHP başlangıç ve bitiş etiketleri arasına alınmalıdır.
"URL fopen sarmalayıcıları" PHP'de etkinleştirilmiş ise (öntanımlı yapılandırmada etkindirler), include deyiminde yerel dosya yolu belirtmek yerine (HTTP ya da desteklenen başka bir sarmalayıcı üzerinden - Supported Protocols and Wrappers bölümününe bakınız) bir URL kullanabilirsiniz. Hedef sunucu, hedef dosyayı PHP kodu olarak çalıştırabiliyorsa, ana betikteki değişkenler dahil edilen dosyaya bir URL istek dizgesi olarak HTTP GET ile aktarılabilir. Bu durum dahil edilen dosyaya ana dosyanın değişken uzayını miras olarak bırakmaktan biraz farklı bir şeydir; betik aslında uzak sunucuda çalıştırılıp yerel betiğe sonuçlar dahil edilmektedir.
PHP'nin 4.3.0 öncesi Windows sürümü uzak dosyalara bu işlev üzerinden erişimi allow_url_fopen etkin olsa bile desteklemez.
Örnek 3 - HTTP üzerinden include
<?php
/* Bu örnekte mesela.dom sitesinin .php uzantılı dosyaları
* çalıştırabildiği ama .txt uzantılıları çalıştırmadığı
* varsayılmıştır. Ayrıca, buradaki 'Çalışır'ın manası
* $foo ve $bar değişkenlerinin dahil edilen dosyada kullanılabilir
* olduğudur. */
// Çalışmaz; dosya.txt dosyası mesela.dom sitesinde çalıştırılmaz
include 'http://mesela.dom/dosya.txt?foo=1&bar=2';
// Çalışmaz; yerel dosya sisteminde 'dosya.php?foo=1&bar=2'
// adında bir dosya olarak aranır.
include 'dosya.php?foo=1&bar=2';
// Çalışır.
include 'http://mesela.dom/dosya.php?foo=1&bar=2';
$foo = 1;
$bar = 2;
include 'dosya.txt'; // Çalışır.
include 'dosya.php'; // Çalışır.
?>
Uzaktaki dosya uzaktaki sunucu tarafından işlenebilir (dosyanın uzantısına ve uzaktaki sunucunun PHP çalıştırıp çalıştırmadığına bağlı olarak). Ancak, elde edilecek çıktı yerel sunucuda çalıştırılacağından bu işlemin sonucu mutlaka geçerli bir PHP betiği üretmek olmalıdır. Dosyanın uzaktaki sunucuda işlenip sadece sonucun çıktılanmasını istiyorsanız readfile() işlevi daha iyi bir seçim olacaktır. Aksi takdirde, uzakta çalıştırılan betiğin geçerli ve istenen kodu üretebilmesini güvence altına alabilmek için özel bir çaba harcamak gerekir.
Ayrıca, bu konuyla ilgili olarak Uzaktaki dosyaların kullanımı belgesiyle fopen() ve file() işlevlerine de bakınız.
return kullanımı: Dahil edilen dosyanın içersinde, bu dosyanın işlenmesi durdurmak ve dahil eden betiğe geri dönmek için return kullanılabilir. Ayrıca, dahil edilen dosyalardan değer döndürmek de mümkündür. Normal bir işlevde olduğu gibi, include çağrısından elde edilen değeri bir değişkene atayabilirsiniz. Ancak bu durum, uzaktaki dosyalar için, sadece uzaktaki dosyanın çıktısı geçerli PHP başlangıç ve bitiş etiketlerine sahipse (herhangi yerel bir dosyada olduğu gibi), kullanılabilir. Gerekli değişkenler bu etiketlerin arasında tanımlandığında dosyanın dahil edildiği noktadan itibaren kullanılabilir olacaklardır.
include özel bir dil oluşumu olduğundan, değiştirgesinin parantez içine alınması gerekmez. Dönüş değerini karşılaştırırken buna dikkat edin.
Örnek 4 - include dönüş değerinin karşılaştırılması
<?php
// çalışmaz, include(('vars.php') == 'TAMAM') olarak değerlendirilir,
// sonuç include('') olur
if (include('vars.php') == 'TAMAM') {
echo 'TAMAM';
}
// çalışır
if ((include 'vars.php') == 'TAMAM') {
echo 'TAMAM';
}
?>
Örnek 5 - include ve return deyimleri
return.php
<?php
$var = 'PHP';
return $var;
?>
noreturn.php
<?php
$var = 'PHP';
?>
testreturns.php
<?php
$foo = include 'return.php';
echo $foo; // 'PHP' basar
$bar = include 'noreturn.php';
echo $bar; // 1 basar
?>
include işlemi başarılı olduğundan
$bar, 1 değerine sahiptir.
Yukarıdaki örnekler arasındaki farklara dikkat edin. Birincisi
return deyimini dahil edilen dosyada kullanırken
ikincisi kullanmıyor. Dosya dahil edilemediği durumda, FALSE
döndürülüyor ve bir E_WARNING üretiliyor.
Dahil edilen dosyanın içinde tanımlanmış işlevler varsa, return deyiminden önce ya da sonra olduğundan bağımsız olarak ana betik içersinde kullanılabilirler. Dosya iki defa dahil edilmişse, PHP 5 ölümcül hata verir çünkü bildirilmiş işlevler tekrar bildirilmeye calışılmış olur. PHP 4 ise return'den sonra tanımlanmış işlevler için şikayetçi olmayacaktır. Dosyanın halihazırda dahil edilip edilmediğini kendiniz tespit edip koşula bağlı return çalıştırmak yerine, include_once kullanmanız önerilir.
Bir PHP dosyasını bir değişkene "dahil" etmenin diğer bir yolu, çıktıyı Çıktı Denetim İşlevlerini include ile birlikte kullanarak yakalamaktır. Örnek:
Örnek 6 - Bir PHP dosyasını bir dizgeye dahil etmek için tampon kullanımı
<?php
$string = get_include_contents('somefile.php');
function get_include_contents($filename) {
if (is_file($filename)) {
ob_start();
include $filename;
$contents = ob_get_contents();
ob_end_clean();
return $contents;
}
return false;
}
?>
Betiğinize dosyaları özdevinimli olarak dahil etmek için, php.ini içersindeki auto_prepend_file ve auto_append_file yapılandırma seçeneklerini inceleyebilirsiniz.
Bilginize: Bu bir işlev değil, dil oluşumu olduğundan değişken işlevler kullanılarak çağrılamaz.
Ayrıca, require, require_once, include_once, readfile(), virtual() ve include_path'a da bakınız.