Sonata Republicandate Field Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require aschaeffer/sonata-republicandate-field-bundle
   

   For non-Flex projects, enable the bundle in AppKernel.php:

   new Aschaeffer\SonataRepublicandateFieldBundle\AschaefferSonataRepublicandateFieldBundle(),
   

2. First Use Case Add the annotation to a string property in your entity, linking it to a DateTime field:

   use Doctrine\ORM\Mapping as ORM;
   use Aschaeffer\SonataRepublicandateFieldBundle\Annotation\RepublicandateField;
   
   class User {
       /**
        * @ORM\Column(type="date", nullable=true)
        */
       protected ?\DateTimeInterface $birthday;
   
       /**
        * @ORM\Column(type="string", nullable=true)
        * @RepublicandateField(gregorianDate="birthday")
        */
       protected ?string $birthdayRepublican;
   }
   

3. Sonata Admin Integration Ensure your Sonata Admin class extends Sonata\AdminBundle\Admin\Admin and the entity is registered in the admin configuration.

Implementation Patterns

Workflows

1. Bidirectional Sync

   • The bundle automatically syncs between Gregorian (DateTime) and Republican (string) dates.
   • If a Gregorian date is set, the Republican equivalent is stored in the string field.
   • If no Gregorian date exists but a Republican date is provided, the bundle converts it to Gregorian and stores it.

2. Form Handling

   • The bundle integrates with Sonata’s form extensions, so the Republican date field appears as a text input in admin forms.
   • No additional form type configuration is required.

3. DataGrid Integration

   • Republican dates are displayed as plain text in Sonata’s DataGrid. For custom rendering, override the toString() method in your entity or use a custom field descriptor.

Integration Tips

• Validation: Add validation constraints to the Republican date field (e.g., @Assert\Regex for valid Republican date formats like 123ème de la République).
• Custom Formats: Extend the bundle’s RepublicandateConverter service to support non-standard Republican date formats.
• Localization: Ensure your Twig templates or admin templates handle the Republican date display consistently (e.g., {{ entity.birthdayRepublican }}).

Gotchas and Tips

Pitfalls

1. Missing ext-calendar Extension

   • The bundle requires the PHP ext-calendar extension for date conversions. Verify it’s enabled:

     php -m | grep calendar
     

   • If missing, install it via your OS package manager (e.g., sudo apt-get install php-calendar on Ubuntu).

2. Non-Existent Republican Dates

   • The bundle will silently fail to convert Gregorian dates that don’t exist in the Republican calendar (e.g., leap years). Handle this in your entity’s setter:

     public function setBirthday(?\DateTimeInterface $birthday): self {
         if ($birthday && !$this->isRepublicanDateValid($birthday)) {
             throw new \InvalidArgumentException('Invalid Republican date');
         }
         $this->birthday = $birthday;
         return $this;
     }
     

3. Sonata Admin Caching

   • Clear Sonata’s cache after adding the bundle to ensure the new field appears in the admin interface:

     php bin/console sonata:cache:clear
     

Debugging

• Log Conversions: Temporarily log the conversion process in the RepublicandateConverter service to debug issues:

  $converter->convertToRepublican($gregorianDate); // Add logging here
  

• Check Database Values: Verify the string field contains valid Republican dates (e.g., 123ème de la République).

Extension Points

1. Custom Converter Override the default converter by configuring a custom service:

   # config/services.yaml
   services:
       App\Service\CustomRepublicandateConverter:
           arguments:
               - '@service_container'
           tags: ['sonata_republicandate.converter']
   

2. Field Descriptor Override Customize how the Republican date appears in Sonata’s DataGrid:

   protected function configureListFields(ListMapper $listMapper) {
       $listMapper
           ->add('birthdayRepublican', 'string', [
               'template' => 'custom_republican_date.html.twig',
           ]);
   }
   

3. Validation Add custom validation logic to the Republican date field:

   use Symfony\Component\Validator\Constraints as Assert;
   
   /**
    * @ORM\Column(type="string", nullable=true)
    * @RepublicandateField(gregorianDate="birthday")
    * @Assert\Regex(
    *     pattern="/^\d{1,3}(?:ème|er|ère|e|ème de la République)$/",
    *     message="Invalid Republican date format"
    * )
    */
   protected ?string $birthdayRepublican;