Add DateTime identifiers documentation with practical examples

[Copilot]

While \DateTime is listed as a supported identifier type, the documentation lacks practical examples showing developers how to implement it.

Changes

• New "Using DateTime Identifiers" section positioned after "Custom Identifier Normalizer"

  • Demonstrates \DateTime and \DateTimeImmutable as identifiers for time-series data, scheduled events, and logs
  • Shows PHP attributes, YAML, and XML configuration syntax
  • Explains automatic URL handling via DateTimeUriVariableTransformer using Symfony's DateTimeNormalizer (RFC 3339 format)
  • Includes state provider example with automatic DateTime parsing
  • Provides Doctrine entity example using DateTime as primary key

• Updated "Supported Identifiers" list to explicitly mention both \DateTime and \DateTimeImmutable

Example

#[ApiResource(provider: ObservationProvider::class)]
final class Observation
{
    #[ApiProperty(identifier: true)]
    public \DateTimeImmutable $recordedAt;
    
    public string $temperature;
    // ...
}

Accessible at /observations/2023-05-31T10:30:00+00:00 with automatic parsing in providers:

public function provide(Operation $operation, array $uriVariables = [], array $context = []): ?Observation
{
    // $uriVariables['recordedAt'] is already a \DateTimeImmutable instance
    $recordedAt = $uriVariables['recordedAt'];
    return $this->findObservationByTimestamp($recordedAt);
}

Note: Requires API Platform 3.1+

Original prompt

Context

Pull request api-platform/core#5606 adds support for creating items with DateTime identifiers. While the current core/identifiers.md file mentions that \DateTime is a supported identifier type (line 212-213), it lacks a practical example showing developers how to use this feature.

Task

Update the core/identifiers.md file to include a comprehensive example demonstrating how to use DateTime as an identifier in API Platform resources.

Requirements

1. Add a new section in the core/identifiers.md file titled "Using DateTime Identifiers"
2. The section should be placed after the "Custom Identifier Normalizer" section and before the "Changing Identifier in a Doctrine Entity" section
3. Include a practical code example showing:
   • How to define a resource with a DateTime identifier
   • Example entity/resource class with DateTime identifier property
   • A brief explanation of how DateTime identifiers are automatically handled by API Platform's DateTimeUriVariableTransformer
4. Show the URL format that would be generated (e.g., /resources/2023-05-31T10:30:00+00:00)
5. Mention that DateTime identifiers use Symfony's DateTimeNormalizer internally
6. Include both PHP attributes syntax example
7. Optionally show how this works with Doctrine entities

Example Structure

The new section should follow this structure:

## Using DateTime Identifiers

API Platform supports using `\DateTime` (and `\DateTimeImmutable`) objects as identifiers. This is particularly useful for resources that are naturally identified by a timestamp or date.

[Include code example here showing a resource with DateTime identifier]

[Include explanation of URL format and how it works]

[Optionally include Doctrine entity example]

Related

• Pull Request: fix: generate IRI with datetime identifier core#5606
• Related Issue: Changing "Identifier" in entity to a DateTime lead to an Exception "Unable to generate an IRI for the item". api-platform#2444

Notes

• Ensure the documentation follows the existing style and formatting conventions in the identifiers.md file
• Use the code-selector pattern if providing multiple syntax examples (PHP/YAML/XML)
• Keep explanations clear and concise
• The DateTime identifiers feature is available in API Platform 3.1+

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.