Datex API: کتابخانه کار با تاریخ های شمسی و جلالی در PHP

کتابخانه های زیادی برای تبدیل تاریخ جلالی به میلادی و برعکس برای php نوشته شده. من چند تا از اونها رو دیدم. اینجا و اینجا و اینجا. گرچه کدهایی که تمام دوستان نوشته اند به خوبی کار میکند اما ما امروز کتابخانه Datex را به شما معرفی میکنم. به مرور زمان پی بردم علاوه بر متدی منعطف‌تر برای پیاده‌سازی تبدیل تاریخ جلالی و میلادی به یک دیگر، نیاز به یک کتابخانه یا یک API جامع برای کار با تاریخ‌های جلالی وجود دارد. ادامه مطلب را برای مشاهده مزیت های این کتابخانه بخوانید.

شیئی که از کلاس DatexObject ساخته می‌شود تاریخ را در شیئی از کلاس DateTime به صورت داخلی ذخیره می‌کند. به این ترتیب شما با تمامی توابع ارائه شده توسط php هم می‌تونید کار کنید. البته به دلایلی از وراثت استفاده نشده بلکه یک شئ داخلی تاریخ میلادی رو ذخیره می‌کنه (استفاده از رابطه DatexObject is a DateTime درست به نظر نمیاد). سعی کردم توابع مهمی رو که DateTime پیاده‌سازی کرده برای دیتکس هم پیاده‌سازی کنم، توابعی هم که پیاده‌سازی نشدن در آینده به این کتابخانه اضافه می‌شه. تمامی توابع این کتابخانه دارای Documentation در فرمت Doxygen هستن با خواندن کامنت‌های موجود در بالای هر تابع به کاری که اتجام می‌ده نحوه‌ی انجامش پی می‌برید.

فعلا این کتابخانه تحت مجور GPL2 منتشر شده.

مزیت ها:

1.  ذخیره تاریخ به صورت میلادی در یک شئ داخلی
2.  پشتیبانی از کتابخانه php-intl
3.  دارای Fallback در صورت نبودن php-intl
4.  توابع کاربردی مختلف
5.  رعایت استایل کدنویسی خوانا و استفاده از سیستم مستندسازی Doxygen
6.  وجود DateTime داخلی
7.  برای محاسبه سال کبیسه از ثابت خیامی استفاده شده که دقت فوق العاده بالایی داره و برخلاف خیلی از الگوریتم‌های دیگه در تشخیص سال های کبیسه به مشکل برنمی خورد. ایده این الگوریتم رو از کد آقای امین گرفتم.
8.  آسانی کار در استفاده از کلاس سازنده به طوری که می‌تونید برای ساخت یک شي از این کلاس، تاریخ مورد نظر رو از طریق یک شیی DateTime، شیي DatexObject، عدد صحیح به عنوان TimeStamp، آرایه یا رشته ارسال کنید که به صورت خودکار اون رو تشخیص می‌ده.

مکانیزم داخلی DatexObject:
DatexObject برای ذخیره سازی تاریخ از یک شیي DateTime که کلاس داخلی PHP است استفاده میکند. با تابع getDateobjClone میتوان به این شی داخلی دسترسی پیدا کرد. بنابراین برای کار با توابعی که برای تاریخ میلادی استفاده شده اند یا درایورهای پایگاه داده که تاریخ جلالی را پشتیبانی نمیکنند نیازی به تبدیل دوباره تاریخ نیست بلکه میتوان مستقیما از این شیئ استفاده کرد. هم چنین برای استفاده از قابلیت ها (Functionality) که بین تاریخ میلادی و جلالی مشترک هستند از کدهای داخلی PHP میتوان استفاده کرد. بدین ترتیب سرعت و پایداری محصول نهایی بالاتر میرود.

نحوه‌ی استفاده:

برای دسترسی به توابعی که با تاریخ کار می‌کنند، از کلاس DatexFormatter استفاده کنید. همه‌ی متدهای این کلاس به صورت استاتیک تعریف شده‌اند. برای ساخت یک شیئ جلالی هم از DatexObject استفاده کنید.
برای دسترسی به توابعی که بین تاریخ جلالی و میلادی مشترک نیستند (getTimeStamp نتیجه مشابهی برای جلالی و میلادی دارد اما setDate برای جلالی و میلادی فرق دارد)، یه ابتدای نام تابع حرف x اضافه کنید. مثلا xformat() به جای format()

//____________________________BUILDING DATE FROM GREGORIAN DATE
//using curent time
$x= new DatexObject();

//Instancing DatexObject according to time stored in a DateTime object
$y = new DateTime('now');
$x= new DateObject($y);
$z= new DateObject($x);

//using timestamp
$x = new DatexObject(434312);

//using array
$x=new DatexObject( array(
'year' => 2012,
'second' => 45,));

//__________________________BUILDING DATE FROM JALALI DATE

//برای ساخت تاریخ از یک تاریخ جلالی، آرگومان دوم ارسالی به سازنده کلاس رو DATEX_JALALI قرار دهید
$x = new DatexObject(array('year'=>1391),DATEX_JALALI);

//__________________________USEFUL FUNCTIONS
//get date by granularity
$x->getDay();
$x->getYear();

//get time in UNIX timestamp
$x->getTimestamp();

$x->setDate)1391,19,5(;
$x->xsetDate(2012,4,3);

$x->difference($y,'days');

توابع دیگری که در این کتابخانه موجود هستند:

1.  تابع difference: این تابع اختلاف بین دو تاریخ را بر حسب میزان داده شده (ثانیه، دقیقه و ماه و ...) محاسبه میکند.
2.  تابع monthFirstDay و monthLastDay:  روز اول و آخر ماه جلالی ذخیره شده در شیئ را برمیگرداند.
3.  تابع xmonthFirstDay و xmonthLastDay:  روز اول و آخر ماه میلادی ذخیره شده در شیئ را برمیگرداند.
4.  datex_api_parse_jalali_from_format: این تابع یک Parser است که یک رشته تاریخ جلالی که شما فرمت و مقدار آن را نمیدانید میگیرد و تاریخ جلالی را از آن استخراج می‌کند. این تابع در حال حاضر در مرحله آزمایشی‌ست و استفاده از اون رو در محصول نهایی توصیه نمی‌کنم.
5.  برای دسترسی به توابع میلادی که با تاریخ جلالی مشترک نیستند، کافی است در ابتدای نام تابع حرف x (کوچک) را قرار دهید.

برای دریافت این کتابخانه به آدرس Github آن مراجعه کنید

بسیار خوشحال میشویم که چنانچه با مشکلی در استفاده از این کلاس برخوردید به ما گزارش کنید تا امکان رفع آن فراهم آید.