ultimatepos/PERSIAN_CALENDAR_SETUP.md

📅 راهنمای کامل شمسی‌سازی سیستم برای ایران

✅ تغییرات انجام شده

1. نصب پکیج تقویم شمسی

• افزودن morilog/jalali به composer.json برای تبدیل تاریخ میلادی به شمسی
• پکیج در دسترس برای استفاده در همه بخش‌های سیستم

2. به‌روزرسانی توابع تاریخ در PHP

فایل: app/Utils/Util.php

• تابع format_date(): تبدیل تاریخ میلادی به شمسی و نمایش با اعداد فارسی
• تابع uf_date(): تبدیل تاریخ شمسی ورودی کاربر به میلادی برای ذخیره در دیتابیس
• تابع format_time(): نمایش زمان با اعداد فارسی

3. به‌روزرسانی Blade Directives

فایل: app/Providers/AppServiceProvider.php

• @format_date: نمایش تاریخ شمسی در View ها
• @format_time: نمایش زمان با اعداد فارسی
• @format_datetime: نمایش تاریخ و زمان شمسی

4. به‌روزرسانی JavaScript

فایل: resources/views/layouts/partials/javascripts.blade.php

• افزودن کتابخانه persian-datepicker برای انتخاب تاریخ شمسی
• افزودن کتابخانه moment-jalaali برای کار با تاریخ شمسی در JavaScript
• تنظیم فرمت تاریخ پیش‌فرض برای فارسی: Y/m/d (1403/01/01)
• تنظیم فرمت moment برای فارسی: jYYYY/jMM/jDD

فایل: public/js/common.js

• به‌روزرسانی تنظیمات datepicker برای استفاده از تقویم شمسی
• به‌روزرسانی datetimepicker برای پشتیبانی از تقویم شمسی
• به‌روزرسانی date range picker برای استفاده از moment-jalaali

فایل: public/js/app.js

• به‌روزرسانی تمام date picker ها برای استفاده از Persian Date Picker
• پشتیبانی از .start-date-picker, #user_dob, .dob-date-picker

5. Helper Functions فارسی

فایل: app/Http/persian_helpers.php

توابع موجود:

• persian_number(): تبدیل اعداد انگلیسی به فارسی
• english_number(): تبدیل اعداد فارسی به انگلیسی
• persian_date(): تبدیل تاریخ میلادی به شمسی
• persian_price(): فرمت قیمت با اعداد فارسی
• persian_month_name(): نام ماه‌های شمسی
• persian_day_name(): نام روزهای هفته
• persian_words(): تبدیل عدد به حروف فارسی
• is_persian_lang(): بررسی فعال بودن زبان فارسی

🚀 نحوه نصب و راه‌اندازی

مرحله 1: نصب پکیج‌ها

composer install

یا اگر قبلاً نصب شده:

composer update morilog/jalali

مرحله 2: پاک‌سازی Cache

php artisan cache:clear
php artisan config:clear
php artisan view:clear
composer dump-autoload

مرحله 3: تنظیم زبان پیش‌فرض

در فایل .env:

APP_LOCALE=fa
APP_TIMEZONE=Asia/Tehran

مرحله 4: تنظیم تاریخ پیش‌فرض کسب‌وکار

در تنظیمات کسب‌وکار، فرمت تاریخ را به Y/m/d تغییر دهید.

📋 نحوه استفاده

در PHP (Backend)

use App\Utils\Util;

$util = new Util();

// نمایش تاریخ شمسی
$date = $util->format_date('2024-01-01'); // 1402/10/11

// تبدیل تاریخ شمسی به میلادی برای ذخیره
$gregorian = $util->uf_date('1403/01/01'); // 2024-03-20

// استفاده از helper function
$persian_date = persian_date(now(), 'Y/m/d'); // 1403/01/01

در Blade Template

{{-- نمایش تاریخ شمسی --}}
@format_date($transaction->transaction_date)

{{-- نمایش تاریخ و زمان شمسی --}}
@format_datetime($transaction->created_at)

{{-- نمایش زمان با اعداد فارسی --}}
@format_time($transaction->created_at)

در JavaScript

// استفاده از moment-jalaali
var today = moment.jDate(); // تاریخ امروز شمسی
var formatted = moment.jDate().format('jYYYY/jMM/jDD'); // 1403/01/01

// استفاده از Persian Date Picker
$('.date-picker').persianDatepicker({
    calendarType: 'persian',
    format: 'YYYY/MM/DD',
    autoClose: true
});

⚙️ تنظیمات پیش‌فرض برای ایران

فرمت تاریخ

• فرمت پیش‌فرض: Y/m/d (1403/01/01)
• فرمت کامل: Y/m/d H:i (1403/01/01 14:30)

منطقه زمانی

• پیش‌فرض: Asia/Tehran

ارز (نیاز به تنظیم دستی)

برای تنظیم ریال ایران، در تنظیمات کسب‌وکار ارز را به "Iranian Rial (IRR)" تغییر دهید.

🔄 تبدیل تاریخ

میلادی به شمسی

$jalali = \Morilog\Jalali\Jalalian::fromCarbon(\Carbon\Carbon::now());
echo $jalali->format('Y/m/d'); // 1403/01/01

شمسی به میلادی

$jalali = \Morilog\Jalali\Jalalian::fromFormat('Y/m/d', '1403/01/01');
$carbon = $jalali->toCarbon();
echo $carbon->format('Y-m-d'); // 2024-03-20

📝 نکات مهم

1. ذخیره‌سازی در دیتابیس: همه تاریخ‌ها به صورت میلادی (Gregorian) در دیتابیس ذخیره می‌شوند.

2. نمایش به کاربر: تاریخ‌ها به صورت شمسی (Jalali) با اعداد فارسی نمایش داده می‌شوند.

3. ورودی کاربر: کاربر تاریخ را به صورت شمسی وارد می‌کند و سیستم آن را به میلادی تبدیل می‌کند.

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

🐛 عیب‌یابی

اگر تاریخ‌ها نمایش داده نمی‌شوند:

1. بررسی کنید که زبان سیستم روی fa تنظیم شده باشد
2. Cache را پاک کنید: php artisan cache:clear
3. بررسی کنید که پکیج morilog/jalali نصب شده باشد: composer show morilog/jalali

اگر Date Picker کار نمی‌کند:

1. بررسی کنید که کتابخانه‌های JavaScript لود شده‌اند (در Developer Tools مرورگر)
2. بررسی کنید که متغیر is_persian_lang در JavaScript تعریف شده باشد
3. بررسی Console مرورگر برای خطاهای JavaScript

✅ چک‌لیست تست

• تاریخ‌های نمایش داده شده به صورت شمسی هستند
• اعداد تاریخ به فارسی نمایش داده می‌شوند (۰-۹)
• Date Picker تاریخ شمسی را نمایش می‌دهد
• ورود تاریخ شمسی از کاربر به درستی تبدیل می‌شود
• گزارش‌ها تاریخ شمسی را نمایش می‌دهند
• فاکتورها تاریخ شمسی را نمایش می‌دهند

📞 پشتیبانی

در صورت بروز مشکل، لطفاً موارد زیر را بررسی کنید:

1. نسخه PHP (حداقل 8.0)
2. نصب بودن تمام پکیج‌های Composer
3. پاک بودن Cache
4. تنظیمات زبان در .env

---

نکته مهم: پس از انجام تغییرات، حتماً Cache را پاک کرده و composer dump-autoload را اجرا کنید.