Filament Hijri Picker Laravel Package

Technical Evaluation

Architecture Fit

• Filament Integration: The package is a Filament-specific extension, leveraging Filament’s existing DatePicker and DateTimePicker components. This ensures low architectural disruption—it plugs into Filament’s form system without requiring changes to core Laravel or Filament logic.
• Hijri Calendar Support: Targets localization needs for Arabic-speaking markets, where Hijri (Islamic) dates are standard. Aligns with Filament’s modular design, allowing region-specific customizations.
• Limited Scope: Focuses solely on UI/UX for date selection; no backend storage or validation logic is provided. Requires TPM to define how Hijri dates map to storage (e.g., converting to Gregorian for DB storage or dual-storage strategies).

Integration Feasibility

• Dependency Alignment: Requires Filament v3.x (explicitly tested against it). Compatibility with Filament v2.x is unlikely without modifications.
• PHP/Laravel Compatibility: No strict PHP version constraints in the README, but Filament v3.x typically supports PHP 8.1+. Assumes modern Laravel (v10+) due to Filament’s dependencies.
• Frontend Stack: Uses Alpine.js (Filament’s default) and likely Laravel Mix/Vite for asset compilation. No jQuery or legacy JS dependencies.

Technical Risk

• Localization Gaps: Hijri date handling may conflict with existing Laravel Carbon or Jalali extensions if not managed. Risk of timezone/date normalization issues when mixing Hijri/Gregorian in the same system.
• Testing Coverage: GitHub Actions show basic test workflows, but no evidence of end-to-end Filament integration tests (e.g., form submission, validation). Risk of edge cases in real-world usage.
• Future-Proofing: Package is new (2026 release) with no major dependents. Risk of abandonment or breaking changes if Filament’s form system evolves.
• Database Schema: No guidance on how to store Hijri dates in the DB. TPM must decide between:
  • Storing as ISO strings (e.g., 1445-05-12).
  • Converting to Gregorian for queries.
  • Using a custom column type (e.g., hijri_date).

Key Questions

1. Storage Strategy:
   • How will Hijri dates be persisted in the database? Will we use a separate column or JSON field?
   • How will we handle queries/filtering by Hijri dates (e.g., WHERE hijri_date BETWEEN...)?
2. Validation:
   • Should Hijri dates be validated against Islamic calendar rules (e.g., month lengths, leap years)?
   • How will we handle Gregorian ↔ Hijri conversion in validation logic?
3. User Experience:
   • Will users need to toggle between Gregorian/Hijri views? If so, how?
   • Should the picker default to Hijri for all users in a region, or be optional?
4. Performance:
   • What impact will Hijri ↔ Gregorian conversions have on API/database performance?
   • Are there caching strategies for frequent conversions?
5. Localization:
   • Does the package support right-to-left (RTL) layouts for Arabic interfaces?
   • Are there cultural UI considerations (e.g., date format preferences like DD/MM/YYYY vs. YYYY-MM-DD)?
6. Testing:
   • Are there automated tests for edge cases (e.g., invalid Hijri dates, timezone offsets)?
   • How will we test Hijri date logic in CI/CD pipelines?
7. Maintenance:
   • Who will update the package if Filament releases breaking changes?
   • Is there a fallback plan if the package is abandoned?

Integration Approach

Stack Fit

• Filament v3.x: Native fit—designed as a drop-in replacement for Filament’s built-in pickers. No changes to Filament’s core required.
• Laravel Ecosystem:
  • Carbon: Likely needed for Hijri ↔ Gregorian conversions (e.g., using carbon/hijri or mwallace/hijri).
  • Validation: Requires custom rules if Hijri-specific validation is needed (e.g., ensuring dates fall within Islamic months).
  • Database: Needs alignment with storage strategy (e.g., datetime, string, or custom type).
• Frontend:
  • Alpine.js: Already used by Filament; no additional setup needed.
  • CSS: May require RTL styling for Arabic interfaces (e.g., dir="rtl").

Migration Path

1. Assessment Phase:
   • Audit existing date fields in Filament forms to identify candidates for Hijri conversion.
   • Decide on storage strategy (see Technical Evaluation).
2. Dependency Setup:
   • Install the package:

     composer require mohamedsabil83/filament-hijri-picker
     

   • Publish and configure Filament if needed (e.g., RTL settings).
3. Backend Integration:
   • Add Hijri ↔ Gregorian conversion logic (e.g., using Carbon extensions).
   • Update database migrations to accommodate new fields/types.
   • Implement validation rules for Hijri dates (if required).
4. Frontend Replacement:
   • Replace existing DatePicker/DateTimePicker with HijriDatePicker/HijriDateTimePicker in Filament forms:

     use MohamedSabil83\FilamentHijriPicker\Fields\HijriDatePicker;
     
     HijriDatePicker::make('event_date')
         ->label('تاريخ الحدث')
         ->required(),
     

5. Testing:
   • Test form submissions, database storage, and queries for correctness.
   • Verify timezone handling (e.g., Hijri dates are timezone-agnostic; ensure Gregorian conversions respect user timezones).

Compatibility

• Filament Plugins: May conflict with other Filament form field plugins if they override the same components. Test with:
  • Filament Spatie Media Library.
  • Filament Tables (if using date filtering).
• Legacy Systems: If the app mixes Gregorian and Hijri dates, ensure APIs and reports handle conversions consistently.
• Browser Support: Alpine.js-based; should work on all modern browsers. Test with Arabic input methods (e.g., virtual keyboards).

Sequencing

1. Phase 1 (Low Risk):
   • Install and test the package in a staging environment.
   • Replace non-critical date fields first (e.g., event dates).
2. Phase 2 (Medium Risk):
   • Implement Hijri storage/validation logic.
   • Update database schema for new fields.
3. Phase 3 (High Risk):
   • Roll out to production forms with monitoring for:
     • Date conversion errors.
     • Validation failures.
     • Performance bottlenecks.
4. Phase 4 (Ongoing):
   • Add Hijri support to APIs/reports.
   • Document troubleshooting steps for Hijri ↔ Gregorian issues.

Operational Impact

Maintenance

• Package Updates:
  • Monitor Filament v3.x updates for breaking changes.
  • Watch for new releases of filament-hijri-picker (currently minimal activity).
• Custom Logic:
  • Conversion utilities (Hijri ↔ Gregorian) may need updates if Carbon or other libraries change.
  • Validation rules may require adjustments for edge cases (e.g., invalid Hijri dates).
• Localization:
  • Arabic language strings (e.g., month/day names) may need updates for dialectal variations.

Support

• User Training:
  • Train non-technical users on Hijri date input (e.g., format expectations, invalid dates).
  • Document common issues (e.g., "Why does my Hijri date appear as Gregorian in reports?").
• Debugging:
  • Log Hijri ↔ Gregorian conversion failures for troubleshooting.
  • Provide fallback Gregorian pickers for users who prefer them.
• Third-Party Dependencies:
  • Support for Carbon extensions (e.g., orangehill/isee) may be needed for advanced use cases.

Scaling

• Performance:
  • Conversion overhead: Each Hijri ↔ Gregorian conversion adds ~1–5ms latency (depending on implementation). Test under load if used in high-frequency forms.
  • Database indexing: Ensure Gregorian-converted dates are indexed for query performance.
• Multi-Region Deployments:
  • Hijri dates are region-agnostic, but