Filament Date Range Picker and Filter

https://github.com/malzariey/filament-daterangepicker-filter
Admin
This package adds a date range picker and filter to the Filament panel using the daterangepicker...
Tokens:55,461
Snippets:474
Trust Score:7.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup Commands

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/CONTRIBUTING.md

Sets up the development environment by cloning the repository, installing PHP and Node dependencies, and building front-end assets.

```bash
# 1. Clone the repository
git clone https://github.com/malzariey/filament-daterangepicker-filter.git
cd filament-daterangepicker-filter

# 2. Install PHP dependencies
composer install

# 3. Install Node dependencies
npm install

# 4. Build front-end assets
npm run build
```

--------------------------------

### Install via Composer

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Run this command to install the package using Composer.

```bash
composer require malzariey/filament-daterangepicker-filter
```

--------------------------------

### Start PHP Dev Server

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/CONTRIBUTING.md

Starts the PHP dev server for the demo app in the second terminal.

```bash
vendor/bin/testbench serve
```

--------------------------------

### Set start and end dates with startDate() and endDate()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Sets explicit start and end dates. Also shows shortcut methods for common defaults: defaultToday(), defaultLast7Days(), defaultThisMonth(), defaultLastYear().

```php
DateRangePicker::make('created_at')
    ->startDate(Carbon::now())
    ->endDate(Carbon::now())

// Or use shortcuts:
DateRangePicker::make('created_at')->defaultToday()
DateRangePicker::make('created_at')->defaultLast7Days()
DateRangePicker::make('created_at')->defaultThisMonth()
DateRangePicker::make('created_at')->defaultLastYear()
```

--------------------------------

### setUp() method

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangeFilter.md

Protected method that calls parent::setUp(), binds the filter to its column via useColumn(), and enables the indicator by default.

```php
protected function setUp(): void
{
    parent::setUp();
    $this->useColumn($this->getName());
    $this->withIndicator();
}
```

--------------------------------

### getDualStartField(): ?string

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Returns the configured Livewire property name for the dual start field, or null when disabled.

```APIDOC
## getDualStartField(): ?string

### Description
Returns the configured Livewire property name for the dual start field, or null when disabled.

### Method
Getter method

### Returns
- **?string** - The Livewire property name or null.

### Source
`src/Concerns/HasRangePicker.php:615`
```

--------------------------------

### startDate

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Sets the default start date. Optionally enforces the default on edit when the current value is null.

```APIDOC
## startDate

### Description
Default start date; `$enforceIfNull` forces the default on edit when the current value is null.

### Method
`startDate(CarbonInterface|string|Closure|null $date, $enforceIfNull = false): static`

### Parameters
- **$date** (CarbonInterface|string|Closure|null) - Optional - Default: `null` - The default start date.
- **$enforceIfNull** (bool) - Optional - Default: `false` - When true, forces the default on edit when the current value is null.

### Returns
`static` - The current instance for chaining.
```

--------------------------------

### DateRangeFilter::make() constructor

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangeFilter.md

Creates a new DateRangeFilter instance. The $name parameter is the column name; setUp() binds the filter to a column with that name.

```php
DateRangeFilter::make(string $name)
```

--------------------------------

### Store start and end dates in separate Livewire properties with useDualState()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Use useDualState('start_date', 'end_date') to store start and end dates in separate Livewire properties. Declare the properties as public ?string in your Livewire component.

```php
DateRangePicker::make('date_range')
    ->useDualState('start_date', 'end_date');
```

```php
// In your Livewire component:
public ?string $start_date = null;
public ?string $end_date = null;
```

--------------------------------

### setUp lifecycle hook

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangePicker.md

Protected lifecycle method that registers a default value and an afterStateHydrated hook. The hook forces the default into state on edit operations when enforceIfNull is true and state is null.

```php
protected function setUp(): void
{
    parent::setUp();
    $this->default(fn () => $this->buildDefaultValue());
    $this->afterStateHydrated(function (string $operation) {
        if ($this->enforceIfNull && $operation === 'edit' && $this->getState() === null) {
            $default = $this->buildDefaultValue();
            if ($default !== null) {
                $this->state($default);
            }
        }
    });
}
```

--------------------------------

### DateRangeFilter::make(string $name)

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangeFilter.md

Creates a new DateRangeFilter instance bound to a column with the given name. The constructor calls setUp() which binds the filter to the column and enables the indicator.

```APIDOC
## DateRangeFilter::make(string $name)

### Description
Creates a new DateRangeFilter instance. The filter is automatically bound to a column with the same name as the filter, and an indicator is enabled by default.

### Method
Constructor

### Parameters
- **name** (string) - Required - The column name to bind the filter to.

### Returns
A new DateRangeFilter instance.

### Example
php
$filter = DateRangeFilter::make('created_at');

```

--------------------------------

### useDualState

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Stores start and end dates in two separate Livewire properties instead of a single state string.

```APIDOC
## useDualState

### Description
Store start/end in two separate Livewire properties instead of one `"start - end"` state string. Field-name only; the component itself still syncs the single state string.

### Method
`useDualState(string $startField, string $endField): static`

### Parameters
- **$startField** (string) - Required - The Livewire property name for the start date.
- **$endField** (string) - Required - The Livewire property name for the end date.

### Returns
`static` - The current instance for chaining.
```

--------------------------------

### getStartDate() / getEndDate()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangePicker.md

Returns the resolved start and end dates for the range.

```APIDOC
## getStartDate() / getEndDate()

### Description
Returns the evaluated start date and end date values, which can be CarbonInterface, string, or null.

### Method
- (not applicable - this is a PHP method)

### Parameters
None

### Return Value
- **CarbonInterface|string|Closure|null** - The resolved date value.

### Example
```php
$start = $field->getStartDate();
$end = $field->getEndDate();
```
```

--------------------------------

### Define predefined ranges with ranges()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Defines preset date ranges shown in the picker. Keys are labels, values are arrays with start and end Carbon instances.

```php
DateRangePicker::make('created_at')
    ->ranges([
        'Today' => [now(), now()],
        'This Week' => [now()->startOfWeek(), now()->endOfWeek()],
        'Last 30 Days' => [now()->subDays(30), now()],
    ])
```

--------------------------------

### Month Picker Range Input with Separator

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Configures month picker mode for range input using the configured separator. The example input shows the expected format '06/2026 - 08/2026'.

```php
DateRangePicker::make('billing_period')
    ->monthPicker()
    ->allowInput()
    ->format('m/Y');
```

```text
06/2026 - 08/2026
```

--------------------------------

### isDualState(): bool

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Returns whether dual state is enabled (both dual start and end fields are set).

```APIDOC
## isDualState(): bool

### Description
`return $this->dualStartField !== null && $this->dualEndField !== null;`

### Method
Getter method

### Returns
- **bool** - Whether dual state is enabled.

### Source
`src/Concerns/HasRangePicker.php:610`
```

--------------------------------

### Set display format with format()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Sets the display format using PHP Carbon date tokens. The JavaScript format is auto-converted. Examples show DD/MM/YYYY, YYYY-MM-DD, and DD MMM YYYY.

```php
DateRangePicker::make('created_at')
    ->format('d/m/Y')      // Renders as DD/MM/YYYY in the browser

DateRangePicker::make('created_at')
    ->format('Y-m-d')      // Renders as YYYY-MM-DD in the browser

DateRangePicker::make('created_at')
    ->format('d M Y')      // Renders as DD MMM YYYY in the browser
```

--------------------------------

### Timezone contract: display vs storage zone

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Shows how to set the display timezone and optionally override the storage timezone. The first example uses the default storage timezone, while the second specifies both display and storage zones for columns stored in UTC.

```php
// Column stored in app.timezone (the normal case): no override needed.
DateRangePicker::make('created_at')->timezone('Asia/Riyadh');

// Column stored in UTC while the panel displays local time elsewhere:
DateRangePicker::make('created_at')
    ->timezone('Asia/Riyadh')   // what the user sees / types
    ->systemTimezone('UTC');    // what the column contains
```

--------------------------------

### Basic DateRangePicker field in Filament schema

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangePicker.md

Creates a DateRangePicker field for 'created_at' with a custom label, date format, and a default range of the last 7 days. Use this as a starting point for adding a date range filter to a Filament schema.

```php
use Malzariey\FilamentDaterangepickerFilter\Fields\DateRangePicker;

Schema::make()->schema([
    DateRangePicker::make('created_at')
        ->label('Created')
        ->format('d/m/Y')
        ->defaultLast7Days(),
]);
```

--------------------------------

### buildDefaultValue method

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangePicker.md

Protected method that builds the default range string. Returns null when both start and end dates are unset; otherwise returns '{start}{separator}{end}', using a single configured date for both sides.

```php
protected function buildDefaultValue(): ?string
{
    $startDate = $this->getStartDate();
    $endDate = $this->getEndDate();

    if ($startDate === null && $endDate === null) {
        return null;
    }

    $format = $this->getFormat();
    $separator = $this->getRangeSeparator();
    $start = ($startDate ?? $endDate)->format($format);
    $end = ($endDate ?? $startDate)->format($format);

    return $start . $separator . $end;
}
```

--------------------------------

### Deploy step: php artisan filament:assets

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/FilamentDaterangepickerFilterServiceProvider.md

Run this command as a deploy step required by the provider, as noted in CLAUDE.md, to publish the assets.

```bash
# Deploy step required by this provider (from CLAUDE.md):
php artisan filament:assets
```

--------------------------------

### defaultCustom

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Sets the default range to custom start and end dates.

```APIDOC
## defaultCustom

### Description
Sets the default range to custom start and end dates.

### Method
static

### Signature
`defaultCustom(CarbonInterface|string $start, CarbonInterface|string $end, $enforceIfNull = false): static`

### Parameters
- **$start** (CarbonInterface|string) - Required - The start date of the range.
- **$end** (CarbonInterface|string) - Required - The end date of the range.
- **$enforceIfNull** (bool) - Optional - If true, enforces the default even if a value is null.

### Behavior
- start = the provided start value
- end = the provided end value

### Return Value
static - Returns the component instance for chaining.
```

--------------------------------

### Publish translations

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Run this command to publish the translation files for the package.

```bash
php artisan vendor:publish --tag="filament-daterangepicker-filter-translations"
```

--------------------------------

### rangeSeparator

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Sets the string separating start and end in the state string.

```APIDOC
## rangeSeparator

### Description
Sets the string separating start and end in the state string.

### Method
rangeSeparator

### Signature
`rangeSeparator(string $separator): static`

### Parameters
- **$separator** (string) - Required - String separating start and end in the state string.

### Returns
`static` - The consuming class for chaining.

### Default
`' - '`
```

--------------------------------

### getOpens(): string / getDrops(): string

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangePicker.md

Returns the opening and dropping behavior of the date range picker.

```APIDOC
## getOpens(): string / getDrops(): string

### Description
Returns the resolved enum value for the 'opens' and 'drops' properties. getOpens returns 'left', 'right', or 'center'; getDrops returns 'up', 'down', or 'auto'.

### Method
- (not applicable - this is a PHP method)

### Parameters
None

### Return Value
- **string** - The enum value.

### Example
```php
$opens = $field->getOpens(); // 'left'|'right'|'center'
$drops = $field->getDrops(); // 'up'|'down'|'auto'
```
```

--------------------------------

### configurePackage method: package name, views, and translations

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/FilamentDaterangepickerFilterServiceProvider.md

Configures the package with the name 'filament-daterangepicker-filter', registers Blade views, and enables translations. The view namespace resolves to resources/views/ and translations are published via the tag 'filament-daterangepicker-filter-translations'.

```php
$package->name(static::$name)->hasViews()->hasTranslations();
```

--------------------------------

### defaultYesterday

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Sets the default range to yesterday, from start of day to end of day.

```APIDOC
## defaultYesterday

### Description
Sets the default range to yesterday, from start of day to end of day.

### Method
static

### Signature
`defaultYesterday($enforceIfNull = false): static`

### Parameters
- **$enforceIfNull** (bool) - Optional - If true, enforces the default even if a value is null.

### Behavior
- start = `now()->subDay()`
- end = `now()->subDay()`

### Return Value
static - Returns the component instance for chaining.
```

--------------------------------

### defaultToday

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Sets the default range to today, from start of day to end of day.

```APIDOC
## defaultToday

### Description
Sets the default range to today, from start of day to end of day.

### Method
static

### Signature
`defaultToday($enforceIfNull = false): static`

### Parameters
- **$enforceIfNull** (bool) - Optional - If true, enforces the default even if a value is null.

### Behavior
- start = `now()->startOfDay()`
- end = `now()->endOfDay()`

### Return Value
static - Returns the component instance for chaining.
```

--------------------------------

### defaultLastYear

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Sets the default range to the previous year, from start of that year to end of that year.

```APIDOC
## defaultLastYear

### Description
Sets the default range to the previous year, from start of that year to end of that year.

### Method
static

### Signature
`defaultLastYear($enforceIfNull = false): static`

### Parameters
- **$enforceIfNull** (bool) - Optional - If true, enforces the default even if a value is null.

### Behavior
- start = `now()->subYear()->startOfYear()`
- end = `now()->subYear()->endOfYear()`

### Return Value
static - Returns the component instance for chaining.
```

--------------------------------

### defaultThisYear

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Sets the default range to the current year, from start of year to end of year.

```APIDOC
## defaultThisYear

### Description
Sets the default range to the current year, from start of year to end of year.

### Method
static

### Signature
`defaultThisYear($enforceIfNull = false): static`

### Parameters
- **$enforceIfNull** (bool) - Optional - If true, enforces the default even if a value is null.

### Behavior
- start = `now()->startOfYear()`
- end = `now()->endOfYear()`

### Return Value
static - Returns the component instance for chaining.
```

--------------------------------

### defaultLastMonth

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Sets the default range to the previous month, from start of that month to end of that month.

```APIDOC
## defaultLastMonth

### Description
Sets the default range to the previous month, from start of that month to end of that month.

### Method
static

### Signature
`defaultLastMonth($enforceIfNull = false): static`

### Parameters
- **$enforceIfNull** (bool) - Optional - If true, enforces the default even if a value is null.

### Behavior
- start = `now()->subMonthNoOverflow()->startOfMonth()`
- end = `now()->subMonthNoOverflow()->endOfMonth()`

### Return Value
static - Returns the component instance for chaining.
```

--------------------------------

### Set drop and open directions with drops() and opens()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Controls the drop and open directions of the picker. Requires importing DropDirection and OpenDirection enums.

```php
use Malzariey\FilamentDaterangepickerFilter\Enums\DropDirection;
use Malzariey\FilamentDaterangepickerFilter\Enums\OpenDirection;

DateRangePicker::make('created_at')
    ->drops(DropDirection::UP)
    ->opens(OpenDirection::CENTER)
```

--------------------------------

### Month Picker with Year and Date Constraints

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Configures month picker mode with min/max year and min/max date constraints. Respects minYear(), maxYear(), minDate(), and maxDate() for year options and disabled months.

```php
DateRangePicker::make('billing_period')
    ->monthPicker()
    ->format('m/Y')
    ->minYear(2020)
    ->maxYear(2030)
    ->minDate('2020-06-01')
    ->maxDate('2030-12-31');
```

--------------------------------

### defaultThisMonth

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Sets the default range to the current month, from start of month to end of month.

```APIDOC
## defaultThisMonth

### Description
Sets the default range to the current month, from start of month to end of month.

### Method
static

### Signature
`defaultThisMonth($enforceIfNull = false): static`

### Parameters
- **$enforceIfNull** (bool) - Optional - If true, enforces the default even if a value is null.

### Behavior
- start = `now()->startOfMonth()`
- end = `now()->endOfMonth()`

### Return Value
static - Returns the component instance for chaining.
```

--------------------------------

### Run Asset Watcher

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/CONTRIBUTING.md

Runs the asset watcher in the first terminal to rebuild CSS and JS on save.

```bash
npm run dev
```

--------------------------------

### Edge-case handling: firstDayOfWeek fallback, presets-only, and state string

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangePicker.md

Shows error-avoidance patterns: out-of-range firstDayOfWeek values are silently corrected, a presets-only field with disableCustomRange and disableClear, and the state string format that Livewire receives. Includes comments explaining each behavior.

```php
// Out-of-range first day is silently corrected (0-7; both accepted here):
DateRangePicker::make('event_date')
    ->firstDayOfWeek(9)      // falls back to config default
    ->firstDayOfWeek(1);     // Monday

// Presets-only field: calendar hidden until a preset is chosen.
DateRangePicker::make('period')
    ->disableCustomRange()
    ->ranges(['This Month' => [now()->startOfMonth(), now()->endOfMonth()]])
    ->disableClear();

// The state string that Livewire receives is "{start}{separator}{end}";
// buildDefaultValue()/getRanges() are the authoritative builders.
DateRangePicker::make('created_at')
    ->format('d/m/Y')
    ->defaultToday()   // state -> "{today's date} - {today's date}" (display timezone)
```

--------------------------------

### Set first day of week with firstDayOfWeek()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Sets the first day of the week. 1 = Monday, 0 = Sunday.

```php
DateRangePicker::make('created_at')->firstDayOfWeek(1) // Monday
```

--------------------------------

### getAllowInput(): bool

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Returns whether input is allowed.

```APIDOC
## getAllowInput(): bool

### Description
`return $this->evaluate($this->allowInput);`

### Method
Getter method

### Returns
- **bool** - Whether input is allowed.

### Source
`src/Concerns/HasRangePicker.php:594`
```

--------------------------------

### Show month/year dropdowns with showDropdowns()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Shows month and year dropdowns in the day picker header. Use minYear() and maxYear() to constrain the year dropdown.

```php
DateRangePicker::make('created_at')
    ->showDropdowns()
    ->minYear(2000)
    ->maxYear(2030)
```

--------------------------------

### hiddenLabel(bool|Closure $condition = true): static

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangeFilter.md

Sets whether the label is hidden. The generated field gets the hiddenLabel condition applied.

```APIDOC
## hiddenLabel(bool|Closure $condition = true): static

### Description
Sets whether the label is hidden. The generated field gets the hiddenLabel condition applied.

### Method
hiddenLabel

### Parameters
- **condition** (bool|Closure) - Optional - Default: true - Whether to hide the label.

### Returns
static - The filter instance for chaining.

### Example
php
$filter->hiddenLabel();

```

--------------------------------

### setAutoApplyOption (Deprecated)

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Deprecated since 2.5.1. Use autoApply() instead.

```APIDOC
## setAutoApplyOption (Deprecated)

### Description
Deprecated since 2.5.1. Use `autoApply()` instead.

### Method
setAutoApplyOption

### Signature
`setAutoApplyOption(bool $condition = true): static`

### Parameters
- **$condition** (bool) - Optional - Whether to auto-apply. Defaults to `true`.

### Returns
`static` - The consuming class for chaining.

### Default
—
```

--------------------------------

### withIndicator() method

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangeFilter.md

Registers an indicateUsing callback that returns a localized period string or null when no value is set. Enabled by default via setUp().

```php
public function withIndicator(): self
{
    $this->indicateUsing(function (array $data): ?string {
        $datesString = data_get($data, $this->column);
        if (empty($datesString)) {
            return null;
        }
        return __('filament-daterangepicker-filter::message.period', [
            'label' => $this->getLabel(),
            'column' => $this->column,
            'period' => $datesString
        ]);
    });
    return $this;
}
```

--------------------------------

### DateRangePicker::make constructor

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangePicker.md

Static constructor inherited from Filament's Field base class. The name parameter is required and serves as the field/column name, Livewire state path, and Alpine component name.

```php
DateRangePicker::make(string $name)
```

--------------------------------

### Import DateRangeFilter

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangeFilter.md

Import statement for the DateRangeFilter class.

```php
use Malzariey\FilamentDaterangepickerFilter\Filters\DateRangeFilter;
```

--------------------------------

### Range state string format

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/types.md

String format for the stored value: {start} {separator} {end}. Separator defaults to ' - ', start/end use display format, single date when singleCalendar is enabled.

```text
{start} {separator} {end}
```

--------------------------------

### Run PHP Tests

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/CONTRIBUTING.md

Runs the PHP test suite using Pest.

```bash
composer test
# or:
vendor/bin/pest
```

--------------------------------

### allowInput

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Enables keyboard date entry with mask/format validation.

```APIDOC
## allowInput

### Description
Enable keyboard date entry with mask/format validation.

### Method
`allowInput(bool|Closure $condition = true): static`

### Parameters
- **$condition** (bool|Closure) - Optional - Default: `false` - When true, enables keyboard input.

### Returns
`static` - The current instance for chaining.
```

--------------------------------

### autoApply

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Applies the selection immediately when the range is complete (no Apply button).

```APIDOC
## autoApply

### Description
Applies the selection immediately when the range is complete (no Apply button).

### Method
autoApply

### Signature
`autoApply(bool|Closure $condition = true): static`

### Parameters
- **$condition** (bool|Closure) - Optional - Whether to auto-apply. Defaults to `true`.

### Returns
`static` - The consuming class for chaining.

### Default
`false`
```

--------------------------------

### Set min and max dates with minDate() and maxDate()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Restricts selectable dates to a range. Use Carbon instances to define the boundaries.

```php
DateRangePicker::make('created_at')
    ->minDate(Carbon::now()->subMonth())
    ->maxDate(Carbon::now()->addMonth())
```

--------------------------------

### Custom Query with DateRangeFilter

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Use this snippet to customize the filter's query behavior. It applies a whereBetween clause on the 'created_at' column when a date string is present, using the provided start and end dates.

```php
use Malzariey\FilamentDaterangepickerFilter\Filters\DateRangeFilter;

DateRangeFilter::make('created_at')
    ->modifyQueryUsing(fn(Builder $query, ?Carbon $startDate, ?Carbon $endDate, $dateString) =>
        $query->when(!empty($dateString),
            fn(Builder $query) => $query->whereBetween('created_at', [$startDate, $endDate])
        )
    )
```

--------------------------------

### Basic fluent configuration for DateRangePicker

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Configures a DateRangePicker field with format, time picker options, min/max dates, default last 7 days, and custom ranges. The same builder pattern applies to the filter.

```php
use Malzariey\FilamentDaterangepickerFilter\Fields\DateRangePicker;

DateRangePicker::make('created_at')
    ->format('d/m/Y')
    ->timePicker()
    ->timePicker24()
    ->minDate(Carbon::now()->subMonth())
    ->maxDate(Carbon::now()->addMonth())
    ->defaultLast7Days()
    ->ranges([
        'Today' => [now(), now()],
        'Last 30 Days' => [now()->subDays(29), now()],
    ]);
```

--------------------------------

### FilamentDaterangepickerFilterServiceProvider class implementation

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/FilamentDaterangepickerFilterServiceProvider.md

The service provider extends PackageServiceProvider, sets the package name, registers views and translations, and registers an Alpine component and CSS asset with FilamentAsset. The facade referenced in composer.json does not exist in the source tree.

```php
<?php

namespace Malzariey\FilamentDaterangepickerFilter;

use Composer\InstalledVersions;
use Filament\Support\Assets\AlpineComponent;
use Filament\Support\Assets\Css;
use Filament\Support\Assets\Js;
use Filament\Support\Facades\FilamentAsset;
use Spatie\LaravelPackageTools\Package;
use Spatie\LaravelPackageTools\PackageServiceProvider;

class FilamentDaterangepickerFilterServiceProvider extends PackageServiceProvider
{
    public static string $name = 'filament-daterangepicker-filter';
    private static string $version = 'dev';

    public function configurePackage(Package $package): void
    {
        $package->name(static::$name)
            ->hasViews()
            ->hasTranslations();
    }

    public function packageRegistered(): void
    {
        $assets = [
            AlpineComponent::make('dateRangeComponent', __DIR__ . '/../dist/filament-daterangepicker.js'),
            Css::make('date-range-picker', __DIR__ . '/../dist/filament-daterangepicker.css'),
        ];

        FilamentAsset::register($assets, 'malzariey/filament-daterangepicker-filter');
    }
}
```

--------------------------------

### formatToPlaceholder(format)

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/dateRangeComponent-methods.md

Converts a day.js format to a placeholder string.

```APIDOC
## formatToPlaceholder(format)

### Description
Converts a day.js format to a placeholder string.

### Method
formatToPlaceholder

### Parameters
- **format** (string) - Required - The format string.

### Return Value
The placeholder string.
```

--------------------------------

### DateRangeFilter::apply() method source

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangeFilter.md

The apply() method processes the filter state, parses date strings, and applies a whereBetween query when both start and end dates are present. It supports timezone conversion, start/end of day adjustments, and an optional modifyQueryUsing callback that overrides the default behavior.

```php
public function apply(Builder $query, array $data = []): Builder
{
    if ($this->isHidden()) {
        return $query;
    }

    if (!($data['isActive'] ?? true)) {
        return $query;
    }

    $datesString = data_get($data, $this->column);

    if (!empty($datesString)) {
        $dates = explode($this->rangeSeparator, $datesString);
    } else {
        $dates = [];
    }

    if (count($dates) === 2) {
        $from = trim($dates[0]);
        $to = trim($dates[1]);

        if ($this->getTimePicker()) {
            $dates = [
                Carbon::createFromFormat($this->getFormat(), $from, $this->getTimezone())->timezone($this->getSystemTimezone()),
                Carbon::createFromFormat($this->getFormat(), $to, $this->getTimezone())->timezone($this->getSystemTimezone())
            ];
        } else {
            $dates = [
                Carbon::createFromFormat($this->getFormat(), $from, $this->getTimezone())->startOfDay()->timezone($this->getSystemTimezone()),
                Carbon::createFromFormat($this->getFormat(), $to, $this->getTimezone())->endOfDay()->timezone($this->getSystemTimezone()),
            ];
        }
    } else {
        $from = null;
        $to = null;
    }

    if ($this->hasQueryModificationCallback()) {
        $callback = $this->modifyQueryUsing;
        $this->evaluate($callback, [
            'data' => $data,
            'query' => $query,
            'state' => $data,
            'dateString' => $datesString,
            'startDate' => $dates[0] ?? null,
            'endDate' => $dates[1] ?? null,
        ]);
        return $query;
    }

    if (empty($dates)) {
        return $query;
    }

    return $query
        ->when(
            $from !== null && $to !== null,
            fn(Builder $query, $date): Builder => $query->whereBetween($this->column, $dates),
        );
}
```

--------------------------------

### format

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Sets the display format with PHP Carbon tokens; auto-converts to Day.js. $enforceFormat prevents time tokens from being appended automatically.

```APIDOC
## format

### Description
Sets the display format with PHP Carbon tokens; auto-converts to Day.js. `$enforceFormat` prevents time tokens from being appended automatically.

### Method
format

### Signature
`format(string|Closure|null $format, bool $enforceFormat = false): static`

### Parameters
- **$format** (string|Closure|null) - Required - Display format with PHP Carbon tokens.
- **$enforceFormat** (bool) - Optional - Whether to enforce the format. Defaults to `false`.

### Returns
`static` - The consuming class for chaining.

### Default
`'d/m/Y'`
```

--------------------------------

### applySelection()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/dateRangeComponent-methods.md

Syncs state, dispatches the 'apply.daterangepicker' event with the current selection, and closes the picker.

```APIDOC
## applySelection()

### Description
Syncs state, dispatches the `apply.daterangepicker` event with the current selection, and closes the picker.

### Method
applySelection

### Parameters
None

### Return Value
undefined
```

--------------------------------

### getDisplayFormat(): string

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Returns the display format. If displayFormat was set (deprecated path), returns it verbatim. Otherwise returns the JavaScript-converted format from getFormat().

```APIDOC
## getDisplayFormat(): string

### Description
If `displayFormat` was set (deprecated path), returns it verbatim. Otherwise returns `convertPhpToJsFormat($this->getFormat())` — the PHP-token format already has time tokens appended, so they carry into the JS string (e.g. `d/m/Y` → `DD/MM/YYYY`).

### Method
Getter method

### Returns
- **string** - The display format string.

### Source
`src/Concerns/HasRangePicker.php:519-530`
```

--------------------------------

### minDate

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Sets the earliest selectable date.

```APIDOC
## minDate

### Description
Sets the earliest selectable date.

### Method
minDate

### Signature
`minDate(CarbonInterface|string|Closure|null $date): static`

### Parameters
- **$date** (CarbonInterface|string|Closure|null) - Required - Earliest selectable date.

### Returns
`static` - The consuming class for chaining.

### Default
`null`
```

--------------------------------

### PHP Fluent API Configuration Methods

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/configuration.md

Chainable methods for configuring the date range picker field or filter. Each method returns the receiver for chaining.

```APIDOC
## PHP Fluent API Configuration Methods

### Description
These chainable methods configure the date range picker field or filter. Each method returns the receiver for chaining.

### Methods

#### icon
- **Signature**: `icon(string|Closure|null $icon = null)`
- **Default**: `null` (renders `heroicon-m-calendar-days`)
- **Description**: Field icon.

#### format
- **Signature**: `format(string|Closure|null $format, bool $enforceFormat = false)`
- **Default**: `'d/m/Y'`
- **Description**: Display format, PHP Carbon tokens — auto-converted to Day.js. `enforceFormat` prevents time-token appending (see `getFormat()`).

#### displayFormat
- **Signature**: `displayFormat(string|Closure|null $format , bool $enforceFormat = false)`
- **Default**: `null`
- **Description**: **Deprecated 2.5.1** — raw Day.js format, used verbatim when set.

#### startDate
- **Signature**: `startDate(CarbonInterface|string|Closure|null $date, $enforceIfNull = false)`
- **Default**: `null`
- **Description**: Default start; `enforceIfNull` forces on edit when null.

#### endDate
- **Signature**: `endDate(CarbonInterface|string|Closure|null $date, $enforceIfNull = false)`
- **Default**: `null`
- **Description**: Default end.

#### minDate
- **Signature**: `minDate(CarbonInterface|string|Closure|null $date)`
- **Default**: `null`
- **Description**: Earliest selectable.

#### maxDate
- **Signature**: `maxDate(CarbonInterface|string|Closure|null $date)`
- **Default**: `null`
- **Description**: Latest selectable.

#### firstDayOfWeek
- **Signature**: field: `firstDayOfWeek(int|null $day)`; filter: `firstDayOfWeek(int|Closure $day)`
- **Default**: `1` (resolves `config('forms.components.date_time_picker.first_day_of_week', 1)`)
- **Description**: First weekday; field clamps `< 0` or `> 7` to the default.

#### timezone
- **Signature**: `timezone(string|Closure|null $timezone)`
- **Default**: `null` → `FilamentTimezone::get()`
- **Description**: Display timezone.

#### systemTimezone
- **Signature**: `systemTimezone(string|Closure|null $timezone)`
- **Default**: `null` → `config('app.timezone')`
- **Description**: Storage/column timezone.

#### timePicker
- **Signature**: `timePicker(bool|Closure $condition = true)`
- **Default**: `false`
- **Description**: Show time selects.

#### timePicker24
- **Signature**: `timePicker24(bool|Closure $condition = true)`
- **Default**: `false`
- **Description**: 24h format (JS default `true`; Blade always passes this PHP value).

#### timePickerSecond
- **Signature**: `timePickerSecond(bool|Closure $condition = true)`
- **Default**: `false`
- **Description**: Seconds select.

#### timePickerIncrement
- **Signature**: `timePickerIncrement(int|Closure $increment = 1)`
- **Default**: `30`
- **Description**: Minute-step of the minutes select.

#### autoApply
- **Signature**: `autoApply(bool|Closure $condition = true)`
- **Default**: `false`
- **Description**: Apply when the range completes.

#### linkedCalendars
- **Signature**: `linkedCalendars(bool|Closure $condition = true)`
- **Default**: `true`
- **Description**: Consecutive-month calendars.

#### singleCalendar
- **Signature**: `singleCalendar(bool|Closure $condition = true)` (field only)
- **Default**: `false`
- **Description**: Single calendar / single-date.

#### alwaysShowCalendar
- **Signature**: `alwaysShowCalendar(bool|Closure $alwaysShow = true)`
- **Default**: `true`
- **Description**: Calendar permanently visible; `disableCustomRange()` forces `false`.

#### showDropdowns
- **Signature**: `showDropdowns(bool|Closure $condition = true)`
- **Default**: `false`
- **Description**: Month/year dropdowns in day-picker header.

#### showWeekNumbers
- **Signature**: `showWeekNumbers(bool|Closure $condition = true)`
- **Default**: `false`
- **Description**: Localized week numbers.

#### showISOWeekNumbers
- **Signature**: `showISOWeekNumbers(bool|Closure $condition = true)`
- **Default**: `false`
- **Description**: ISO week numbers.

#### minYear
- **Signature**: `minYear(int|Closure|null $condition = null)`
- **Default**: `null`
- **Description**: Lower year bound.

#### maxYear
- **Signature**: `maxYear(int|Closure|null $condition = null)`
- **Default**: `null`
- **Description**: Upper year bound.

#### disabledDates
- **Signature**: `disabledDates(array|Closure $dates)`
- **Default**: `[]`
- **Description**: Unselectable dates.

#### maxSpan
- **Signature**: `maxSpan(array|Closure|null $maxSpan)`
- **Default**: `null`
- **Description**: Max range: `['days'|'months'|'years' => int]`.

#### ranges
- **Signature**: `ranges(null|array|Closure $ranges)`
- **Default**: `null` (field builds 8 localized defaults)
- **Description**: Presets `[label => [start, end]]`.

#### useRangeLabels
- **Signature**: `useRangeLabels(bool $useRangeLabels = true)`
- **Default**: `false`
- **Description**: Show the matching preset label instead of dates.

#### disableCustomRange
- **Signature**: `disableCustomRange(bool|Closure $d = true)`
- **Default**: `false`
- **Description**: Presets only.

#### disableRanges
- **Signature**: `disableRanges(bool|Closure $d = true)`
- **Default**: `false`
- **Description**: Hide the preset sidebar.

#### rangeSeparator
- **Signature**: `rangeSeparator(string $separator)`
- **Default**: `' - '`
- **Description**: Separator in the state string.

#### opens
- **Signature**: `opens(OpenDirection|Closure $direction)`
- **Default**: `OpenDirection::LEFT`
- **Description**: Horizontal alignment.

#### drops
- **Signature**: `drops(DropDirection|Closure $direction)`
- **Default**: `DropDirection::DOWN`
- **Description**: Vertical drop.

#### teleport
- **Signature**: `teleport(bool|Closure $condition = true)`
- **Default**: `true`
- **Description**: Teleport dropdown to `<body>`.

#### allowInput
- **Signature**: `allowInput(bool|Closure $condition = true)`
- **Default**: `false`
- **Description**: Masked keyboard entry.
```

--------------------------------

### Enable time picker with timePicker()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Enables time selection. Use timePicker24() for 24-hour format, timePickerSecond() to show seconds, and timePickerIncrement(30) to set minute increments.

```php
DateRangePicker::make('created_at')
    ->timePicker()
    ->timePicker24()       // Use 24-hour format
    ->timePickerSecond()   // Show seconds
    ->timePickerIncrement(30) // 30-minute increments
```

--------------------------------

### Listening for apply with formatted output

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/dateRangeComponent.md

Use this event listener to react when the user applies a date range. The event detail provides startDate and endDate as dayjs objects and formattedValue as a string in the display format.

```javascript
document.addEventListener('apply.daterangepicker', (e) => {
    console.log(e.detail.startDate);       // dayjs object
    console.log(e.detail.endDate);         // dayjs object
    console.log(e.detail.formattedValue);  // '01/06/2026 - 31/08/2026'
});
```

--------------------------------

### getRanges(): ?array

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/DateRangePicker.md

Returns the list of preset ranges, or default localized presets if none set.

```APIDOC
## getRanges(): ?array

### Description
Returns the evaluated ranges. If disableRanges is on, returns []. If empty, builds default localized presets (today, yesterday, last 7 days, etc.).

### Method
- (not applicable - this is a PHP method)

### Parameters
None

### Return Value
- **?array** - Associative array of range labels to date pairs, or null if not set.

### Example
```php
$ranges = $field->getRanges();
```
```

--------------------------------

### Auto apply selection with autoApply()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Automatically applies the selected date range without requiring a button click.

```php
DateRangePicker::make('created_at')->autoApply()
```

--------------------------------

### Livewire listener for apply.daterangepicker event

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/dateRangeComponent-methods.md

Listens for the 'apply.daterangepicker' event in a Livewire context. The event detail provides startDate and endDate as dayjs instances and formattedValue as the sync string. Commented-out lines show programmatic open/apply methods (toggleSelection, apply, clear).

```javascript
// In a Livewire listener:
document.addEventListener('apply.daterangepicker', (e) => {
    const { startDate, endDate, formattedValue } = e.detail;
    // startDate/endDate are dayjs instances; formattedValue is the sync string
});

// Programmatic open/apply from Alpine:
// component.toggleSelection();
// component.apply();
// component.clear();
```

--------------------------------

### generateGrid(monthOffset = 0)

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/dateRangeComponent-methods.md

Generates a month grid with weeks and day cells.

```APIDOC
## generateGrid(monthOffset = 0)

### Description
Generates a month grid with weeks and day cells.

### Method
generateGrid

### Parameters
- **monthOffset** (number) - Optional - Offset to add to the current month.

### Return Value
An object with properties: month, monthName, year, weeks.
```

--------------------------------

### Show week numbers with showWeekNumbers() and showISOWeekNumbers()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/README.md

Displays localized or ISO week numbers in the calendar.

```php
DateRangePicker::make('created_at')
    ->showWeekNumbers()     // Localized week numbers
    ->showISOWeekNumbers()  // ISO week numbers
```

--------------------------------

### createDayObject(date, currentMonth)

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/dateRangeComponent-methods.md

Builds a day grid cell object with selection, range, and disabled flags.

```APIDOC
## createDayObject(date, currentMonth)

### Description
Builds a day grid cell object with selection, range, and disabled flags.

### Method
createDayObject

### Parameters
- **date** (dayjs) - Required - The date for the cell.
- **currentMonth** (boolean) - Required - Whether the date is in the current month.

### Return Value
An object with properties: date, day, isCurrentMonth, isToday, isSelected, inRange, isStart, isEnd, isHovered, disabled, weekNumber, dateString.
```

--------------------------------

### getFormat(): string

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Returns the resolved display format. If enforceFormat is off and the time picker is on, appends time tokens based on 24h and seconds settings.

```APIDOC
## getFormat(): string

### Description
Returns the resolved display format. If `enforceFormat` is **off** and the time picker is on, appends time tokens: `' H:i:s'`/`' H:i'` when 24h, else `' h:i:s A'`/`' h:i A'`, each conditioned on `timePickerSecond()`.

### Method
Getter method

### Returns
- **string** - The resolved display format.

### Source
`src/Concerns/HasRangePicker.php:108-121`
```

--------------------------------

### createDateMaskOptions(format)

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/dateRangeComponent-methods.md

Creates IMask date mask options for day pickers.

```APIDOC
## createDateMaskOptions(format)

### Description
Creates IMask date mask options for day pickers.

### Method
createDateMaskOptions

### Parameters
- **format** (string) - Required - The date format pattern.

### Return Value
Mask options object for IMask.
```

--------------------------------

### monthPicker

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/HasRangePicker.md

Shorthand for pickerType(PickerType::MONTH).

```APIDOC
## monthPicker

### Description
Shorthand for `pickerType(PickerType::MONTH)`.

### Method
`monthPicker(): static`

### Parameters
None.

### Returns
`static` - The current instance for chaining.
```

--------------------------------

### clear()

Source: https://github.com/malzariey/filament-daterangepicker-filter/blob/x5/_autodocs/api-reference/dateRangeComponent-methods.md

Clears the current selection, syncs state, and closes the picker.

```APIDOC
## clear()

### Description
Clears the current selection, syncs state, and closes the picker.

### Method
clear

### Parameters
None

### Return Value
undefined
```
Tokens:
Raw