الدوال المساعدة والدوال العامة

لماذا توجد الدوال المساعدة داخل فضاء أسماء#

أسماء مثل is_mobile() أو ordinal() أو to_english() قصيرة وعامة. ولا توجد في PHP طريقة «لاستبدال» دالة عامة: إذا أعلنت حزمتان (أو تطبيقك وإحدى الحزم) عن الاسم العام نفسه، فإن الإعلان الثاني خطأ فادح. لذلك قد تعطّل المكتبة التي تعرّف دوالَّ عامة دون شرط تطبيقًا كان يعمل قبل تثبيتها.

يتجنب RTLY-Kit هذه المشكلة بحكم التصميم:

• الدوال المساعدة السبع والعشرون كلها معرّفة في فضاء الأسماء RtlyKit. يحمّلها Composer تلقائياً، ولا يمكن أن تتعارض مع أي شيء.
• الأسماء العامة القصيرة اختيارية عبر \RtlyKit\Globals::register()، التي لا تعرّف إلا الأسماء التي ما زالت حرة.
• مزوّد الخدمة في Laravel لا يسجّل دوالَّ عامة هو الآخر. راجع إعداد Laravel.

استخدام الدوال المساعدة#

استورد ما تحتاجه بـ use function ثم استدعِه باسمه القصير. أو استدعِه بالاسم الكامل:

use function RtlyKit\jdate;
use function RtlyKit\is_national_code;

echo jdate('2025-03-21')->format('Y/m/d');       // 1404/01/01
var_dump(is_national_code('0013542419'));         // bool(true)
echo \RtlyKit\to_persian_digits(1404);            // ۱۴۰۴

// عدة دوال دفعة واحدة (use المجمّع في PHP):
use function RtlyKit\{hdate, hebrew_date, number_to_words};
echo hdate('2025-03-21')->format('Y/m/d');       // 1446/09/21
echo hebrew_date('2025-03-21')->format('Y/m/d'); // 5785/06/21
echo number_to_words(1404);                       // یک هزار و چهارصد و چهار

الدوال المساعدة أغلفة رقيقة: كل منها يستدعي الصنف المقابل، فيمكنك دائمًا استخدام الصنف مباشرة عندما تحتاج إلى تحكم أكبر (مثل Jalali::create() مع منطقة زمنية).

جميع الدوال المساعدة#

أنواع المعاملات وأنواع الإرجاع هي نفسها الموجودة في الشيفرة المصدرية تمامًا. المدخلات من النوع mixed لا ترمي استثناءً أبدًا: المدخل غير الصالح يعطي ببساطة false أو Result غير صالح.

التقاويم#

الأرقام والأعداد#

انظر الأرقام والتنسيق والأعداد بالكلمات والأعداد بالحروف العربية. الدالة number_to_words() لا تأخذ خيارات؛ وللجنس والحالة الإعرابية والحركات استدعِ NumberToWords::convert() مع ArabicOptions.

النصوص#

راجع أدوات النصوص.

التحقق من الصحة: نعم/لا#

كل منها يُرجع bool ويقبل mixed.

التحقق من الصحة: نتيجة منظَّمة#

كل منها يُرجع RtlyKit\Validation\Result بالدوال valid() وinvalid() وisValid() وerrors() وdetails(). راجع نظرة عامة على أدوات التحقق.

$r = \RtlyKit\validate_national_code('1234567890');
var_dump($r->isValid());   // bool(false)

العطل وأوقات الصلاة#

المجموع إذن 3 + 7 + 3 + 6 + 6 + 2 = 27 دالة مساعدة، وهي القائمة نفسها التي تحملها Globals::NAMES.

الأسماء العامة الاختيارية: Globals::register()#

إذا كنت تفضّل الأسماء العامة القصيرة (مثلًا في قاعدة شيفرة قديمة أو محرك قوالب أو سكربت)، فاستدعِ هذا مرة واحدة أثناء الإقلاع:

$skipped = \RtlyKit\Globals::register();

الضمانات التي تقدمها:

• لا تُعرَّف إلا الأسماء الحرة. لا يُعرَّف الاسم إلا إذا لم توجد دالة بهذا الاسم. ولا تُستبدل دالة موجودة أبدًا.
• تُبلغ عمّا تخطّته. القيمة المرجعة list<string> بالأسماء التي لم تُعرَّف لأن دالة أخرى تستخدمها. القائمة الفارغة تعني أن كل شيء سُجّل.
• لا ترمي استثناءً أبدًا ولا تسبب خطأ إعادة إعلان، مهما كان الوضع.
• إعادة الاستدعاء آمنة (idempotent). استدعِها كما تشاء. الاسم الذي هو تعريف RTLY-Kit السابق نفسه لا يُعدّ متخطًّى، فيعطي الاستدعاء الثاني القائمة نفسها التي أعطاها الأول.
• الدوال ضمن فضاء الأسماء تعمل دائمًا، سواء تُخطّي اسم عام أم لا.
• \RtlyKit\Globals::NAMES ثابت يسرد الأسماء السبعة والعشرين كلها.

مثال على التعارض#

لدى التطبيق دالته الخاصة is_mobile() (فحص user-agent). الحزمة لا تعطّلها ولا تستبدلها، وتخبرك بذلك:

require 'vendor/autoload.php';

// التطبيق يملك أصلاً دالة عامة بالاسم نفسه.
function is_mobile(string $ua): bool { return str_contains($ua, 'Mobi'); }

$skipped = \RtlyKit\Globals::register();
var_dump($skipped);
// array(1) { [0]=> string(9) "is_mobile" }

var_dump(is_mobile('Mozilla/5.0 (iPhone) Mobile'));   // bool(true)   دالة التطبيق نفسه
var_dump(\RtlyKit\is_mobile('09123456789'));           // bool(true)   فحص رقم الجوال الإيراني، متاح دائماً
echo jdate('2025-03-21')->format('Y/m/d'), "\n";       // 1404/01/01   اسم حر: سُجّل كدالة عامة
var_dump(\RtlyKit\Globals::register());                // آمنة عند التكرار: القائمة نفسها، array(1) { [0]=> string(9) "is_mobile" }

السياسة المعقولة هي تسجيل القائمة في السجل ثم المتابعة:

$skipped = \RtlyKit\Globals::register();
if ($skipped !== []) {
    error_log('RTLY-Kit globals skipped: ' . implode(', ', $skipped));
}

أي أسلوب أختار؟#

• المكتبات والتطبيقات الجديدة: الاستيراد من فضاء الأسماء (use function RtlyKit\jdate;). فهو صريح وسهل البحث ولا يسبب تعارضًا.
• الشيفرة القديمة والسكربتات والقوالب: استدعِ Globals::register() مرة واحدة وأبقِ على الأسلوب القصير القديم.
• Laravel: كلاهما مناسب؛ فمزوّد الخدمة لا يضيف دوالَّ عامة، فاستدعِ Globals::register() في AppServiceProvider::register() إن أردتها، أو استورد الدوال ضمن فضاء الأسماء في Blade وفي الأصناف.