Functions in PHP

📌 ما هي الدالة (Function)؟

الدالة هي كتلة كود قابلة لإعادة الاستخدام تقوم بمهام محددة. بدل ما نكرر نفس الكود أكثر من مرة، بنكتبه داخل دالة ونستدعيه عند الحاجة.

✨ مفهوم DRY:

DRY = Don’t Repeat Yourself
يعني لا تكرر نفسك، وبدل التكرار، استعمل دوال.

🧱 الصيغة الأساسية:

function اسم_الدالة() {
    // الكود
}

✅ المثال بدون استخدام دالة (❌ تكرار الكود):

$name = "Yasin";
echo "Welcome $name<br>";
echo "We're happy to see you $name<br>";
echo "Have a nice day $name<br>";

🎯 المشكلة:
كل مرة تكتب فيها رسالة فيها اسم المستخدم، تكرر نفس الكود يدويًا. ولو أردت تعديل الأسلوب لاحقًا (مثل تغيير “Welcome” إلى “Hello”)، يجب تعديل كل سطر يدويًا.

✅ نفس المثال باستخدام دالة (✅ تطبيق DRY):

function greetUser($name) {
    echo "Welcome $name<br>";
    echo "We're happy to see you $name<br>";
    echo "Have a nice day $name<br>";
}

// استخدام الدالة:
greetUser("Yasin");
greetUser("Ali");

🎯 الفوائد:

• ✔️ إعادة استخدام الكود بسهولة
• ✔️ التعديل مرة واحدة فقط داخل الدالة
• ✔️ تنظيم الكود وقراءة أسهل
• ✔️ توفير وقت وجهد كبير خصوصًا في المشاريع الكبيرة

🔔 ملاحظة:

هذا الأسلوب هو أساس بناء المواقع والأنظمة الضخمة، حيث يتم تجزئة الوظائف إلى دوال ووحدات صغيرة مستقلة.

🧪 مثال:

function sayHello() {
    echo "أهلاً بك في PHP!<br>";
}

sayHello();
sayHello();

📌 النتيجة:

أهلاً بك في PHP!
أهلاً بك في PHP!

✅ المثال 1: دالة للجمع

function add($a, $b) {
    echo "الناتج: " . ($a + $b) . "<br>";
}

add(5, 7); // الناتج: 12

🧠 الشرح:

• add هي الدالة.
• $a و $b هما الـ parameters.
• 5 و 7 هما الـ arguments.

✅ المثال 2: دالة لحساب الفرق (الطرح)

function subtract($x, $y) {
    echo "الفرق: " . ($x - $y) . "<br>";
}

subtract(10, 4); // الفرق: 6

✅ المثال 3: دالة لحساب المساحة (مستطيل)

function area($length, $width) {
    echo "المساحة: " . ($length * $width) . "<br>";
}

area(8, 3); // المساحة: 24

✅ المثال 4: دالة لحساب النسبة المئوية

function percentage($total, $value) {
    $percent = ($value / $total) * 100;
    echo "النسبة: $percent%<br>";
}

percentage(200, 50); // النسبة: 25%

Parameters And Arguments

🧠 الفكرة:

يمكنك تمرير معلومات إلى الدالة لتتعامل معها بشكل ديناميكي.

🧱 الصيغة:

function sayHello($name) {
    echo "أهلاً $name <br>";
}

🧪 مثال:

sayHello("Yasin");
sayHello("Ali");

📌 النتيجة:

أهلاً Yasin  
أهلاً Ali

Function Return And Echo

✅ أولًا: الفرق الأساسي بين return و echo

✅ مثال 1: استخدام echo فقط داخل الدالة

function sayHello($name) {
    echo "Hello $name<br>";
}

sayHello("Yasin"); // Hello Yasin
sayHello("Ali");   // Hello Ali

📌 الشرح:

• الدالة تقوم بطباعة الترحيب مباشرة على الشاشة.
• لا يمكن استخدام الناتج في عملية أخرى لأنه مجرد طباعة.

✅ مثال 2: استخدام return فقط داخل الدالة

function getHello($name) {
    return "Hello $name";
}

$message = getHello("Yasin");
echo $message; // Hello Yasin

📌 الشرح:

• return أرجعت النص من الدالة.
• استخدمنا القيمة لاحقًا بطباعتها أو حتى استخدامها في منطق آخر.

✅ مثال 3: الفرق في العمليات الحسابية

function addWithEcho($a, $b) {
    echo $a + $b;
}

function addWithReturn($a, $b) {
    return $a + $b;
}

addWithEcho(5, 3);       // تطبع 8 مباشرة
echo "<br>";
$result = addWithReturn(5, 3);
echo $result * 2;        // تطبع 16 (8 × 2)

📌 الشرح:

• addWithEcho تطبع النتيجة ولا يمكننا استخدامها مرة أخرى.
• addWithReturn ترجع القيمة، لذلك يمكننا استخدامها في حساب آخر.

✅ مثال 4: استخدام return داخل شرط

function isEven($num) {
    if ($num % 2 == 0) {
        return true;
    }
    return false;
}

if (isEven(10)) {
    echo "العدد زوجي";
} else {
    echo "العدد فردي";
}

📌 الشرح:

• الدالة تعيد true أو false باستخدام return.
• استخدمنا النتيجة في شرط خارجي.
• لا يمكن فعل ذلك باستخدام echo فقط.

✅ نصائح للمبتدئين:

🔹 استخدم echo فقط للطباعة البسيطة.
🔹 استخدم return عندما تريد إعادة قيمة لاستخدامها لاحقًا في عمليات أو منطق.

🧠 الفرق:

• echo: تطبع النتيجة مباشرة.
• return: ترجع القيمة بدون طباعة، لتستخدم لاحقًا.

🧪 مثال:

function sum($a, $b) {
    return $a + $b;
}

$result = sum(5, 3);
echo "النتيجة: $result";

Function Default Parameter Value

✅ ما هو Default Parameter Value في PHP؟

هو قيمة افتراضية يتم إعطاؤها للـ parameter داخل تعريف الدالة، بحيث لو تم استدعاء الدالة بدون تمرير قيمة لذلك الوسيط، تُستخدم القيمة الافتراضية تلقائيًا.

🎯 الفائدة:

• ✅ تجعل الدوال أكثر مرونة.
• ✅ تقلل عدد الأخطاء الناتجة عن نسيان تمرير قيمة.
• ✅ تساعد في إعادة استخدام الدالة بسهولة أكثر من سيناريو.

⚠️ محاذير مهمة:

1. إذا وضعت قيمة افتراضية لوسيط، يجب أن تأتي بعد الوسائط العادية. ❌ خطأ: phpCopyEditfunction greet($name = "Yasin", $age) { } // ❌ ✅ صح: phpCopyEditfunction greet($name, $age = 18) { } // ✅
2. لا يمكن استخدام متغير غير معرف كقيمة افتراضية (يجب أن تكون قيمة ثابتة أو معرفة سابقًا).

✨ نصائح للمبتدئين:

• استخدم القيمة الافتراضية لتقليل تكرار الدوال.
• لا تفرط باستخدام القيم الافتراضية إذا كان الوسيط مهم وأساسي.
• اجعل القيم الافتراضية منطقية (مثلاً: العمر = 18، اللغة = “ar”).

✅ 4 أمثلة على Default Parameters

✅ مثال 1: ترحيب افتراضي

function sayHello($name = "زائر") {
    echo "أهلاً وسهلاً $name<br>";
}

sayHello("ياسين"); // أهلاً وسهلاً ياسين
sayHello();         // أهلاً وسهلاً زائر

✅ مثال 2: حساب الضريبة

function calculateTax($amount, $tax = 0.15) {
    return $amount * $tax;
}

echo calculateTax(100);      // 15
echo calculateTax(100, 0.2); // 20

✅ مثال 3: عرض معلومات المستخدم

function userInfo($name, $city = "غير معروف") {
    echo "$name من مدينة $city<br>";
}

userInfo("علي", "دمشق");
userInfo("فاطمة");

✅ مثال 4: تحديد اللغة الافتراضية

function greet($name, $lang = "ar") {
    if ($lang == "en") {
        echo "Hello $name<br>";
    } else {
        echo "مرحبا $name<br>";
    }
}

greet("Yasin", "en"); // Hello Yasin
greet("Yasin");       // مرحبا Yasin

🧠 المعنى:

تستطيع إعطاء قيمة افتراضية للباراميتر إذا لم يُمرر.

🧪 مثال:

function greet($name = "زائر") {
    echo "مرحبًا $name <br>";
}

greet("Yasin");
greet(); // تستخدم القيمة الافتراضية

📌 النتيجة:

مرحبًا Yasin  
مرحبًا زائر

✅ ما هو Function Variable Arguments List؟

هو إمكانية تمرير عدد غير محدود من القيم (arguments) إلى دالة واحدة، باستخدام ثلاث نقاط ... قبل اسم المتغير.

هذه الميزة تُسمى أيضًا variadic functions.

✳️ الصيغة:

function functionName(...$args) {
    // $args يكون عبارة عن مصفوفة (Array) من القيم المرسلة
}

🎯 الفوائد:

• ✅ تُمكنك من إنشاء دوال مرنة تستقبل عددًا غير محدد من القيم.
• ✅ تقلل الحاجة إلى إنشاء أكثر من نسخة من الدالة لعدد مختلف من المعطيات.
• ✅ تسهل العمليات على مجموعة من البيانات مثل الجمع، الضرب، الطباعة، إلخ.

⚠️ محاذير ونصائح:

• يمكنك تمرير وسيط ثابت قبل ...$args، لكن ... يجب أن يكون في النهاية فقط.
• المتغير بعد ... سيكون دائمًا مصفوفة تحتوي على جميع القيم المرسلة.
• لا يمكن استخدام أكثر من ... مرة واحدة في نفس الدالة.

✅ مثال 1: دالة تجمع كل الأرقام الممررة

function sumAll(...$numbers) {
    $sum = 0;
    foreach ($numbers as $num) {
        $sum += $num;
    }
    echo "المجموع: $sum<br>";
}

sumAll(1, 2, 3);          // المجموع: 6
sumAll(10, 20, 30, 40);   // المجموع: 100

✅ مثال 2: طباعة كل الأسماء المرسلة

function printNames(...$names) {
    foreach ($names as $name) {
        echo "مرحبًا $name<br>";
    }
}

printNames("ياسين", "علي", "نور");

✅ مثال 3: تحديد خصم على مجموعة أسعار

function applyDiscount($discount, ...$prices) {
    foreach ($prices as $price) {
        $newPrice = $price - ($price * $discount);
        echo "السعر بعد الخصم: $newPrice<br>";
    }
}

applyDiscount(0.1, 100, 200, 300); // خصم 10%

✅ مثال 4: إيجاد أكبر رقم من قائمة أرقام

function getMax(...$numbers) {
    $max = max($numbers); // دالة PHP جاهزة
    echo "أكبر رقم: $max<br>";
}

getMax(5, 99, 32, 45); // أكبر رقم: 99

✅ خلاصة للمبتدئ:

• ...$args = اجمع كل ما يُرسل للدالة كمصفوفة.
• استخدمها عندما لا تعرف مسبقًا كم عدد القيم.
• مفيدة جدًا في العمليات المتكررة أو الجماعية.

🧠 لما لا تعرف عدد البراميترز مسبقًا:

استخدم ...$args

🧪 مثال:

function printNumbers(...$nums) {
    foreach ($nums as $num) {
        echo "$num<br>";
    }
}

printNumbers(1, 2, 3, 4, 5);

✅ Function Training And Unpacking Arguments

🧠 تمرين على استخدام القوائم وتفريغها داخل الدالة.

🧪 مثال:

function calculate($a, $b, $c) {
    return $a + $b + $c;
}

$data = [10, 20, 30];
echo calculate(...$data);

✅ Function Variable And Function Exists

✳️ أولًا: ما هو function_exists()؟

هي دالة في PHP تستخدم للتأكد مما إذا كانت دالة معينة موجودة ومعرّفة قبل محاولة استخدامها.

✅ الصيغة:

function_exists("functionName");

🔹 تُعيد:

• true إذا كانت الدالة موجودة
• false إذا لم تكن موجودة

✳️ ثانيًا: ما هي Variable Functions؟

هي طريقة لاستدعاء دالة باستخدام اسمها من داخل متغير.

✅ الصيغة:

$func = "sayHello";
$func(); // هذا ينفذ الدالة sayHello()

🔹 بشرط أن تكون الدالة موجودة أصلًا.

🎯 الفوائد:

⚠️ المحاذير:

• لا تستخدم variable functions بدون التأكد أن الدالة موجودة.
• تأكد من كتابة اسم الدالة الصحيح داخل المتغير.
• إذا كانت الدالة غير معرفة واستُدعيت، ستحدث Fatal Error.

✅ الأمثلة:

📘 مثال 1: التحقق من وجود دالة قبل استدعائها

function greet() {
    echo "مرحبًا بك<br>";
}

if (function_exists("greet")) {
    greet(); // سيتم التنفيذ
} else {
    echo "الدالة غير موجودة<br>";
}

📘 مثال 2: استدعاء دالة بناءً على اسم في متغير

function sayHi() {
    echo "Hi there!<br>";
}

$call = "sayHi";
$call(); // تنفذ sayHi

📘 مثال 3: تنفيذ دوال مختلفة حسب إدخال المستخدم

function add() {
    echo "عملية جمع<br>";
}

function subtract() {
    echo "عملية طرح<br>";
}

$operation = "add";
if (function_exists($operation)) {
    $operation(); // تنفذ الدالة add
}

📘 مثال 4: دالة غير معرفة مع الحماية

$unknown = "doSomething";

if (function_exists($unknown)) {
    $unknown(); // لن تُنفذ لأنها غير موجودة
} else {
    echo "⚠️ الدالة '$unknown' غير معرفة<br>";
}

✅ خلاصة مبسطة للمبتدئين:

• استخدم function_exists() للتأكد قبل التنفيذ.
• يمكن تخزين اسم الدالة في متغير وتنفيذه باستخدام ().
• هذا يفيدك في بناء أنظمة مرنة ومتغيرة مثل لوحة تحكم أو مدير أوامر.

📌 function_exists("اسم"): تفيدنا لمعرفة إذا كانت الدالة معرفة مسبقًا.

🧪 مثال:

if (!function_exists("sayHi")) {
    function sayHi() {
        echo "Hi from sayHi!";
    }
}
sayHi();

🟢 أولًا: Passing Arguments By Reference (التمرير بالإشارة)

✅ ما هو؟

في PHP، القيم تُمرر افتراضيًا بالنسخ (By Value)، أي يتم إنشاء نسخة من المتغير داخل الدالة.

لكن عند التمرير بالإشارة (By Reference)، فإن أي تعديل على المتغير داخل الدالة يُؤثر على القيمة الأصلية خارجها.

✅ الصيغة:

function changeValue(&$var) {
    $var = "تم التعديل";
}

لاحظ علامة & قبل اسم الوسيط — هذه تعني “مرر بالإشارة”.

🎯 الفوائد:

⚠️ محاذير:

• لا تمرر بالإشارة إلا إذا كنت بحاجة حقيقية لتغيير القيمة الأصلية.
• قد يؤدي إلى نتائج غير متوقعة إن لم تكن حذرًا.

📘 مثال 1: تمرير بدون إشارة (By Value)

function setName($name) {
    $name = "علي";
}

$person = "ياسين";
setName($person);
echo $person; // يطبع "ياسين"

📌 المتغير لم يتغير لأن النسخة تم تعديلها، وليس الأصل.

📘 مثال 2: تمرير بالإشارة (By Reference)

function setName(&$name) {
    $name = "علي";
}

$person = "ياسين";
setName($person);
echo $person; // يطبع "علي"

📌 القيمة الأصلية تغيرت لأننا استخدمنا &.

📘 مثال 3: زيادة قيمة رقم

function increment(&$number) {
    $number++;
}

$num = 5;
increment($num);
echo $num; // 6

📘 مثال 4: تعديل عناصر مصفوفة

function makeUppercase(&$value) {
    $value = strtoupper($value);
}

$names = ["yasin", "ali", "nour"];
foreach ($names as &$n) {
    makeUppercase($n);
}

print_r($names);
// ["YASIN", "ALI", "NOUR"]

🟢 ثانيًا: Return Type Declaration (تحديد نوع القيمة الراجعة)

✅ ما هو؟

يسمح لك PHP بتحديد نوع القيمة التي تُعيدها الدالة باستخدام : بعد الأقواس، وذلك لضمان دقة نوع البيانات المرجعة.

✅ الصيغة:

function sum(int $a, int $b): int {
    return $a + $b;
}

🔸 هنا نطلب أن تُرجع الدالة عددًا صحيحًا int.

✅ الأنواع الشائعة:

• int
• float
• string
• bool
• array
• object
• mixed (من PHP 8+)
• void (لا تُرجع شيء)

🎯 الفوائد:

⚠️ محاذير:

• يجب أن تُرجع الدالة فعلًا القيمة من النوع المحدد وإلا ستظهر Fatal Error.
• لا تستخدمه إذا كانت الدالة تحتوي على عدة return بأنواع مختلفة بدون mixed.

📘 مثال 1: دالة تُرجع عددًا صحيحًا

function multiply(int $a, int $b): int {
    return $a * $b;
}

echo multiply(3, 4); // 12

📘 مثال 2: دالة تُرجع نصًا

function greet(string $name): string {
    return "Hello, $name";
}

echo greet("Yasin");

📘 مثال 3: دالة بدون قيمة (void)

function showMessage(): void {
    echo "تم تنفيذ العملية<br>";
}

showMessage();

📘 مثال 4: دالة تُرجع true أو false

function isEven(int $n): bool {
    return $n % 2 === 0;
}

var_dump(isEven(4)); // true
var_dump(isEven(7)); // false

✅ خلاصة:

🔹 ما هي الدوال المجهولة (Anonymous Functions)؟

هي دوال ليس لها اسم، وتُخزن عادةً في متغير لاستخدامها لاحقًا.
تُعرف أحيانًا أيضًا باسم Closure في PHP، وتُستخدم لتنفيذ منطق معيّن بدون الحاجة لتعريف دالة باسم دائم.

✅ الصيغة العامة:

$var = function($params) {
    // كود الدالة
};

يمكن استدعاؤها لاحقًا باستخدام: $var();

✅ الفوائد:

⚠️ المحاذير:

• يصعب تتبعها إذا زاد استخدامها بشكل عشوائي.
• لا يمكن استدعاؤها قبل تعريفها (Unlike normal functions).
• قد تكون مربكة للمبتدئين إذا أسيء استخدامها.

🎯 استخداماتها الشائعة:

• في الفلاتر (مثل array_filter, array_map)
• تمريرها كوسيط لدالة أخرى (Callback)
• اختصارات داخل عمليات التكرار
• التعامل مع البيانات المؤقتة

📘 المثال 1: إنشاء دالة مجهولة لطباعة رسالة

$greet = function($name) {
    echo "مرحبًا يا $name<br>";
};

$greet("ياسين"); // مرحبًا يا ياسين
$greet("نور");   // مرحبًا يا نور

📘 المثال 2: استخدام دالة مجهولة مع array_map

$nums = [1, 2, 3, 4];

$squared = array_map(function($n) {
    return $n * $n;
}, $nums);

print_r($squared);
// [1, 4, 9, 16]

📘 المثال 3: استخدام use لإدخال متغير خارجي

$prefix = "أهلاً ";

$say = function($name) use ($prefix) {
    echo $prefix . $name . "<br>";
};

$say("ياسين"); // أهلاً ياسين

🔎 use تسمح لك بإدخال متغير خارجي داخل الدالة.

📘 المثال 4: استخدام دالة مجهولة داخل دالة أخرى

function processName($name, $callback) {
    echo "الاسم بعد المعالجة: ";
    $callback($name);
}

processName("ياسين", function($n) {
    echo strtoupper($n) . "<br>";
});
// الاسم بعد المعالجة: YASIn

✅ خلاصة للمبتدئين:

🔹 ما هي الـ Arrow Function؟

هي نوع مختصر من الدوال المجهولة Anonymous Function، تم تقديمها في PHP 7.4، وتُستخدم في السطر الواحد فقط.

✳️ تُشبه دوال JavaScript في الصيغة، لكنها أخف وأبسط من الـ Closure العادية.

✅ الصيغة:

$function = fn($parameter) => التعبير;

🔹 fn تعني “function”
🔹 لا تحتاج إلى return — القيمة تُعاد تلقائيًا
🔹 تستخدم السهم => بدلاً من الأقواس والـ return

✅ الفوائد:

⚠️ المحاذير:

✅ الفرق بينها وبين Anonymous Function العادية:

📘 مثال 1: جمع رقمين باستخدام Arrow Function

$sum = fn($a, $b) => $a + $b;

echo $sum(3, 5); // 8

📘 مثال 2: استخدام Arrow Function داخل array_map

$nums = [1, 2, 3, 4];

$squared = array_map(fn($n) => $n * $n, $nums);

print_r($squared);
// [1, 4, 9, 16]

📘 مثال 3: استخدام متغير خارجي بدون use

$tax = 0.05;

$addTax = fn($price) => $price + ($price * $tax);

echo $addTax(100); // 105

🔎 المتغير $tax مستخدم بدون use لأن الـ Arrow Functions تلتقط المتغيرات تلقائيًا.

📘 مثال 4: دالة تحقق إذا كان الرقم زوجي

$isEven = fn($n) => $n % 2 === 0;

var_dump($isEven(6)); // true
var_dump($isEven(7)); // false

✅ استخداماتها الشائعة:

• array_map / array_filter / array_reduce
• دوال مؤقتة بسيطة داخل التكرار
• اختصارات للكود البسيط في سطر واحد
• منطق رياضي/شرطي بسيط

✅ نصائح للمبتدئين:

• استخدمها عندما تحتاج فقط تعبير واحد بسيط.
• تجنب استخدامها في منطق معقد أو يحتوي على أكثر من سطر.
• لا تحتاج إلى return — القيمة تُعاد تلقائيًا.
• لا تستخدم معها {} أو ; داخل التعبير.