Doctrine Clock Bundle Laravel Package

Product Decisions This Supports

• Simplify Entity Development: Reduces boilerplate for timestamp management (creation/update) in Doctrine entities by replacing repetitive interfaces/traits with PHP attributes (e.g., #[CreateTimestamp]). Aligns with modern PHP/Symfony practices (attributes over annotations).
• Accelerate Onboarding: New developers can add timestamps without memorizing Doctrine/Symfony conventions, lowering cognitive load.
• Roadmap for Attribute-Based ORM: Supports a broader shift toward PHP 8+ attributes (e.g., replacing LifecycleCallbacks or custom listeners). Enables future features like:
  • Precision Timestamps: Add microsecond precision or timezone handling via attributes.
  • Soft Deletes: Extend to #[SoftDeleteTimestamp] with configurable logic.
  • Audit Trails: Integrate with Symfony’s Clock for deterministic testing (e.g., mocking timestamps in unit tests).
• Build vs. Buy: Buy for teams already using Symfony/Doctrine. Build only if needing custom timestamp logic (e.g., business-hour adjustments) or multi-ORM support.
• Use Cases:
  • CRUD-Heavy Apps: Automate timestamps in admin panels, CMS, or SaaS platforms.
  • Legacy Modernization: Migrate from LifecycleCallbacks to attributes without refactoring business logic.
  • Testing: Leverage Symfony’s Clock interface for reproducible timestamp tests (e.g., CI pipelines).

When to Consider This Package

• Look Elsewhere If:
  • Multi-ORM: Using Eloquent (Laravel) or non-Symfony ORMs (e.g., Propel). This is Symfony/Doctrine-specific.
  • Complex Timestamp Logic: Need business rules (e.g., "update timestamp only on admin edits")—attributes may not suffice; use listeners or services.
  • Performance-Critical Paths: Overhead of attribute reflection is negligible, but if timestamps are in a hot loop (e.g., bulk inserts), evaluate raw SQL DEFAULT CURRENT_TIMESTAMP.
  • Existing Mature Solutions: Teams already using Gedmo/DoctrineExtensions or custom traits may lack incentive to switch.
  • Non-Symfony 8.0/PHP 8.4: Compatibility is strict; requires Symfony 8+ and PHP 8.4+.
  • Need for Extensibility: Want to add metadata (e.g., #[CreateTimestamp(user: 'admin')])—this bundle is lightweight and may not support advanced use cases.

How to Pitch It (Stakeholders)

For Executives:

*"This package lets our backend team automate timestamp management in Doctrine entities using modern PHP attributes—no more repetitive interfaces or traits. It’s a 10-minute upgrade that:

• Reduces bugs: Eliminates manual timestamp errors in entities.
• Speeds development: New hires can add timestamps without ORM deep dives.
• Future-proofs: Aligns with Symfony’s attribute-first direction, making it easier to adopt upcoming features like soft deletes or audit trails. Cost: Zero (MIT license). Risk: Minimal—only 1 star but actively maintained by a small, responsive team. Let’s pilot it in our next feature sprint to replace LifecycleCallbacks in 2–3 entities and measure dev time saved."*

For Engineering:

*"This bundle replaces Doctrine timestamp boilerplate (e.g., implements TimestampableInterface) with PHP 8.4 attributes like #[CreateTimestamp]. Key benefits:

• Simplicity: Drop attributes on any property (e.g., #[UpdateTimestamp] public ?\DateTimeImmutable $updatedAt).
• Symfony Clock Integration: Enables deterministic testing—mock timestamps in unit tests without touching the database.
• Zero Runtime Overhead: Uses Doctrine’s event system under the hood; no reflection penalties in production. Tradeoffs:
• Tightly coupled to Symfony 8+/Doctrine. Not for legacy stacks.
• Limited to basic timestamps (no custom logic yet). Proposal: Use it for new entities in [Project X]. If successful, we can extend it for soft deletes or audit logs. Let’s start with a PR to replace UserEntity’s timestamps and compare dev time."*

Call to Action:

• Engineering: "Let’s add this to our composer.json and test it on a non-critical entity this sprint."
• Executives: "Approve the pilot—if it saves 2+ hours per entity, we’ll roll it out to all new models."