Add DateTime identifier usage example to documentation

[Copilot]

While \DateTime is listed as a supported identifier type in the documentation, there are no practical examples showing developers how to use it. This adds a comprehensive example section demonstrating DateTime/DateTimeImmutable as resource identifiers.

Changes

Added new section "Using DateTime as an Identifier" to core/identifiers.md with:

• Basic Example: Complete Doctrine entity using DateTimeImmutable as identifier
• URL Format: Explains ISO 8601 representation in URLs (/daily_reports/2023-05-31T10:30:00+00:00) and URL encoding requirements
• Implementation Notes: Documents DateTimeUriVariableTransformer's automatic registration and use of Symfony's DateTimeNormalizer
• Best Practices: Recommends DateTimeImmutable over DateTime, datetime_immutable Doctrine type, and timezone considerations

Example

#[ORM\Entity]
#[ApiResource]
final class DailyReport
{
    #[ORM\Id]
    #[ORM\Column(type: 'datetime_immutable')]
    #[ApiProperty(identifier: true)]
    public \DateTimeImmutable $reportDate;

    #[ORM\Column]
    public string $content;
}

The section is positioned after "Custom Identifier Normalizer" and links to the DateTimeUriVariableTransformer source, consistent with how other transformers are documented in the "Supported Identifiers" section.

Original prompt

Add DateTime Identifier Usage Example to Documentation

Context

Pull request api-platform/core#5606 ("fix: generate IRI with datetime identifier") adds support for using DateTime objects as identifiers in API Platform. While the identifiers.md documentation mentions that \DateTime is a supported identifier type, there is no practical example showing developers how to use this feature.

Related

• PR: 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

Task

Update the core/identifiers.md file to include a comprehensive example section demonstrating how to use DateTime/DateTimeImmutable as resource identifiers.

Requirements

Add a new section titled "## Using DateTime as an Identifier" after the "Custom Identifier Normalizer" section (around line 173, before "## Changing Identifier in a Doctrine Entity").

The new section should include:

1. Introduction: Brief explanation that DateTime identifiers are useful for resources identified by timestamps or dates (e.g., daily reports, scheduled events)

2. Basic Example with Doctrine Entity: Show a complete example with:

   • An entity using \DateTimeImmutable as the identifier
   • Proper annotations for both Doctrine and API Platform
   • The datetime Doctrine type

3. Code Example Structure:

   <?php
   // api/src/Entity/DailyReport.php
   namespace App\Entity;
   
   use ApiPlatform\Metadata\ApiProperty;
   use ApiPlatform\Metadata\ApiResource;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   #[ApiResource]
   final class DailyReport
   {
       #[ORM\Id]
       #[ORM\Column(type: 'datetime_immutable')]
       #[ApiProperty(identifier: true)]
       public \DateTimeImmutable $reportDate;
   
       #[ORM\Column]
       public string $content;
   
       // ...
   }

4. URL Format Explanation: Explain how the DateTime is represented in URLs:

   • Example: /daily_reports/2023-05-31T10:30:00+00:00
   • Note about URL encoding for special characters
   • Mention that the DateTimeUriVariableTransformer handles the conversion automatically

5. Important Notes:

   • The DateTimeUriVariableTransformer uses Symfony's DateTimeNormalizer internally
   • Supports \DateTime, \DateTimeImmutable, and \DateTimeInterface
   • The transformer is automatically registered with the api_platform.uri_variables.transformer tag
   • No manual configuration needed - it works out of the box

6. Best Practices:

   • Recommend using DateTimeImmutable over DateTime for immutability
   • Suggest using the datetime_immutable Doctrine type
   • Consider timezone implications in your API design

File to Modify

• core/identifiers.md - Add the new section after line 173

Acceptance Criteria

• New section is properly formatted in Markdown
• Code examples follow the existing documentation style (using code-selector if needed for Symfony/Laravel variants)
• Examples are practical and complete
• Section fits logically in the document flow
• No existing content is removed or broken
• Links to the DateTimeUriVariableTransformer source code are included (similar to how other transformers are referenced in the "Supported Identifiers" section)

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[soyuka]

@copilot The PR @api-platform/core/pull/5606 clearly shows that this is not working from scratch. Users shoulde decorate the identifiersextractor to pick the identifier serialization format or else it'd be a default toString on a datetime ? also this ise quite an edge case therefore we can be quite short and concise in the added documentation