Filament Hijri Picker Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mohamedsabil83/filament-hijri-picker
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="MohamedSabil83\FilamentHijriPicker\FilamentHijriPickerServiceProvider"
   

2. First Use Case: Replace a standard DatePicker or DateTimePicker in a Filament form/resource with the Hijri equivalent:

   use MohamedSabil83\FilamentHijriPicker\Fields\HijriDatePicker;
   use MohamedSabil83\FilamentHijriPicker\Fields\HijriDateTimePicker;
   
   // In a Filament form/resource
   HijriDatePicker::make('event_date')
       ->required()
       ->default(now()->format('Y-m-d')),
   
   // Or for datetime
   HijriDateTimePicker::make('event_datetime')
       ->required()
       ->default(now()->format('Y-m-d H:i:s')),
   

3. Where to Look First:

   • README for basic usage.
   • Filament Docs for field customization patterns (applies similarly here).
   • config/filament-hijri-picker.php for package-specific configurations (e.g., locale, default format).

Implementation Patterns

Core Workflows

1. Replacing Default Filament Date Fields: Directly swap DatePicker/DateTimePicker with HijriDatePicker/HijriDateTimePicker in:

   • Resources: getFormFields() or getTableColumns().
   • Pages: Custom form fields.
   • Widgets: Dynamic forms (e.g., FormWidget).

   // Example in a Resource
   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               HijriDatePicker::make('birth_date')
                   ->label('تاريخ الميلاد')
                   ->columnSpanFull(),
           ]);
   }
   

2. Handling Hijri ↔ Gregorian Conversion:

   • Input/Output: The package auto-converts between Hijri (input) and Gregorian (storage/database).
   • Custom Logic: Use Carbon methods to manually convert if needed:

     use Carbon\Carbon;
     $gregorianDate = Carbon::createFromFormat('Y-m-d', $hijriInput)->toDateTimeString();
     

3. Localization:

   • Set the Hijri locale in the config:

     'locale' => 'ar', // Arabic (default), or 'en' for English labels
     

   • Override labels dynamically:

     HijriDatePicker::make('expiry_date')
         ->label('تاريخ الانتهاء')
         ->placeholder('اختر تاريخاً'),
     

4. Integration with Filament Tables:

   • Use HijriDateColumn for displaying Hijri dates in tables:

     use MohamedSabil83\FilamentHijriPicker\Columns\HijriDateColumn;
     
     HijriDateColumn::make('created_at')
         ->label('تاريخ الإنشاء')
         ->dateFormat('Y-m-d'),
     

5. Dynamic Defaults:

   • Set defaults in Hijri format (auto-converted to Gregorian on save):

     HijriDatePicker::make('deadline')
         ->default(now()->translatedFormat('Y-m-d', 'ar_SA')), // Hijri format
     

6. Validation:

   • Use standard Filament validation rules (e.g., required, after):

     HijriDatePicker::make('start_date')
         ->required()
         ->after('yesterday'),
     

Gotchas and Tips

Pitfalls

1. Database Storage:

   • The package stores dates in Gregorian format by default (standard for Laravel). Ensure your database columns are compatible (e.g., DATE or DATETIME types).
   • Fix: If storing raw Hijri strings, use string columns and handle conversion manually.

2. Timezone Conflicts:

   • Hijri dates are timezone-agnostic, but Gregorian conversion depends on the server’s timezone.
   • Tip: Set a consistent timezone in config/app.php (e.g., 'timezone' => 'Asia/Riyadh').

3. Locale Mismatches:

   • If labels appear in English despite locale: 'ar', clear the view cache:

     php artisan view:clear
     

4. Carbon Version Issues:

   • The package relies on Carbon for conversion. Ensure your carbon/carbon package is v2.x+ (Laravel 9+ compatible).
   • Fix: Update Carbon if errors occur:

     composer require carbon/carbon:^2.66
     

5. Nested Forms/Relationships:

   • Hijri fields in nested forms (e.g., BelongsToMany) may require explicit conversion in accessors/mutators:

     // Example mutator for a relationship
     public function setEventDateAttribute($value) {
         $this->attributes['event_date'] = Carbon::createFromFormat('Y-m-d', $value)->toDateTimeString();
     }
     

Debugging Tips

1. Check Stored Values:

   • Verify database storage with:

     dd($model->event_date); // Should be Gregorian (e.g., "2023-10-01")
     

   • Convert to Hijri for debugging:

     dd($model->event_date->translatedFormat('Y-m-d', 'ar_SA'));
     

2. Log Conversion Errors:

   • Wrap field usage in a try-catch to log issues:

     try {
         $field = HijriDatePicker::make('date_field');
     } catch (\Exception $e) {
         Log::error('Hijri Picker Error: ' . $e->getMessage());
     }
     

3. Test with Hardcoded Hijri Dates:

   • Manually test conversion with known Hijri dates (e.g., 1445-01-01 = Gregorian 2023-08-30):

     $hijriDate = '1445-01-01';
     $gregorian = Carbon::createFromFormat('Y-m-d', $hijriDate)->toDateTimeString();
     dd($gregorian); // Should output "2023-08-30 00:00:00"
     

Extension Points

1. Custom Hijri Formats:

   • Extend the package to support custom Hijri formats (e.g., d/m/Y):

     // In a service provider
     HijriDatePicker::macro('customFormat', function ($format) {
         $this->format = $format;
         return $this;
     });
     

     Usage:

     HijriDatePicker::make('date')->customFormat('d/m/Y');
     

2. Additional Locales:

   • Add support for other languages by extending the HijriPicker class and overriding __() methods.

3. Custom Conversion Logic:

   • Override the default conversion by binding a custom Carbon instance:

     HijriDatePicker::make('date')
         ->usingCarbon(function () {
             return Carbon::setLocale('ar_SA');
         }),
     

4. Filament 3.x Compatibility:

   • The package is built for Filament 3.x. For Filament 2.x, check the support branch or fork the package.

5. Performance:

   • For large datasets, pre-convert Hijri dates to Gregorian in queries to avoid runtime conversion:

     // In a query scope
     public function scopeHijriDate($query, $hijriDate) {
         $gregorianDate = Carbon::createFromFormat('Y-m-d', $hijriDate)->toDateTimeString();
         return $query->where('created_at', '>=', $gregorianDate);
     }