Agenda Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ekyna/agenda-bundle
   

   Add to config/bundles.php:

   Ekyna\AgendaBundle\EkynaAgendaBundle::class => ['all' => true],
   

2. Publish Config & Migrations

   php artisan vendor:publish --provider="Ekyna\AgendaBundle\EkynaAgendaBundle" --tag="config"
   php artisan migrate
   

3. First Use Case Create an agenda event via Tinker:

   php artisan tinker
   

   $agenda = new \Ekyna\AgendaBundle\Entity\Agenda();
   $agenda->setTitle('Team Sync');
   $agenda->setStartDate(new \DateTime('2024-01-15 10:00:00'));
   $agenda->setEndDate(new \DateTime('2024-01-15 11:00:00'));
   $agenda->setDescription('Weekly team alignment');
   $agendaManager = $this->app->make('ekyna_agenda.manager.agenda');
   $agendaManager->save($agenda);
   

Implementation Patterns

Core Workflows

1. CRUD Operations Use the manager service for all agenda operations:

   $agendaManager = $this->container->get('ekyna_agenda.manager.agenda');
   $agendas = $agendaManager->findAll(); // Get all agendas
   $agenda = $agendaManager->find(1);   // Get single agenda
   $agendaManager->remove($agenda);     // Delete agenda
   

2. Event Integration Listen for agenda events (e.g., ekyna.agenda.pre_save):

   // In a service provider
   $this->eventDispatcher->addListener(
       'ekyna.agenda.pre_save',
       function ($agenda) {
           // Modify agenda before save
       }
   );
   

3. API Endpoints Create a controller to expose agenda data:

   use Ekyna\AgendaBundle\Entity\Agenda;
   use Ekyna\AgendaBundle\Manager\AgendaManager;
   
   class AgendaController extends Controller
   {
       public function index(AgendaManager $manager)
       {
           return response()->json($manager->findAll());
       }
   }
   

4. Frontend Integration Fetch agendas via API and render with a calendar library (e.g., FullCalendar):

   fetch('/api/agendas')
       .then(response => response.json())
       .then(agendas => {
           // Format for FullCalendar
           const events = agendas.map(a => ({
               title: a.title,
               start: a.startDate,
               end: a.endDate
           }));
           calendar.addEventSource(events);
       });
   

Gotchas and Tips

Common Pitfalls

1. Missing Configuration Ensure config/ekyna_agenda.php is published and updated. Default values may not suit all use cases (e.g., timezone settings).

2. Date Handling Always use DateTime objects for startDate/endDate to avoid timezone issues. Example:

   $agenda->setStartDate(new \DateTime('now', new \DateTimeZone('Europe/Paris')));
   

3. Entity Lifecycle The bundle uses Doctrine lifecycle callbacks. Override these carefully to avoid infinite loops:

   // Bad: Triggers prePersist again
   $agenda->prePersist();
   

4. Performance Avoid loading large datasets without pagination. Use DQL or repository methods:

   $agendaManager->createQueryBuilder('a')
       ->where('a.startDate > :date')
       ->setParameter('date', new \DateTime('-1 month'))
       ->getQuery()
       ->getResult();
   

Debugging Tips

• Enable SQL Logging Add to config/database.php:

  'logging' => true,
  'default' => 'doctrine',
  

  Then check storage/logs/laravel.log for raw SQL queries.

• Event Debugging Dump dispatched events in a listener:

  $this->eventDispatcher->addListener(
      '*',
      function ($event) {
          \Log::debug('Event:', [$event->getName(), $event->getArguments()]);
      }
  );
  

Extension Points

1. Custom Fields Extend the Agenda entity:

   namespace App\Entity;
   
   use Ekyna\AgendaBundle\Entity\Agenda as BaseAgenda;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   class Agenda extends BaseAgenda
   {
       #[ORM\Column(type: 'string', nullable: true)]
       private $location;
   
       // Getters/setters...
   }
   

2. Validation Add custom validation to the entity or use a form type:

   use Symfony\Component\Validator\Constraints as Assert;
   
   #[Assert\NotBlank]
   #[Assert\Length(max: 255)]
   private $title;
   

3. Recurring Events Implement a recurring event strategy by adding a recurrenceRule field (e.g., iCal RRULE) and a cron job to generate instances:

   $agenda->setRecurrenceRule('FREQ=WEEKLY;BYDAY=MO');