Download the PHP package aegisora/date-format-rule without Composer

Aegisora Date Format Rule

Date Format Rule provides a simple, rule-based date/time format validation implementation for the Aegisora ecosystem.

It is built on top of aegisora/rule-contract and follows its strict validation architecture, ensuring consistent and predictable behavior across applications.

This rule is useful for validating user input, form fields, birth dates, appointment times, API request parameters, imported data, and any other string that must conform to a specific date/time format.

📑 Table of Contents

• Features
• Installation
• Core Concept
• Basic Usage
• Valid vs Invalid
• Validation Result
• Time Zones
• Guardian Usage
• Real-World Examples
• Constructor & API
• Architecture
• License
• Contributing
• Support

✨ Features

• 🔹 Lightweight and dependency-free except aegisora/rule-contract
• 🔹 Validates a string against any PHP date/time format (Y-m-d, d/m/Y H:i, H:i:s, ...)
• 🔹 Supports the full PHP format syntax, including escaped literals (\T)
• 🔹 Exhaustive check — rejects overflow dates (2026-02-31), out-of-range values, and non-canonical input the parser silently tolerates
• 🔹 Optional time zone support
• 🔹 Rejects non-string input as an invalid context
• 🔹 Fully compatible with Aegisora validation pipeline
• 🔹 Strict Context → Result validation flow
• 🔹 No raw booleans — only structured results
• 🔹 Safe execution via base Rule abstraction
• 🔹 Ready to use out of the box

📦 Installation

🚀 Core Concept

This package implements a single validation rule:

• accepts a string value via Context
• checks whether the string is a valid date/time that strictly matches the configured format
• returns a standardized Result

Under the hood it wraps the common — and easy to get wrong — boilerplate:

into a reusable rule that reports its outcome through a Result object instead of a raw boolean.

🏗️ Basic Usage

✅ Valid vs Invalid

The rule passes when the string is a real date/time that renders back exactly as the input under the configured format, and fails otherwise.

Dates

Strict formatting

Times and combined formats

🧪 Validation Result

If the string is a valid date/time matching the format, the rule returns a valid result.

$result->isValid(); // true

If the string does not match the format, the rule returns an invalid result.

If the context value is not a string, the rule throws:

Aegisora\RuleContract\Exceptions\InvalidRuleContextException

If the configured format is an empty string, the rule throws:

Aegisora\RuleContract\Exceptions\InvalidRuleContextException

🌍 Time Zones

An optional DateTimeZone can be passed as the second argument. It is used while parsing the value, which matters for formats that carry time information.

If the format itself carries a time zone (e, T, P, O), that value takes precedence and the argument is ignored.

🔗 Guardian Usage

This rule can be used together with aegisora/guardian to build fluent validation pipelines.

If the value does not match the format, Guardian throws the provided domain exception.

🧭 Real-World Examples

Date Format Rule is useful for enforcing date/time constraints before values are persisted or processed.

Examples

🧩 Constructor & API

new DateFormatRule($format);

• creates a rule that passes when the value is a valid date/time strictly matching the PHP $format

new DateFormatRule($format, $timeZone);

• additionally applies the given DateTimeZone while parsing the value

(new DateFormatRule($format))->validate($context);

• $context — Context wrapping the string value to validate

🏛️ Architecture

This package relies on aegisora/rule-contract.

Flow:

1. validate() is called
2. Context is passed in
3. The configured format is checked; an empty format raises InvalidRuleContextException
4. The string value is extracted from context (non-strings raise InvalidRuleContextException)
5. The value is parsed with DateTimeImmutable::createFromFormat(), checked against getLastErrors() for overflow/out-of-range warnings, and round-tripped back through the format to reject non-canonical input
6. Result is returned — valid on a strict match, invalid with the date_format_rule code otherwise

All logic is safely handled by Rule contract.

⚖️ License

This package is open-source and licensed under the MIT License. See the LICENSE for details.

🌱 Contributing

Contributions are welcome and greatly appreciated! See the CONTRIBUTING for details.

🌟 Support

If you find this project useful, please consider giving it a star on GitHub!

It helps the project grow and motivates further development.