DateFieldType
extends AbstractFieldType
in package
The "date" additional checkout field type.
Values are calendar dates in YYYY-MM-DD format with no time or timezone component. Field also accept min/max constraints as absolute dates (i.e. YYYY-MM-DD) or relative ISO 8601-2 periods (e.g. -P2Y, P1M).
Table of Contents
- DATE_PATTERN = '\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])'
- Matches a YYYY-MM-DD date with valid month and day ranges.
- default_validate() : WP_Error|void
- The validate_callback a field gets when it does not declare its own: rejects empty required fields.
- format_value() : mixed
- Formats a stored YYYY-MM-DD date using the store's date format.
- from_storage() : mixed
- Converts a stored meta value into the type the rest of checkout works with.
- prepare_form_field() : array<string|int, mixed>
- Adds the resolved min/max constraints as input attributes for woocommerce_form_field().
- prepare_validation_schema() : array<string|int, mixed>
- Defaults date comparison schemas to date strings without replacing supplied keywords.
- prepare_value_schema() : array<string|int, mixed>
- Applies type-specific keywords to a field's REST API value schema.
- process_options() : array<string|int, mixed>|false
- Processes and validates the options supplied during field registration.
- sanitize() : mixed
- Trims whitespace from submitted date values before they are validated and stored.
- validate() : WP_Error|null
- Validates that a submitted value is a real calendar date within the field's min/max constraints.
- validate_options() : bool
- Validates the options that apply to every field type: callbacks, hidden state, and rule schemas.
- doing_it_wrong() : false
- Reports a field registration misuse that does not prevent the field from being registered.
- process_attributes() : array<string|int, mixed>
- Processes the attributes supplied during field registration.
- process_type_options() : array<string|int, mixed>|false
- Processes the options for a date field and returns the new field_options array.
- registration_error() : false
- Reports a field registration error and prevents the field from being registered.
- get_constraints() : array<string|int, mixed>
- Returns the resolved min and max dates for a date field.
- is_absolute_date() : bool
- Returns true if the given value is a date in YYYY-MM-DD format.
- parse_date() : DateTimeImmutable|null
- Parses a YYYY-MM-DD date in the store's timezone.
- parse_duration() : DateInterval
- Parses a duration without losing weeks on PHP 7.
- resolve_constraint() : string
- Resolves a date field min/max constraint to a YYYY-MM-DD date in the store's timezone.
Constants
DATE_PATTERN
Matches a YYYY-MM-DD date with valid month and day ranges.
private
mixed
DATE_PATTERN
= '\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])'
Undelimited because a JSON Schema pattern takes a bare expression; the PHP uses add delimiters.
Methods
default_validate()
The validate_callback a field gets when it does not declare its own: rejects empty required fields.
public
default_validate(mixed $value, array<string|int, mixed> $field) : WP_Error|void
Unlike validate(), a field's validate_callback can be replaced at registration, so nothing here is mandatory for the type.
Parameters
- $value : mixed
-
The submitted value.
- $field : array<string|int, mixed>
-
The field.
Return values
WP_Error|void — An error if the value is invalid.format_value()
Formats a stored YYYY-MM-DD date using the store's date format.
public
format_value(mixed $value, array<string|int, mixed> $field) : mixed
Parameters
- $value : mixed
-
The stored value.
- $field : array<string|int, mixed>
-
The field.
Return values
mixed — The formatted date, or the value unchanged if it could not be parsed.from_storage()
Converts a stored meta value into the type the rest of checkout works with.
public
from_storage(mixed $value) : mixed
Parameters
- $value : mixed
-
The stored value.
Tags
Return values
mixed — The converted value.prepare_form_field()
Adds the resolved min/max constraints as input attributes for woocommerce_form_field().
public
prepare_form_field(array<string|int, mixed> $form_field) : array<string|int, mixed>
These forms are rendered server side, so the constraints are resolved here rather than by the client.
Parameters
- $form_field : array<string|int, mixed>
-
The woocommerce_form_field() arguments built from the field.
Return values
array<string|int, mixed> — The updated arguments.prepare_validation_schema()
Defaults date comparison schemas to date strings without replacing supplied keywords.
public
prepare_validation_schema(array<string|int, mixed> $schema) : array<string|int, mixed>
Parameters
- $schema : array<string|int, mixed>
-
The supplied validation schema.
Tags
Return values
array<string|int, mixed> — The schema with defaults applied.prepare_value_schema()
Applies type-specific keywords to a field's REST API value schema.
public
prepare_value_schema(array<string|int, mixed> $field_schema, array<string|int, mixed> $field) : array<string|int, mixed>
Parameters
- $field_schema : array<string|int, mixed>
-
The schema built for the field so far.
- $field : array<string|int, mixed>
-
The field.
Return values
array<string|int, mixed> — The updated schema.process_options()
Processes and validates the options supplied during field registration.
public
final process_options(array<string|int, mixed> $field_data, array<string|int, mixed> $options) : array<string|int, mixed>|false
Parameters
- $field_data : array<string|int, mixed>
-
The field data array to be updated.
- $options : array<string|int, mixed>
-
The options supplied during field registration.
Return values
array<string|int, mixed>|false — The updated $field_data array, or false if an error should prevent registration.sanitize()
Trims whitespace from submitted date values before they are validated and stored.
public
sanitize(mixed $value, array<string|int, mixed> $field) : mixed
Parameters
- $value : mixed
-
The submitted value.
- $field : array<string|int, mixed>
-
The field.
Return values
mixed — The sanitized value.validate()
Validates that a submitted value is a real calendar date within the field's min/max constraints.
public
validate(mixed $value, array<string|int, mixed> $field) : WP_Error|null
Parameters
- $value : mixed
-
The submitted value.
- $field : array<string|int, mixed>
-
The field.
Return values
WP_Error|null — Error if the value is not valid, null otherwise.validate_options()
Validates the options that apply to every field type: callbacks, hidden state, and rule schemas.
public
validate_options(array<string|int, mixed> $options) : bool
Subclasses adding checks should call this parent method first.
Parameters
- $options : array<string|int, mixed>
-
The options supplied during field registration.
Return values
bool — False if an error should prevent registration, true otherwise.doing_it_wrong()
Reports a field registration misuse that does not prevent the field from being registered.
protected
doing_it_wrong(string $message, string $version) : false
Parameters
- $message : string
-
The message describing the misuse.
- $version : string
-
The version the misuse was introduced in.
Return values
false —process_attributes()
Processes the attributes supplied during field registration.
protected
process_attributes(string $id, mixed $attributes) : array<string|int, mixed>
Invalid attributes are dropped with a warning rather than preventing registration.
Parameters
- $id : string
-
The field ID.
- $attributes : mixed
-
The attributes supplied during field registration.
Return values
array<string|int, mixed> — The processed attributes.process_type_options()
Processes the options for a date field and returns the new field_options array.
protected
process_type_options(array<string|int, mixed> $field_data, array<string|int, mixed> $options) : array<string|int, mixed>|false
Parameters
- $field_data : array<string|int, mixed>
-
The field data array to be updated.
- $options : array<string|int, mixed>
-
The options supplied during field registration.
Return values
array<string|int, mixed>|false — The updated $field_data array, or false if an error was encountered.registration_error()
Reports a field registration error and prevents the field from being registered.
protected
registration_error(string $id, string $reason, string $version) : false
Parameters
- $id : string
-
The ID of the field being registered.
- $reason : string
-
The reason the field cannot be registered.
- $version : string
-
The version the misuse was introduced in.
Return values
false —get_constraints()
Returns the resolved min and max dates for a date field.
private
get_constraints(array<string|int, mixed> $field[, bool $log_invalid_range = false ]) : array<string|int, mixed>
Parameters
- $field : array<string|int, mixed>
-
The field.
- $log_invalid_range : bool = false
-
Whether to log an invalid range during value validation.
Return values
array<string|int, mixed> — Array with "min" and "max" keys, each a YYYY-MM-DD date or null when unconstrained.is_absolute_date()
Returns true if the given value is a date in YYYY-MM-DD format.
private
is_absolute_date(mixed $value) : bool
Parameters
- $value : mixed
-
The value to check.
Return values
bool —parse_date()
Parses a YYYY-MM-DD date in the store's timezone.
private
parse_date(string $value) : DateTimeImmutable|null
Parameters
- $value : string
-
The date to parse.
Return values
DateTimeImmutable|null — The date, or null if it is not a real calendar date.parse_duration()
Parses a duration without losing weeks on PHP 7.
private
static parse_duration(string $duration) : DateInterval
Parameters
- $duration : string
-
The unsigned ISO duration.
Return values
DateInterval — The parsed duration.resolve_constraint()
Resolves a date field min/max constraint to a YYYY-MM-DD date in the store's timezone.
private
resolve_constraint(string $value[, DateTimeInterface|null $reference = null ]) : string
Durations are resolved at read time, so they follow the current date rather than freezing into whatever markup a page cache stored.
We use DateInterval to resolve durations but it has 2 issues that we must solve here:
- Negative constraints are not supported with this version, so we must account for them ourselves.
- DateInterval has an inconsistent behavior compared to ISO 8601-2 in which adding a month to a date equals adding 31 days instead of a calendar month, resulting in P1M after Jan 31 giving you Mar 3 instead of Feb 28.
Parameters
- $value : string
-
The constraint, as validated and normalized at registration.
- $reference : DateTimeInterface|null = null
-
Date a duration is relative to. Defaults to today in the store timezone.