Filament Calendar Laravel Package

Getting Started

1. Install via Composer using the package name from the README (e.g. composer require <vendor>/filament-jalali-calendar). Confirm the package supports Filament v5 in its composer.json.
2. Publish assets/config if required:

   php artisan vendor:publish --tag="filament-jalali-calendar-config"
   php artisan vendor:publish --tag="filament-jalali-calendar-assets"
   php artisan filament:assets
   

3. Register the plugin in each Filament panel provider if the package ships one:

   ->plugin(JalaliCalendarPlugin::make())
   

4. Clear caches after installation: php artisan optimize:clear and php artisan filament:optimize-clear.

Where to look first

• README.md for the exact field class name and configuration options.
• src/ for the form component (likely JalaliDatePicker or CalendarPicker) and any plugin class.
• config/ for default calendar mode, locale, and asset paths.
• resources/views and resources/js if you need to customise rendering or debug front‑end behaviour.

First use case Replace a standard Filament DatePicker in a resource form so users can pick dates in Jalali or Gregorian:

use Vendor\FilamentJalaliCalendar\Forms\Components\JalaliDatePicker;

JalaliDatePicker::make('birth_date')
    ->label('Birth date')
    ->required();

The field should output a standard date string (typically Gregorian Y-m-d) for persistence, while displaying the selected calendar to the user.

Implementation Patterns

• Form fields everywhere: Use the picker in resource forms, relation managers, custom Livewire forms, and table filters (->form([JalaliDatePicker::make('created_at')])).
• Calendar mode: Configure per field if supported (e.g. ->calendar('jalali'), ->calendar('gregorian'), ->calendar('both')). Defaults usually come from the config file.
• Persistence and casts: Filament typically stores dates as Y-m-d. Ensure your model casts are set:

  protected $casts = ['birth_date' => 'date'];
  

  Verify whether the package converts Jalali input to Gregorian before saving; if it stores Jalali strings, add conversion logic in the model or a form dehydrateStateUsing callback.
• Table columns: The package may not provide a column. Use TextColumn::make('birth_date')->formatStateUsing(fn ($state) => ...) with a Jalali converter (e.g. hekmatinasser/verta or morilog/jalali) to display Persian dates.
• Validation: Apply standard Laravel date rules (->rules(['date']), ->beforeOrEqual('today')). Test Jalali‑specific boundaries (leap years, month lengths).
• Localization: Set the panel/app locale to fa if the package uses translations. Otherwise set labels and placeholders manually.
• Multi‑panel apps: Register the plugin in every panel provider that needs the field.
• Custom Livewire components: Include the field in the form schema like any other Filament component; ensure the component’s mount and save handle the date value consistently.

Gotchas and Tips

• Initial release risk: v1.0.0 has minimal documentation and may contain bugs. Pin the version in composer.json ("vendor/package": "^1.0") and test thoroughly before production.
• Filament v5 only: Confirm your app runs Filament v5; the package likely does not support v3/v4.
• Asset publishing: Missing JS/CSS assets cause a broken picker UI. Always run php artisan filament:assets after install and after upgrades.
• Date storage ambiguity: Test a submission and inspect the database value. If the package stores Jalali dates, queries and comparisons will break. Add a dehydrateStateUsing or model mutator to normalise to Gregorian.
• Timezone shifts: Date‑only fields can shift by a day if timezones are mishandled. Store as date (no time) and avoid datetime casts unless necessary.
• RTL layout: For Persian UIs, ensure the panel direction is RTL. Filament v5 may support ->direction('rtl') or rely on locale; test the picker’s popover positioning.
• Debugging: If the field does not render, check plugin registration, service provider discovery (composer dump-autoload), and that the correct field class is imported. Use php artisan about to confirm providers.
• Extension points: Publish views and config to customise the picker. If the field class is not final, extend it to override behaviour. Watch for events or macros exposed by the package.
• Upgrade path: Since this is the first release, monitor subsequent versions for breaking changes to the field API or config keys. Keep a changelog review step in your upgrade process.