include()
פקודת include() מספחת ומריצה או מעריכה קובץ מסויים.
הפקודות require() ו-include() זהות בכל מובן חוץ מאשר האופן בו הן מטפלות בשגיאות או בחוסר הצלחה בסיפוח הקובץ. פקודת include() מייצרת אזהרה בעוד שפקודת require() מייצרת Fatal Error - שגיאה שתגרום לעצירת הריצה של הסקריפט. אם ברצונך למנוע את ריצת הסקריפט במקרה שקובץ לא נמצא, יש להשתמש ב-require(). פקודת include() אינה מתנהגת באופן כזה.כמו כן, מומלץ לקבוע את ערכו של include_path.
כאשר קובץ מסופח בעזרת include הוא יורש את מערך המשתנים ברגע הסיפוח. כלומר, כל משתנה שהיה זמין בסקריפט הראשי בנקודת הסיפוח, יהי זמין בתחילת קוד ה-include גם כן.
Example#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
?>
אם הסיפוח מתבצע מתוך פונקציה בסקריפט הראשי, כל הקוד המוכל יתנהג כאילו הוא חלק מהפונקציה עצמה כך שהוא יירש את מערך המשתנים של הפונקציה בלבד.
Example#2 סיפוח מתוך פונקציה
<?php
function foo()
{
global $color;
include 'vars.php';
echo "A $color $fruit";
}
/* vars.inc 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 בתחילת הקובץ. כפועל יוצא, כל קוד מסופח צריך להיות בתגיות פתיחה וסגירה תקניות.
אם מאופשרת אופציית " URL fopen wrappers" (שהיא ברירת מחדל בהגדרות), יש באפשרותינו לציין קישור HTTP במקום שם קובץ מקומי. אם שרת המטרה מפרש קבצי PHP, תיתכן העברת משתנים לקישור בשיטת HTTP GET. זה שונה במקצת מסיפוח של קובץ מקומי היורש את המשתנים מהסקריפט הראשי. הסקריפט המרוחק בעצם מורץ ותוצאתו מסופחת לסקריפט המקומי.
Example#3 שימוש ב-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 'https://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 'https://www.example.com/file.php?foo=1&bar=2';
$foo = 1;
$bar = 2;
include 'file.txt'; // Works.
include 'file.php'; // Works.
?>
מאחר והפקודות include() ו-require() הן מבנה מיוחד בשפה, חובה לעטוף אותן בסוגריים מסולסלים כאשר רוצים להתנות את ביצוען.
Example#4 התנייה של פקודת include()
<?php
// This is WRONG and will not work as desired.
if ($condition)
include $file;
else
include $other;
// This is CORRECT.
if ($condition) {
include $file;
} else {
include $other;
}
?>
ניתן להפעיל פקודת return מתוך קובץ מסופח במטרה לקטוע את הסיפוח ולהחזיר את השליטה לסקריפט הקורא. כמו כן, ניתן להחזיר מידע מקובץ מסופח ולהשתמש במידע בדומה לשימוש בפונקציה רגילה.
Note: בגרסה 3 של PHP לא תיתכן קריאה ל-return() אלא מתוך פונקציה בלבד ולא מתיוך קובץ ראשי או קובץ מסופח.
Example#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
?>
המשתנה $bar יקבל את הערך 1 כי הסיפוח התבצע בהצלחה. שימו לב להבדל בין הדוגמאות הקודמות. הראשונה משתמשת בפקודת return() מקובץ מסופח והשנייה - לא. דרכים נוספות לסיפוח קובץ לתוך משתנים ניתן לממש תוך שימוש ב- fopen(), file() או תוך שימוש ב-include() בשילוב עם פונקציות לשליטה בפלט.
עיין גם בפרקים על require(), require_once(), include_once(), readfile(), virtual() ו- include_path.