أساسيات PHP

Include و Require

13 دقيقة الدرس 8 من 45

Include و Require في PHP

توفر PHP آليات تضمين الملفات التي تسمح لك بإدراج محتوى ملف PHP في آخر. هذا أساسي لإعادة استخدام الكود والتصميم المعياري والحفاظ على مبدأ DRY (لا تكرر نفسك).

عبارة include

عبارة include تتضمن وتقيّم الملف المحدد:

<?php
// تضمين ملف:
include 'header.php';

echo "<h1>المحتوى الرئيسي</h1>";

include 'footer.php';
?>

ملاحظة: إذا لم يتم العثور على الملف، تنتج include تحذيراً (E_WARNING) لكن السكريبت يستمر في التنفيذ.

عبارة require

عبارة require مطابقة لـ include باستثناء أنها تنتج خطأ فادحاً إذا لم يتم العثور على الملف:

<?php
// طلب ملف حيوي:
require 'config.php';
require 'database.php';

// إذا لم يكن config.php موجوداً، يتوقف السكريبت هنا
echo "هذا لن يعمل إذا فشل require";
?>

تحذير: استخدم require للملفات الحيوية (مثل الإعدادات أو اتصالات قاعدة البيانات) الأساسية لتشغيل تطبيقك. استخدم include للملفات الاختيارية (مثل القوالب أو الوحدات الاختيارية).

عبارات include_once و require_once

هذه المتغيرات تضمن تضمين الملف مرة واحدة فقط، حتى لو تم استدعاؤه عدة مرات:

<?php
// تضمين الملف مرة واحدة فقط:
include_once 'functions.php';
include_once 'functions.php'; // هذا لن يتضمن مرة أخرى

// طلب الملف مرة واحدة فقط:
require_once 'config.php';
require_once 'config.php'; // هذا لن يطلب مرة أخرى
?>

نصيحة: استخدم متغيرات _once عند تضمين ملفات تحدد دوال أو فئات أو ثوابت لتجنب أخطاء "معرّف بالفعل".

جدول المقارنة

العبارة	عند الفشل	التضمينات المتعددة	حالة الاستخدام
`include`	تحذير (السكريبت يستمر)	مسموح	قوالب اختيارية، عروض
`require`	خطأ فادح (السكريبت يتوقف)	مسموح	ملفات حيوية، مكتبات أساسية
`include_once`	تحذير (السكريبت يستمر)	مرة واحدة فقط	دوال اختيارية، مساعدات
`require_once`	خطأ فادح (السكريبت يتوقف)	مرة واحدة فقط	فئات، إعدادات، دوال

مسارات الملفات

يمكنك استخدام مسارات مطلقة أو نسبية أو ديناميكية عند تضمين الملفات:

<?php
// مسار نسبي (من الدليل الحالي):
include 'header.php';
include './header.php'; // نفس الشيء أعلاه
include '../shared/functions.php'; // الدليل الأب

// مسار مطلق:
include '/var/www/html/includes/config.php';

// استخدام ثابت __DIR__ (موصى به):
include __DIR__ . '/includes/config.php';

// استخدام المتغيرات:
$template = 'default';
include "templates/{$template}/header.php";
?>

نصيحة: استخدم __DIR__ لحل المسار الموثوق. يرجع دليل الملف الحالي، مما يجعل تضميناتك تعمل بغض النظر عن مكان استدعاء السكريبت.

أمثلة عملية

مثال 1: إنشاء ملف رأس الصفحة

الملف: includes/header.php

<!DOCTYPE html>
<html lang="ar" dir="rtl">
<head>
    <meta charset="UTF-8">
    <title><?php echo $pageTitle ?? 'موقعي'; ?></title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <header>
        <nav>
            <a href="index.php">الرئيسية</a>
            <a href="about.php">من نحن</a>
            <a href="contact.php">اتصل بنا</a>
        </nav>
    </header>
    <main>

الملف: includes/footer.php

    </main>
    <footer>
        <p>&copy; <?php echo date('Y'); ?> موقعي</p>
    </footer>
</body>
</html>

الملف: index.php

<?php
$pageTitle = "الصفحة الرئيسية";
include 'includes/header.php';
?>

<h1>مرحباً بك في موقعي</h1>
<p>هذا هو المحتوى الرئيسي.</p>

<?php include 'includes/footer.php'; ?>

مثال 2: ملف الإعدادات

الملف: config.php

<?php
// إعدادات قاعدة البيانات:
define('DB_HOST', 'localhost');
define('DB_USER', 'root');
define('DB_PASS', 'password');
define('DB_NAME', 'myapp');

// إعدادات التطبيق:
define('APP_NAME', 'تطبيقي');
define('APP_URL', 'https://example.com');
define('DEBUG_MODE', true);

// المنطقة الزمنية:
date_default_timezone_set('Asia/Riyadh');
?>

الملف: index.php

<?php
require_once 'config.php';

echo "مرحباً بك في " . APP_NAME;

if (DEBUG_MODE) {
    error_reporting(E_ALL);
    ini_set('display_errors', 1);
}
?>

مثال 3: مكتبة الدوال

الملف: functions.php

<?php
function sanitize($data) {
    return htmlspecialchars(strip_tags(trim($data)));
}

function redirect($url) {
    header("Location: $url");
    exit;
}

function formatDate($date) {
    return date('Y-m-d', strtotime($date));
}

function isLoggedIn() {
    return isset($_SESSION['user_id']);
}
?>

استخدام الدوال:

<?php
require_once 'functions.php';

$userInput = $_POST['name'] ?? '';
$cleanInput = sanitize($userInput);

if (!isLoggedIn()) {
    redirect('login.php');
}
?>

نطاق المتغيرات في الملفات المضمنة

المتغيرات المعرفة في ملف مضمن متاحة في النطاق المضمّن:

<?php
// الملف: vars.php
$greeting = "مرحباً";
$name = "أحمد";

// الملف: main.php
include 'vars.php';
echo "$greeting، $name"; // الناتج: مرحباً، أحمد

// المتغيرات من main.php متاحة أيضاً في الملفات المضمنة:
$color = "أزرق";
include 'display.php'; // يمكن الوصول إلى $color
?>

قيم الإرجاع من الملفات المضمنة

يمكن للملفات المضمنة إرجاع قيم باستخدام عبارة return:

<?php
// الملف: config.php
return [
    'database' => [
        'host' => 'localhost',
        'user' => 'root',
        'pass' => 'password'
    ],
    'app' => [
        'name' => 'تطبيقي',
        'version' => '1.0.0'
    ]
];

// الملف: index.php
$config = include 'config.php';
echo $config['app']['name']; // الناتج: تطبيقي
?>

نصيحة: إرجاع المصفوفات من ملفات الإعدادات نمط شائع في أطر عمل PHP الحديثة. يحافظ على نظافة الإعدادات ويمنع تلوث الفضاء العام.

التضمينات الشرطية

يمكنك تضمين الملفات بشكل مشروط بناءً على المنطق:

<?php
$userRole = 'admin';

// تضمين ملفات مختلفة بناءً على الشروط:
if ($userRole === 'admin') {
    include 'admin-panel.php';
} else {
    include 'user-dashboard.php';
}

// التضمين بناءً على الوجود:
if (file_exists('custom-theme.php')) {
    include 'custom-theme.php';
} else {
    include 'default-theme.php';
}
?>

الأنماط الشائعة وأفضل الممارسات

1. نمط بنية الدليل

project/
├── includes/
│   ├── config.php
│   ├── functions.php
│   └── database.php
├── templates/
│   ├── header.php
│   └── footer.php
└── index.php

2. نمط الإقلاع

<?php
// الملف: bootstrap.php - تحميل جميع الملفات الأساسية:
require_once __DIR__ . '/config.php';
require_once __DIR__ . '/functions.php';
require_once __DIR__ . '/database.php';

session_start();

// الملف: index.php
require_once 'bootstrap.php';
// جميع الأساسيات محملة الآن
?>

3. نمط القالب

<?php
function render($template, $data = []) {
    extract($data); // تحويل مفاتيح المصفوفة إلى متغيرات
    include __DIR__ . "/templates/{$template}.php";
}

// الاستخدام:
render('header', ['title' => 'الصفحة الرئيسية']);
render('product', ['name' => 'لابتوب', 'price' => 999]);
render('footer');
?>

اعتبارات الأمان

تحذير أمني: لا تضمّن أبداً ملفات بناءً على إدخال المستخدم دون التحقق. يمكن أن يؤدي هذا إلى ثغرات أمنية خطيرة!

<?php
// خطير - لا تفعل هذا أبداً:
$page = $_GET['page'];
include $page . '.php'; // يمكن للمستخدم تضمين أي ملف!

// آمن - استخدم التحقق من القائمة البيضاء:
$page = $_GET['page'] ?? 'home';
$allowedPages = ['home', 'about', 'contact'];

if (in_array($page, $allowedPages)) {
    include "pages/{$page}.php";
} else {
    include 'pages/404.php';
}
?>

اعتبارات الأداء

<?php
// استخدم require_once للملفات المضمنة بشكل متكرر مع الدوال/الفئات:
require_once 'functions.php';

// include العادي أسرع إذا كنت متأكداً من عدم تضمين الملف بعد:
include 'template.php';

// للتطبيقات الكبيرة، فكر في استخدام التحميل التلقائي بدلاً من ذلك:
spl_autoload_register(function ($class) {
    include "classes/{$class}.php";
});
?>

تمرين تطبيقي

المهمة: إنشاء نظام مدونة بسيط:

أنشئ ملف config.php مع اسم الموقع وإعدادات المنطقة الزمنية
أنشئ ملف functions.php مع دالة لتنظيف النص وتنسيق التواريخ
أنشئ قوالب header.php و footer.php
أنشئ index.php الذي يتضمن جميع الملفات ويعرض مشاركة مدونة
إضافة: أنشئ دالة renderPost($title, $content, $date) التي تعرض مشاركة مدونة منسقة
إضافي: نفذ نظام توجيه الصفحات الذي يتضمن بشكل آمن صفحات مختلفة بناءً على معاملات URL

أفضل الممارسات

استخدم require أو require_once للملفات الحيوية
استخدم include أو include_once للملفات الاختيارية
استخدم دائماً متغيرات _once للملفات التي تحتوي على دوال أو فئات أو ثوابت
استخدم __DIR__ لحل المسار الموثوق
احتفظ بالملفات المضمنة في أدلة منظمة (includes/, templates/, config/)
لا تضمّن أبداً الملفات بناءً على إدخال المستخدم غير المحقق
استخدم نهج القائمة البيضاء عند تضمين الملفات المختارة من المستخدم
فكر في استخدام التحميل التلقائي لملفات الفئات في التطبيقات الكبيرة
أرجع المصفوفات من ملفات الإعدادات بدلاً من تعريف الثوابت العامة
تحقق من وجود الملف قبل تضمين الملفات الاختيارية