توابع کمکی و سراسری

۲۷ تابع کمکی در فضای‌نام، روش وارد کردن آن‌ها و Globals::register() اختیاری که نام‌های کوتاه سراسری را بدون عوض کردن تابع‌های شما اضافه می‌کند.

برنامه RTLY-Kit 0.2.0آخرین بررسی 9 اکتبر 2026زمان خواندن 7 دقیقه

چرا توابع کمکی در فضای‌نام هستند

نام‌هایی مثل is_mobile()، ordinal() یا to_english() کوتاه و رایج‌اند. در PHP نمی‌شود تابع سراسری را دوباره تعریف کرد. اگر دو بسته (یا برنامهٔ شما و یک بسته) یک نام سراسری را تعریف کنند، تعریف دوم خطای مرگبار می‌دهد. کتابخانه‌ای که بی‌قید تابع سراسری تعریف کند، می‌تواند برنامه‌ای را که تا قبل از نصب سالم بود از کار بیندازد.

RTLY-Kit این مشکل را از اول حل کرده:

هر ۲۷ تابع کمکی در فضای‌نام RtlyKit هستند. Composer خودکار بارگذاری‌شان می‌کند و با هیچ چیز تداخل ندارند.
نام‌های کوتاه سراسری اختیاری هستند. با \RtlyKit\Globals::register() روشن می‌شوند و فقط نام‌های آزاد را تعریف می‌کنند.
service provider در Laravel هم تابع سراسری ثبت نمی‌کند. راه‌اندازی Laravel را ببینید.

استفاده

هر چه لازم دارید با use function وارد کنید و با نام کوتاه صدا بزنید. یا با نام کامل صدا بزنید:

PHP

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);            // ۱۴۰۴

// چند تابع با هم (group use):
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 نامعتبر می‌دهد.

تقویم‌ها

تابع	امضا	صدا می‌زند
`jdate`	`jdate(DateTimeInterface\|string\|int\|null $time = null, ?DateTimeZone $timezone = null): Jalali`	`Jalali::make()`، جلالی
`hdate`	`hdate(DateTimeInterface\|string\|int\|null $time = null, ?DateTimeZone $timezone = null): Hijri`	`Hijri::make()`، هجری
`hebrew_date`	`hebrew_date(DateTimeInterface\|string\|int\|null $time = null, ?DateTimeZone $timezone = null): Hebrew`	`Hebrew::make()`، عبری

رقم‌ها و عددها

تابع	امضا	نمونه
`to_persian_digits`	`(string\|int\|float $value): string`	`to_persian_digits(1404)` می‌دهد `۱۴۰۴`
`to_english_digits`	`(string $value): string`	`to_english_digits('۱۴۰۴')` می‌دهد `1404`
`to_persian`	`(string\|int\|float $value): string`	نام کوتاه `to_persian_digits`. `to_persian('12.5')` می‌دهد `۱۲.۵`
`to_english`	`(string $value): string`	نام کوتاه `to_english_digits`. `to_english('٣٤')` می‌دهد `34`
`number_to_words`	`(int\|float\|string $number, string $locale = 'fa'): string`	`number_to_words(25, 'ar')` می‌دهد `خمسة وعشرون`. گزینه‌های عربی را با `NumberToWords::convert()` بدهید
`format_number`	`(int\|float\|string $number): string`	`format_number(1234567)` می‌دهد `۱٬۲۳۴٬۵۶۷`
`ordinal`	`(int\|float $number): string`	`ordinal(3)` می‌دهد `سوم`

رقم‌ها و قالب‌بندی عدد، عدد به حروف و عدد به حروف عربی را ببینید.

متن

تابع	امضا	نمونه
`normalize_text`	`(string $text): string`	`normalize_text('كتاب ي')` می‌دهد `کتاب ی` (کاف و یای عربی فارسی می‌شوند)
`contains_rtl`	`(string $text): bool`	`contains_rtl('abc سلام')` می‌دهد `true`
`text_direction`	`(string $text): string`	`text_direction('سلام')` می‌دهد `rtl` و `text_direction('hello')` می‌دهد `ltr`

ابزارهای متن را ببینید.

اعتبارسنجی: بله یا خیر

هر کدام bool می‌دهند و mixed می‌گیرند.

تابع	امضا	نمونه
`is_national_code`	`(mixed $value): bool`	`is_national_code('0013542419')` می‌دهد `true`
`is_sheba`	`(mixed $value): bool`	`is_sheba('IR062960000000100324200001')` می‌دهد `true`
`is_bank_card`	`(mixed $value): bool`	`is_bank_card('6037997535328737')` می‌دهد `true`
`is_mobile`	`(mixed $value): bool`	`is_mobile('09123456789')` می‌دهد `true`
`is_postal_code`	`(mixed $value): bool`	`is_postal_code('1676543210')` می‌دهد `true`
`is_vehicle_plate`	`(mixed $value): bool`	`is_vehicle_plate('12ب345-67')` می‌دهد `true`

اعتبارسنجی: نتیجهٔ کامل

هر کدام یک RtlyKit\Validation\Result می‌دهند که متدهای valid()، invalid()، isValid()، errors() و details() دارد. مرور اعتبارسنج‌ها را ببینید.

تابع	امضا
`validate_national_code`	`(mixed $value): Result`
`validate_sheba`	`(mixed $value): Result`
`validate_bank_card`	`(mixed $value): Result`
`validate_mobile`	`(mixed $value): Result`
`validate_postal_code`	`(mixed $value): Result`
`validate_vehicle_plate`	`(mixed $value): Result`

PHP

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

تعطیلات و اوقات شرعی

تابع	امضا	توضیح
`is_iran_holiday`	`(Jalali\|int $year, ?int $month = null, ?int $day = null): bool`	همان `IranHolidays::isHoliday()` است و تقویم پیش‌فرض را می‌خواند. `is_iran_holiday(1404, 11, 22)` می‌دهد `true`. تعطیلات و تقویم تعطیلات را ببینید.
`prayer_times`	`(string $city = 'tehran', string $method = 'Tehran'): array`	وقت‌های امروز به منطقهٔ زمانی شهر، به شکل `{"fajr", "sunrise", "dhuhr", "asr", "maghrib", "isha"}`. شهر یا روش ناشناخته `InvalidPrayerConfigException` می‌دهد. اوقات شرعی را ببینید.

جمعاً ۳ + ۷ + ۳ + ۶ + ۶ + ۲ = ۲۷ تابع، همان فهرستی که Globals::NAMES دارد.

نام‌های سراسری اختیاری: Globals::register()

اگر نام‌های کوتاه سراسری را ترجیح می‌دهید (مثلاً در کد قدیمی، موتور قالب یا اسکریپت)، یک بار در بوت‌استرپ این را صدا بزنید:

PHP

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

تضمین‌ها:

فقط نام‌های آزاد تعریف می‌شوند. اگر تابعی با آن نام باشد، دست نمی‌خورد.
نام‌های ردشده را می‌گوید. خروجی یک list<string> از نام‌هایی است که چون تابع دیگری داشتند تعریف نشدند . فهرست خالی یعنی همه ثبت شدند.
خطا پرتاب نمی‌کند و خطای تعریف دوباره هم نمی‌دهد.
چند بار صدا زدنش مشکلی ندارد. نامی که تعریفش از خود RTLY-Kit باشد ردشده حساب نمی‌شود. پس بار دوم همان فهرست بار اول را می‌گیرید.
توابع فضای‌نام‌دار همیشه کار می‌کنند ، چه نام سراسری ردشده باشد چه نه.
ثابت \RtlyKit\Globals::NAMES هر ۲۷ نام را دارد.

نمونهٔ تداخل نام

برنامه از قبل is_mobile() خودش را دارد (برای user-agent). بسته آن را خراب یا عوض نمی‌کند و به شما خبر می‌دهد:

PHP

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" }

روش معقول این است که فهرست را لاگ کنید و ادامه بدهید:

PHP

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

نکته. تابع‌هایی که در سطح بالای یک فایل PHP تعریف شده‌اند از قبل ثبت می‌شوند (hoist). پس تابع سراسری‌ای که پایین‌تر در همان فایل تعریف شده هم «از قبل تعریف‌شده» حساب می‌شود. اگر روی نامی حساس هستید، آن را قبل از register() تعریف کنید، یا فقط به تابع فضای‌نام‌دار تکیه کنید.

کدام سبک را انتخاب کنم؟

کتابخانه و برنامهٔ جدید: importهای فضای‌نام‌دار ( use function RtlyKit\jdate; ). روشن است، جست‌وجوپذیر است و تداخل ندارد.
کد قدیمی، اسکریپت و قالب: یک بار Globals::register() را صدا بزنید و سبک کوتاه قبلی را نگه دارید.
Laravel: هر دو ممکن است. provider تابع سراسری اضافه نمی‌کند. اگر خواستید، Globals::register() را در AppServiceProvider::register() صدا بزنید، یا در Blade و کلاس‌ها تابع‌های فضای‌نام‌دار را import کنید.