دستور include

عبارت include فایلی را که مشخص کرده اید فراخوانی و ارزیابی می کند. توضیحات زیر در مورد دستور require نیز صدق می کند.

فایل ها بر اساس مسیری که برای آن مشخص شده است فراخوانی می شوند، و اگر مسیری مشخص نشده باشد، بر اساس مقدار تعیین شده در include_path فراخوانی می شوند. اگر فایل شما در داخل دایرکتوری(پوشه) مشخص شده در include_path وجود نداشته باشد، در نهایت دستور include پوشه ای که اسکریپت از داخل آن اجرا شده و دایرکتوری فعلی را قبل از بروز هرنوع خطا بررسی می کند. اگر دستور include نتواند فایل را پیدا کند، یک هشدار نمایش داده می شود؛ این رفتار با رفتار دستور require متفاوت است، چون دستور require در این حالت یک خطای مرگبار (Fatal Error) را بوجود می آورد.

اگر یک مسیر مشخص شده باشد – مسیر در ویندوز با یک حرف درایور یا علامت بک اسلش \ آغاز می شود، یا در لینوکس و یونیکس با اسلش / - مقدار تعیین شده در include_path به طور کلی نادیده گرفته می شود. به عنوان مثال اگر نام یک فایل با عبارت ../ شروع شود، پردازشگر در داخل پوشه والد (یک پوشه بالاتر) به دنبال آن می گردد تا فایل درخواست شده را پیدا نماید.

برای به دست آوردن اطلاعات بیشتر در مورد اینکه پی اچ پی چگونه فایلها را دستکاری می کند و مسیر را چگونه مشخص می کند، مستندات مربوط به include_path را مطالعه کنید.

هنگامی که یک فایل را فراخوانی می کنید، کدی که در داخل این فایل قرار دارد از لحاظ محدوده متغیرها، از همان خطی (خطی که در فایل اصلی، دستور include در داخل آن قرارداده شده است) تبعیت می کند که دستور include در داخل آن قرار داده شده. از آن نقطه به بعد هر متغیری که در خطی که فایل فراخوانی شده است وجود داشته باشد در داخل فایل فراخوانی شده نیز در دسترس خواهد بود. با این وجود، تمامی توابع و کلاسهایی که در فایل فراخوانی شده وجود دارند دارای محدوده سراسری هستند.

مثال اول: کاربرد دستور 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

?>

اگر دستور include در داخل یک تابع در فایل فراخوانی شده استفاده شود، پس از آن تمام کدهایی که در داخل فایل فراخوانی شده قرار دارند به گونه ای عمل می کنند که گویا در داخل تابع تعریف شده اند. بنابراین از لحاظ محدوده متغیرها، از محدوده تابع تبعیت می کنند. یک استثناء در این مورد وجود دارد: ثابت های جادویی (magic_constants )، پردازشگر آنها را قبل از فراخوانی ارزیابی می کند.

مثال دوم: استفاده از دستور include در داخل توابع

<?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

?>

هنگامی که یک فایل را در داخل یک فایل دیگر فراخوانی می کنیم، پردازش گر از حالت پی اچ پی خارج می شود و در ابتدای فایل هدف وارد حالت اچ تی ام ال می گردد، و سپس دوباره در انتهای فایل، به حالت پی اچ پی بازمی گردد. به همین خاطر تمامی فایل هایی که در داخل فایل هدف قرار دارند و باید به عنوان کدهای پی اچ پی مورد پردازش قرار گیرند باید توسط تگ های معتبر پی اچ پی مشخص شوند.

اگر حالت URL include wrappers در پی اچ پی فعال باشد، شما می توانید به جای اینکه مسیر محلی را مشخص نمایید فایل مورد نظر خود را با استفاده از یو آر ال مشخص کنید (اینکار را می توانید با استفاده از اچ تی تی پی یا سایر بسته بندی های پشتیبانی شده انجام دهید). اگر سرویس دهنده هدف، فایل هدف را به عنوان یک کد پی اچ پی تفسیر کند، ممکن است متغیرها با استفاده از رشته های درخواست (Query Strings) از طریق یو آر ال ( همانگونه که با استفاده از HTTP GET انجام می شود ) برای فایل مورد استفاده، ارسال گردد. این حالت دقیقا شبیه به حالتی نیست که فایل را وارد می کنیم و متغیرها، همان حوزه متغیرهای فایل والد را به ارث می برند؛ در واقع کد بر روی سرور بیرونی اجرا می شود و سپس نتیجه در داخل فایل محلی قرار می گیرد.

مثال سوم: استفاده از دستور include با استفاده از پروتکل 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';

$foo = 1;
$bar = 2;
include 'file.txt';  // Works.
include 'file.php';  // Works.

?>

هشدار امنیتی

فایل های راه دور ممکن است بر روی سرویس دهنده راه دور اجرا شوند (این امر به توسعه فایل - پسوند فایل - شما بستگی دارد و اینکه آیا سرویس دهنده راه دور توانایی اجرای فایل های پی اچ پی را دارد یا خیر). اما در هر صورت این فایل ها باید یک کد پی اچ پی معتبر را ایجاد کنند به خاطر اینکه خروجی آن بر روی سرویس دهنده محلی اجرا خواهد شد. اگر قرار است فایل موجود بر روی سرویس دهنده راه دور پردازش شود و سپس فقط خروجی خود را ارائه کند، استفاده از تابع readfile() بسیار مناسب تر است. در غیر اینصورت، باید مراقبتهای خاصی را به عمل آورید که اسکریپت راه دور کد مورد نظر شما را به صورت معتبر ایجاد نماید.

مدیریت کردن مقادیر بازگشتی: دستور include در هنگام بروز خطا مقدار FALSE را بر می گرداند و یک هشدار را نمایش می دهد. دستور include موفق، حتی اگر با فایل وارد شده جایگزین شده باشد، مقدار 1 را بر می گرداند. می توان مقدار عبارت return را در داخل فایل وارد شده اجرا کرد تا پردازش آن را در داخل آن فایل پایان دهیم و مقدار را به اسکریپتی که آن را فراخوانی کرده است برگردانیم. همچنین می توان مقادیر را از داخل فایل های وارد شده بازگردانیم. شما می توانید مقدار فایل فراخوانی شده را همانگونه که در مورد یک تابع معمولی انجام می دهیم، بازگردانید. این کار در مورد فایلهایی که بر روی یک سرویس دهنده راه دور قرار دارند عملی نیست؛ مگر اینکه خروجی فایل راه دور تگهای استاندارد آغازین و پایانی پی اچ پی را داشته باشند (همانند یک فایل محلی). شما می توانید متغیرهای مورد نیاز را در بین آن تگ ها معرفی کنید و آنها در هر نقطه ای از فایل که وارد شده باشند، معرفی خواهند شد.

از آنجا که دستور include یک ساختار زبانی خاص است، نیازی به استفاده از پرانتز در اطراف آرگومان های آن نیست. در هنگام مقایسه مقادیر بازگشتی بیشتر احتیاط کنید.

مثال چهارم: مقایسه مقدار بازگشتی توسط دستور include

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

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

مثال پنجم: دستور 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

?>

مقدار متغیر $bar عدد 1 است، به این خاطر که فرایند فراخوانی فایل به درستی انجام شده (در این حالت دستور include مقدار 1 را بر می گرداند). به تفاوت بین دو مثال بالا دقت کنید. در مثال اول از عبارت return در داخل فایل فراخوانی شده استفاده کرده ایم در حالی که در فایل دیگر این کار را انجام نداده ایم. اگر فایل را نتوانیم فراخوانی کنیم، مقدار FALSE برگردانده می شود و یک هشدار سطح E_WARNING بروز خواهد کرد.

اگر توابعی وجود دارند که در داخل فایل فراخوانی شده تعریف شده اند، در صورتی که قبل یا بعد از آن توابع از عبارت return استفاده کرده باشیم، می توانیم از آن توابع در داخل فایل اصلی استفاده نماییم. اگر فایل را دو مرتبه فراخوانی کنیم، در پی اچ پی 5 یک خطای مرگبار رخ خواهد داد به خاطر اینکه قبلا تابع ها معرفی شده اند، در پی اچ پی 4 هیچ شکایتی نسبت به توابعی که بعد از return تعریف شده اند وجود ندارد. توصیه می شود به جای اینکه بررسی کنید آیا فایل قبلا فراخوانی شده است یا خیر، از دستور include_once استفاده نمایید.

یک روش دیگر برای اینکه محتوای یک فایل پی اچ پی را در داخل یک متغیر قرار دهید این است که از توابع کنترل خروجی با استفاده از include استفاده کنید. به عنوان مثال:

مثال ششم: استفاده از بافر کردن خروجی برای اینکه مقدار یک عبارت پی اچ پی را در یک رشته قرار دهیم

<?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;
}

?>

به منظور اینکه به صورت خودکار فایل ها را در داخل کدهای خود فراخوانی کنید، به گزینه های پیکربندی auto_prepend_file و auto_append_file توجه کنید.

نکته: به خاطر اینکه این دستور، یک ساختار زبانی است و یک تابع نیست، نمی توان آن را با استفاده از توابع متغیر (Variable functions) فراخوانی کرد.