پکیج تاریخ شمسی در لاراول

سلام دوستان گرامی ، امروز میخوام شما عزیزان را با نسخه جدید پکیج کاربردی و قدرتمند تاریخ شمسی در لاراول که توسط یکی از دوستان عزیزم ناصرحکمتی نوشته شده را معرفی کنم ، امیدوارم مورد توجه شما عزیزان واقع بشود.

پکیج تاریخ شمسی در لاراول

برنامه نویسان فارسی زبان برای استفاده از تاریخ شمسی از الگوریتم تبدیل تاریخ میلادی به شمسی استفاده می کنند. برای زبان php و فریم ورک لاراول این الگوریتم به صورت پکیج وجود دارد. Verta یک پکیج برای تبدیلات تاریخ شمسی به میلادی و بالعکس می باشد و شامل توابع کمکی که کاربران به راحتی بتوانند تبدیلات تاریخ خود را انجام دهند.

زبان php دارای کلاسی به نام Datetime است که Verta از همین کلاس ارث بری کرده است. دقت داشته باشید این پکیج سازگار با همه نسخه ها و  ۵.۵ لاراول می باشد.

پکیج قدرتمند carbon یکی از پکیج های پیش فرض لاراول است که برای کار با تاریخ میلادی بسیار کاربردی است. Verta با هدف ارایه توابع و امکاناتی همچون carbon سعی در کمک به برنامه نویسان فارسی زبان دارد.

نصب

برای استفاده از این پکیج باید ابتدا پکیج را دریافت و نصب کنید برای این کار از دستور زیر را وارد کنید:

composer require hekmatinasser/verta

حال باید پکیج را درون پروژه خود ثبت کنید برای این کار فایل config/app.php در آرایه providers دستور زیر را وارد کنید:

Hekmatinasser\Verta\VertaServiceProvider::class,

سپس در آرایه alias دستور زیر را وارد کنید:

'Verta' = Hekmatinasser\Verta\Verta::class,

حالا میتوانید از این پکیج در پروژه خود استفاده کنید. حال با نحوه استفاده از پکیج و توابع آن معرفی خواهیم کرد:

هر کلاسی که از verta استفاده میکنید باید در بالای کد های خود کلاس verta را اضافه کنید، دستور زیر را وارد کنید:

use Verta;

توابع Verta در دسته بندی های مجزا تقسیم شده است و هر دسته بندی اعمال خاصی بر روی تاریخ را انجام خواهند داد.

توابع ایجاد تاریخ

شما میتوانید کلاس Verta بدین صورت ایجاد کنید:

$v = verta();
$v = new Verta();

در صورتی میخواهید نسبت به تاریخ امروز تاریخ فردا ییا دیروز را بدست آورید از دستور زیر استفاده کنید :

$v = Verta::now(); //1396-02-02 15:32:08
$v = Verta::today(); //1396-03-02 00:00:00
$v = Verta::tomorrow(); // 1396-03-03 00:00:00
$v = Verta::yesterday(); // 1396-03-01 00:00:00

در صورتی که پارامتر شما رشته از سال میلادی است از دستور زیر استفاده کنید:

$v = new Verta('2016-12-27 14:12:32');
$v = Verta::instance('2016-12-25 11:12:36');

ارسال پارامتر timestamp

برای استفاده از عدد timestamp به شمسی، از دستور زیر استفاده کنید :

$v = new Verta(1333857600);

ارسال پارامتر Datetime

برای استفاده از کلاس Datetime به شمسی، از دستور زیر استفاده کنید:

$dt = new \Datetime();
return new Verta($dt); // 1395-12-09 15:05:56

ارسال پارامتر carbon

$c = \Carbon::now();
return new Verta($c); // 1395-12-09 15:05:56

برای استفاده از تاریخ شمسی به صورت رشته، از دستور زیر استفاده کنید :

$v = Verta::parse('1395-10-07 14:12:32');
$v = Verta::parse('1396 مهر ۱۷'); 
$v =  Verta::parseFormat('Y n j','1396 مهر ۱۷');

اگر پارامتر های تاریخ شما به صورت مجزا باشد تابع create برای شما این کار را انجام خواهد داد. تابع create پارامتر هایی که از شما دریافت نمیشود با تاریخ و زمان فعلی پر میکند.

return Verta::create(2016,12,25,15,20,15);

شما میتوانید بخشی از تاریخ و زمان را نیز ارسال کنید :

return Verta::createDate(2016,12,25);
return Verta::createTime(15,51,5);

تابع createGregorian مانند تابع create تاریخ میلادی را دریافت می کند.

return Verta::createGregorian(2016,12,25,15,20,15); // 1395-10-05 15:20:15
return Verta::createGregorianDate(2016,12,25); // 1395-10-05 21:35:49 set time now
return Verta::createGregorianTime(15,51,5); // 1396-02-31 15:51:05 set date now

در صورتی که پارامتر ها تاریخ شمسی استفاده می کنید از توابع createJalali استفاده کنید.

return Verta::createJalali(1394,12,29,15,51,5);  // 1394-12-29 15:51:05
return Verta::createJalaliDate(1394,12,29); // 1394-12-29 11:18:29 set time now
return Verta::createJalaliTime(15,51,5); // 1395-12-14 15:51:05 set date now

مقادیر و مقداردهی get and set

یکی از قابلیتها خوب دسترسی به هر خصوصیت از تاریخ میباشد. شما میتوانید سال و … به صورت یک خصوصیت دریافت کنید.

$v = verta();
return $v->year; // 1396
return $v->month; // 3
return $v->day; // 14
return $v->hour; // 14
return $v->minute; // 18
return $v->second; // 23
return $v->timestamp; // 1496557661
return $v->timezone; // Asia/Tehran

میتوانید مقدار هر یک از قسمتهای تاریخ را نیز مقداردهی کنید. شما هم به صورت مقداردهی به یک خصوصیت و هم به صورت یک متد میتوانید این کار را انجام دهید.

$v = verta();
$v->year = 1395;
$v->month = 4; // set 13 for next year first month
$v->day = 25;
$v->hour = 16;
$v->minute = 50;
$v->second = 42;
$v->timestamp = 1496557661;
$v->timezone = 'Asia/Baku';

برای مقدار دهی خصوصیات با استفاده از تابع، از دستورات زیر استفاده کنید :

$v = $v->year(1395)
$v = $v->month(4) // set 13 for next year first month
$v = $v->day(25)
$v = $v->hour(16)
$v = $v->minute(50)
$v = $v->second(42)
$v = $v->timestamp(1496557661)
$v = $v->timezone('Asia/Baku');

در صورتی که میخواهید به یکباره مقداردهی کنید از توابع زیر استفاده کنید:

$v = $v->setDateTime(1395, 4, 25, 16, 50, 42);
$v = $v->setDateTime(1395, 4, 25, 16, 50, 42, 1569856);
$v = $v->setDate(1395, 4, 25);
$v = $v->setTimeString('12:25:48');

در صورتی که وجود هر یک مقادیر را میخواهید بررسی کنید از تابع isset استفاده کنید.

$v = verta();
echo isset($v->year); // true
echo isset($v->month); // true
echo empty($v->day); // false
echo empty($v->hour); // false
echo empty($v->minute); // false
echo empty($v->second); // false
echo isset($v->timestamp); // true
echo isset($v->timezone); // true

توابع فرم خروجی

زمانی که میخواهید تاریخ خود را چاپ کنید تابع format به شما این امکان را میدهد هر بخشی از تاریخ خود را مشاهده کنید. وقتی شی از کلاس Verta را return میکنید به صورت پیشفرض فرمت را خروجی می دهد.

return new Verta(); // 1395-12-12 00:18:04

شما میتوانید فرمت خروجی هنگام که return را مشخص کنید:

Verta::setStringformat('Y/n/j H:i:s');
return new Verta(); // 1395/12/12 00:11:35

برای تنظیم مجددفرمت خروجی به حالت اولیه، از دستور زیر استفاده کنید :

Verta::resetStringFormat();

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

$v = new Verta('2016-12-27 14:12:32');
return $v->format('Y-n-j H:i'); // 1395-10-7 14:12
return $v->format('%B %d، %Y'); // دی ۰۷، ۱۳۹۵
return $v; //1395-10-07 14:12:32

فرمت های از پیش تعیین شدهای در Verta مشخص شده است که چاپ فرمت های رایج را آسانتر میکند :

$v = new Verta();
return $v->formatDatetime(); // 1395-12-10 23:37:26
return $v->formatDate(); // 1395-12-10
return $v->formatTime(); // 23:26:35
return $v->formatJalaliDatetime(); // 1395/12/10 23:46:09
return $v->formatJalaliDate(); // 1395/12/10

در صورتی که بخواهید اعداد را به صورت فارسی نمایش دهید تابع persianNumbers تبدیل اعداد به فارسی را انجام خواهد داد:

return Verta::persianNumbers($v); // ۱۳۹۶-۱۰-۰۷ ۱۴:۱۲:۳۲

در صورتی که میخواهید معادل میلادی تاریخ خود را چاپ کند از دستور زیر میتوانید استفاده کنید:

return $v->DateTime()->format('Y-m-d H:i:s'); // 2017-05-23 23:21:02
return $v->formatGregorian('Y-m-d H:i:s'); // 2017-05-23 23:21:02

برای نمایش اختلاف تاریخ به صورت واحد زمانی، از دستور زیر استفاده کنید درصورتی که تاریخ را وارد نکنید، اختلاف با زمان کنونی محاسبه می شود.

return $v1->formatDifference($v2); // 12 ماه بعد
return $v1->formatDifference($v3); // 1 سال قبل
return $v1->addDays(25)->formatDifference(); // 4 هفته بعد
return $v1->subDays(6)->formatDifference(); // 6 روز قبل
return verta()->formatDifference(); // 

متد نمایش اعداد به صورت حروف

 برای نمایش اعداد به صورت حروف، از دستور زیر استفاده کنید :

return $v->formatWord('Y'); // یک هزار و سیصد و نود و شش
return $v->formatWord('l dS F'); // چهارشنبه بیست و نه ام شهریور
return $v->formatWord('d F Y'); // بیست و نه شهریور یک هزار و سیصد و نود و شش
return $v->formatWord('r'); // چهارشنبه یک هزار و سیصد و نود و شش, شش, بیست و نه, بیست و دو:چهل و نه:سی و هشت +۰۴:۳۰
return $v->formatWord('d F ') . $v->year; //

در صورتی که بخواهید اعداد را به صورت فارسی نمایش دهید  تابع persianNumbersتبدیل اعداد به فارسی را انجام خواهد داد:

return Verta::persianNumbers($v); // ۱۳۹۶-۱۰-۰۷ ۱۴:۱۲:۳۲

در صورتی که میخواهید تابع فرمت معادل میلادی تاریخ خود را چاپ کند از دستور زیر میتوانید استفاده کنید:

return $v->DateTime()->format('Y-m-d H:i:s'); // 2017-05-23 23:21:02
return $v->formatGregorian('Y-m-d H:i:s'); // 2017-05-23 23:21:02

متد تغییر دادن

برای اضافه یا کم کردن از تاریخ خود، از دستور زیر استفاده کنید :

$v = verta();
return $v->addYear(); // 1396-10-07 14:12:32
return $v->addYears(4); // 1399-10-07 14:12:32
return $v->subYear(); // 1394-10-07 14:12:32
return $v->subYears(2); // 1393-10-07 14:12:32

return $v->addMonth(); // 1395-11-07 14:12:32
return $v->addMonths(5); // 1396-03-07 14:12:32
return $v->subMonth(); // 1395-09-07 14:12:32
return $v->subMonths(2); // 1395-08-07 14:12:32

return $v->addWeek(); // 1395-10-12 14:12:32
return $v->addWeeks(3); // 1395-10-26 14:12:32
return $v->subWeek(); // 1395-09-30 14:12:32
return $v->subWeeks(2); // 1395-09-27 14:12:32

return $v->addDay(); // 1395-10-08 14:12:32
return $v->addDays(3); // 1395-10-11 14:12:32
return $v->subDay(); // 1395-10-06 14:12:32
return $v->subDays(2); // 1395-09-05 14:12:32

return $v->addHour(); // 1395-10-07 15:12:32
return $v->addHours(5); // 1395-10-07 19:12:32
return $v->subHour(); // 1395-10-07 13:12:32
return $v->subHours(2); // 1395-10-07 12:12:32

return $v->addMinute(); // 1395-10-07 14:13:32
return $v->addMinutes(3); // 1395-10-07 14:15:32
return $v->subMinute(); // 1395-10-07 14:11:32
return $v->subMinutes(2); // 1395-10-07 14:10:32

return $v->addSecond(); // 1395-10-07 14:12:33
return $v->addSeconds(3); // 1395-10-07 14:12:35
return $v->subSecond(); // 1395-10-07 14:12:31
return $v->subSeconds(2); // 1395-10-07 14:12:30

محاسبات

متد های محاسباتیverta همانندcarbon می باشدو شما میتوانیدبه تاریخ خود واحد های زمانی سال، ماه،هفته، روز، ساعت، دقیقه و ثانیه آضافه یا کم کنید:

$v = Verta::parse('1395-10-07 14:12:32');
return $v->addYear(); // 1396-10-07 14:12:32
return $v->addYears(4); // 1399-10-07 14:12:32
return $v->subYear(); // 1394-10-07 14:12:32
return $v->subYears(2); // 1393-10-07 14:12:32

return $v->addMonth(); // 1395-11-07 14:12:32
return $v->addMonths(5); // 1396-03-07 14:12:32
return $v->subMonth(); // 1395-09-07 14:12:32
return $v->subMonths(2); // 1395-08-07 14:12:32

return $v->addWeek(); // 1395-10-12 14:12:32
return $v->addWeeks(3); // 1395-10-26 14:12:32
return $v->subWeek(); // 1395-09-30 14:12:32
return $v->subWeeks(2); // 1395-09-27 14:12:32

return $v->addDay(); // 1395-10-08 14:12:32
return $v->addDays(3); // 1395-10-11 14:12:32
return $v->subDay(); // 1395-10-06 14:12:32
return $v->subDays(2); // 1395-09-05 14:12:32

return $v->addHour(); // 1395-10-07 15:12:32
return $v->addHours(5); // 1395-10-07 19:12:32
return $v->subHour(); // 1395-10-07 13:12:32
return $v->subHours(2); // 1395-10-07 12:12:32

return $v->addMinute(); // 1395-10-07 14:13:32
return $v->addMinutes(3); // 1395-10-07 14:15:32
return $v->subMinute(); // 1395-10-07 14:11:32
return $v->subMinutes(2); // 1395-10-07 14:10:32

return $v->addSecond(); // 1395-10-07 14:12:33
return $v->addSeconds(3); // 1395-10-07 14:12:35
return $v->subSecond(); // 1395-10-07 14:12:31
return $v->subSeconds(2); // 1395-10-07 14:12:30

متد بدست آوردن تاریخ شروع و پایان هر بازه زمانی

برای بدست آوردن تاریخ شروع و پایان هر بازه زمانی، از دستور زیر استفاده کنید :

$v = verta(); // 1396-04-29 14:25:48
return $v->startDay(); // 1396-04-29 00:00:00
return $v->endDay(); // 1396-04-29 23:59:59
return $v->startWeek(); // 1396 1396-04-24 00:00:00
return $v->endWeek(); // 1396-04-30 23:59:59
return $v->startMonth(); // 1396-04-01 00:00:00
return $v->endMonth(); // 1396-04-31 00:00:00
return $v->startQuarter(); // 1396-04-01 00:00:00
return $v->endQuarter(); // 1396-06-31 23:59:59
return $v->startYear(); // 1396-01-01 00:00:00
return $v->endYear(); // 1396-12-29 23:59:59

متد های مقایسه ای

متد های مقایسه ای برای بررسی صحت تاریخ و زمان و مقایسه با تاریخ اکنون وجود دارد.

خروجی متد  isLeapYear مشخص میکند سال مورد نظر کبیسه است یا خیر؟

echo Verta::isLeapYear(1394); // false
echo Verta::isLeapYear(1395); // true

خروجی متد isLeapYear مشخص میکند سال مورد نظر کبیسه است یا خیر؟

echo Verta::isLeapYear(1394); // false
echo Verta::isLeapYear(1395); // true

خروجی متد isValideDate و isValideTime مشخص میکند معتبر است یا خیر؟

توجه داشته باشید متد isValideDate مخصوص تاریخ شمسی میباشد.

echo Verta::isValideDate(1394, 12, 30); // false
 echo Verta::isValideDate(1395, 12, 30); // true

echo Verta::isValideTime(15, 62, 50); // false
echo Verta::isValideTime(15, 12, 30); // true

 متد اختلاف تاریخ ها با یکدیگر

برای محاسبه اختلاف تاریخ ها با یکدیگر، از دستور زیر استفاده کنید :

$v1 = verta(); // 1396-03-31 22:21:40
$v2 = verta('2017-06-21 01:21:40'); // 1396-03-31 01:21:40
$v3 = verta('2017-06-20'); // 1396-03-30 15:24:53

return $v1->diffYears($v3); // -1
return $v1->diffMonths($v2); // 11
return $v2->diffMonths(); // -11 compare with now
return $v1->diffWeeks($v2); // 51
return $v1->diffDays($v3); // -372
return $v3->diffMinutes(); // 536548
return $v3->diffMinutes(); // 536548

برای مقایسه تاریخ ها با یکدیگر، از دستور زیر استفاده کنید :

echo $v1->eq($v2); // false equalTo();
echo $v1->ne($v2); // true notEqualTo()
echo $v1->gt($v2); // true greaterThan()
echo $v1->gte($v2); // true greaterThanOrEqualTo()
echo $v1->lt($v2); // false lessThan()
echo $v1->lte($v2); // false lessThanOrEqualTo()
echo $v1->between($v2, $v3); // false

برای بررسی تاریخ از لحاظ نزدیکتر یا دورتر بودن و یا کوچکتر و بزرگتر بودن، از دستور زیر استفاده کنید :

echo $v1->closest($v2, $v3); // return $v2 object
echo $v1->farthest($v2, $v3); // return $v3 object
echo $v1->minimum($v2); // return $v2
echo $v1->min($v2); // return $v2
echo $v1->maximum($v2); // return $v1
echo $v1->max($v2); // return $v1

برای بررسی تاریخ با تاریخ فعلی، از دستور زیر استفاده کنید :

echo $v1->isWeekday(); // true
echo $v1->isWeekend(); // false
echo $v1->isYesterday(); // false
echo $v1->isToday(); // true
echo $v1->isTomorrow(); // false
echo $v1->isNextWeek(); // false
echo $v1->isLastWeek(); // false
echo $v1->isNextMonth(); // false
echo $v1->isLastMonth(); // false
echo $v1->isNextYear(); // false
echo $v1->isLastYear(); // false
echo $v1->isFuture(); // false
echo $v1->isPast(); // false
echo $v1->isPast(); // false

echo $v1->isCurrentYear(); // true
echo $v1->isSameAs('y', $v2); // true isSameYear()
echo $v1->isCurrentMonth(); // true
echo $v1->isSameMonth($v2); // true
echo $v1->isSameDay($v2); // true
echo $v1->isBirthday(); // true compare with today
echo $v1->isBirthday($v2); // true

echo $v1->isSaturday(); // false
echo $v1->isSunday(); // false
echo $v1->isMonday(); // false
echo $v1->isTuesday(); // false
echo $v1->isWednesday(); // false
echo $v1->isThursday(); // true
echo $v1->isFriday(); // false

تبدیلات

شما میتوانید تاریخ میلادی و شمسی به یکدیگر تبدیل کنیدو خروجی آن آرایه ای شامل سه عدد تبدیل شده خواهد بود.

return Verta::getJalali(2015,12,25); // [1394,10,4]
return Verta::getGregorian(1394,10,4); // [2015,12,25]

شما حتی میتوانید تاریخ خود را به انواع کلاسهای تاریخ در php و carbon تبدیل کنید.

$v = Verta::parse('1395/01/05 23:50:25');
$dt = $v->DateTime();
$v = Verta::parse('1395/01/05 23:50:25');
$c = Carbon::instance($v->DateTime());

امیدوارم این مطلب برای شما مفید باشد.

نویسنده : ناصر حکمتی

منبع : www.studio-design.ir