Mycalendar Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require axi/mycalendar
   

   Ensure eluceo/ical is installed if using the ical format:

   composer require eluceo/ical
   

2. First Use Case: Calculate special dates for a given birthdate (e.g., 15,000th day):

   use Axi\MyCalendar\Service\CalendarService;
   
   $calendar = new CalendarService();
   $events = $calendar->getEventsFromDate(
       new DateTime("1990-05-15"),
       'json'
   );
   echo $events->getContent();
   

3. Key Files:

   • vendor/axi/mycalendar/src/Service/CalendarService.php (Core logic)
   • vendor/axi/mycalendar/src/Recipe/ (Predefined recipes like ThousandsDays, PlanetsRevolutions)

Implementation Patterns

Core Workflow

1. Instantiate the Service:

   $calendar = new CalendarService();
   

   • Pass a custom DateTime object or use the default constructor (today).

2. Fetch Events:

   $events = $calendar->getEventsFromDate(
       $birthDate, // DateTime
       'json'      // Format: 'json', 'ical', or 'none'
   );
   

   • Formats:
     • json: Returns a JSON string (e.g., {"15000": "1990-05-15 00:00:00"}).
     • ical: Requires eluceo/ical; returns an iCalendar string.
     • none: Returns an internal Event object for custom processing.

3. Leverage Recipes:

   // Example: Add a custom recipe (e.g., "SleepTime")
   $calendar->addRecipe(new \Axi\MyCalendar\Recipe\SleepTime());
   $events = $calendar->getEventsFromDate($birthDate, 'none');
   foreach ($events->getEvents() as $event) {
       echo $event->getName() . ": " . $event->getDate()->format('Y-m-d');
   }
   

4. Integration with Laravel:

   • Service Provider: Bind the service to the container in AppServiceProvider:

     public function register()
     {
         $this->app->singleton(CalendarService::class, function () {
             return new CalendarService();
         });
     }
     

   • Facade (Optional): Create a facade for cleaner syntax:

     // app/Facades/MyCalendar.php
     namespace App\Facades;
     use Illuminate\Support\Facades\Facade;
     class MyCalendar extends Facade { protected static function getFacadeAccessor() { return 'calendar'; } }
     

     Register the facade in config/app.php and bind the service in AppServiceProvider.

   • Usage in Controllers:

     use App\Facades\MyCalendar;
     
     public function showBirthdayEvents(Request $request)
     {
         $birthDate = new \DateTime($request->input('birthdate'));
         $events = MyCalendar::getEventsFromDate($birthDate, 'json');
         return response()->json(['events' => json_decode($events, true)]);
     }
     

5. Dynamic Date Handling:

   • Use Laravel’s Carbon for seamless date manipulation:

     use Carbon\Carbon;
     
     $birthDate = Carbon::parse($request->birthdate);
     $events = $calendar->getEventsFromDate($birthDate, 'none');
     

Gotchas and Tips

Pitfalls

1. Missing eluceo/ical Dependency:

   • If using the ical format, ensure eluceo/ical is installed. The package does not auto-install it.
   • Fix: Manually require it via Composer or add it to composer.json:

     "require": {
         "eluceo/ical": "^2.0"
     }
     

2. Timezone Sensitivity:

   • The package uses the system timezone by default. For consistency, explicitly set the timezone:

     $birthDate = new \DateTime("1990-05-15", new \DateTimeZone('UTC'));
     

   • In Laravel, configure the default timezone in .env:

     APP_TIMEZONE=UTC
     

3. Recipe Overrides:

   • Predefined recipes (e.g., ThousandsDays) may not cover all use cases. Custom recipes must extend \Axi\MyCalendar\Recipe\RecipeInterface and implement getEvents().
   • Example Custom Recipe:

     namespace App\Recipes;
     use Axi\MyCalendar\Recipe\RecipeInterface;
     use Axi\MyCalendar\Event\Event;
     
     class CustomMilestone implements RecipeInterface {
         public function getEvents(\DateTime $date): array {
             $events = [];
             $targetDays = [1000, 5000, 10000];
             foreach ($targetDays as $days) {
                 $eventDate = clone $date;
                 $eventDate->modify("+$days days");
                 $events[] = new Event("Custom Milestone $days", $eventDate);
             }
             return $events;
         }
     }
     

4. Performance with Large Date Ranges:

   • Calculating events for distant dates (e.g., 100,000 days) may impact performance. Cache results in Laravel:

     $events = Cache::remember("calendar_events_{$birthDate->format('Y-m-d')}", now()->addDays(365), function () use ($calendar, $birthDate) {
         return $calendar->getEventsFromDate($birthDate, 'none');
     });
     

5. Event Object Quirks:

   • The none format returns an Event object with methods like:
     • getName(): Event name (e.g., "15000th Day").
     • getDate(): DateTime object of the event.
     • getContent(): Only available for json/ical formats.
   • Workaround for none format:

     $event = $events->getEvents()[0];
     echo $event->getName() . " on " . $event->getDate()->format('Y-m-d');
     

Debugging Tips

1. Inspect Internal Events:

   • Use the none format to debug event generation:

     $events = $calendar->getEventsFromDate($birthDate, 'none');
     dd($events->getEvents()); // Dump all generated events
     

2. Validate Input Dates:

   • Ensure the input DateTime is valid:

     if (!$birthDate instanceof \DateTime) {
         throw new \InvalidArgumentException("Invalid birthdate provided.");
     }
     

3. Check for Recipe Conflicts:

   • If events are missing, verify recipes are correctly added:

     $calendar->addRecipe(new \Axi\MyCalendar\Recipe\ThousandsDays());
     $calendar->addRecipe(new \Axi\MyCalendar\Recipe\SleepTime());
     

Extension Points

1. Custom Recipes:

   • Extend functionality by creating new recipes. Example:

     namespace App\Recipes;
     use Axi\MyCalendar\Recipe\RecipeInterface;
     use Axi\MyCalendar\Event\Event;
     
     class ZodiacSigns implements RecipeInterface {
         public function getEvents(\DateTime $date): array {
             $zodiacDates = [
                 'Aries' => '03-21', 'Taurus' => '04-19', // ... (add all signs)
             ];
             $events = [];
             foreach ($zodiacDates as $sign => $startDate) {
                 $eventDate = \DateTime::createFromFormat('Y-m-d', $date->format('Y') . '-' . $startDate);
                 $events[] = new Event("Zodiac: $sign", $eventDate);
             }
             return $events;
         }
     }
     

2. Modify Event Formatting:

   • Override the json or ical output by extending CalendarService:

     namespace App\Services;
     use Axi\MyCalendar\Service\CalendarService;
     
     class CustomCalendarService extends CalendarService {
         public function getEventsFromDate(\DateTime $dateTime, string $format = 'json') {
             $events = parent::getEventsFromDate($dateTime, $format);
             if ($format === 'json') {
                 $content = $events->getContent();
                 $content = str_replace('"', "'", $content); // Custom JSON tweak
                 $events->setContent($content);
             }
             return $events;
         }
     }
     

3. Localization:

   • The package supports translation via Weblate. Extend translations by adding a resources/lang/ directory in your project and publishing the