mirror of
https://github.com/Respect/Validation.git
synced 2026-03-18 08:09:51 +01:00
bd48bdcda4
Introduces a Markdown linter for checking the Changelog format. "See Also" was transformed into a section to make it easier to handle it with the `Content` class. The "Related" linter was simplified to reflect that change too. An additional "alignment" parameter was added to markdown table generators, allowing the padding and headers to be explicitly marked with a specific left (-1), middle (0) or right(1) alignment. Existing files were fixed using the `fix` option after the changes.
118 lines
3.7 KiB
Markdown
118 lines
3.7 KiB
Markdown
<!--
|
|
SPDX-FileCopyrightText: (c) Respect Project Contributors
|
|
SPDX-License-Identifier: MIT
|
|
-->
|
|
|
|
# DateTime
|
|
|
|
- `DateTime()`
|
|
- `DateTime(string $format)`
|
|
|
|
Validates whether an input is a date/time or not.
|
|
|
|
The `$format` argument should be in accordance to [DateTime::format()][]. See more in the [Formats](#formats) section.
|
|
|
|
When a `$format` is not given its default value is `Y-m-d H:i:s`.
|
|
|
|
```php
|
|
v::dateTime()->assert('2009-01-01');
|
|
// Validation passes successfully
|
|
```
|
|
|
|
Also accepts [strtotime()](http://php.net/strtotime) values:
|
|
|
|
```php
|
|
v::dateTime()->assert('now');
|
|
// Validation passes successfully
|
|
```
|
|
|
|
And `DateTimeInterface` instances:
|
|
|
|
```php
|
|
v::dateTime()->assert(new DateTime());
|
|
// Validation passes successfully
|
|
|
|
v::dateTime()->assert(new DateTimeImmutable());
|
|
// Validation passes successfully
|
|
```
|
|
|
|
You can pass a format when validating strings:
|
|
|
|
```php
|
|
v::dateTime('Y-m-d')->assert('01-01-2009');
|
|
// → "01-01-2009" must be a valid date/time in the format "2005-12-30"
|
|
```
|
|
|
|
Format has no effect when validating DateTime instances.
|
|
|
|
Message template for this validator includes `{{sample}}`.
|
|
|
|
## Formats
|
|
|
|
Note that this validator validates whether the input **matches a given [DateTime::format()][] format** and **NOT if the input
|
|
can be parsed with a given [DateTimeImmutable::createFromFormat()][] format**. That makes the validation stricter but
|
|
offers some limitations.
|
|
|
|
The way [DateTimeImmutable::createFromFormat()][] parses an input allows for many different conversions. Overall
|
|
[DateTimeImmutable::createFromFormat()][] tend to be more lenient than [DateTime::format()][]. This might be what
|
|
you desire, and you may want to use [Callback](Callback.md) to create a custom validation.
|
|
|
|
```php
|
|
$input = '2014-04-12T23:20:50.052Z';
|
|
|
|
v::callback(fn($input) => is_string($input) && DateTime::createFromFormat(DateTime::RFC3339_EXTENDED, $input))
|
|
->assert($input);
|
|
// Validation passes successfully
|
|
|
|
v::dateTime(DateTime::RFC3339_EXTENDED)->assert($input);
|
|
// → "2014-04-12T23:20:50.052Z" must be a valid date/time in the format "2005-12-30T01:02:03.000+00:00"
|
|
```
|
|
|
|
## Templates
|
|
|
|
### `DateTime::TEMPLATE_STANDARD`
|
|
|
|
| Mode | Template |
|
|
| ---------: | :---------------------------------------- |
|
|
| `default` | {{subject}} must be a valid date/time |
|
|
| `inverted` | {{subject}} must not be a valid date/time |
|
|
|
|
### `DateTime::TEMPLATE_FORMAT`
|
|
|
|
| Mode | Template |
|
|
| ---------: | :----------------------------------------------------------------- |
|
|
| `default` | {{subject}} must be a valid date/time in the format {{sample}} |
|
|
| `inverted` | {{subject}} must not be a valid date/time in the format {{sample}} |
|
|
|
|
## Template placeholders
|
|
|
|
| Placeholder | Description |
|
|
| ----------- | ---------------------------------------------------------------- |
|
|
| `subject` | The validated input or the custom validator name (if specified). |
|
|
| `sample` | |
|
|
|
|
## Categorization
|
|
|
|
- Date and Time
|
|
|
|
## Changelog
|
|
|
|
| Version | Description |
|
|
| ------: | :----------------------------------------- |
|
|
| 2.3.0 | Validation became a lot stricter |
|
|
| 2.2.4 | `v::dateTime('z')` is no longer supported. |
|
|
| 2.0.0 | Created |
|
|
|
|
## See Also
|
|
|
|
- [Between](Between.md)
|
|
- [BetweenExclusive](BetweenExclusive.md)
|
|
- [Callback](Callback.md)
|
|
- [Date](Date.md)
|
|
- [DateTimeDiff](DateTimeDiff.md)
|
|
- [LeapDate](LeapDate.md)
|
|
- [LeapYear](LeapYear.md)
|
|
- [Time](Time.md)
|
|
|
|
[DateTimeImmutable::createFromFormat()]: https://www.php.net/datetimeimmutable.createfromformat
|
|
[DateTime::format()]: https://www.php.net/datetime.format
|