## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require eluceo/ical

Ensure PHP version compatibility (e.g., 8.4-8.5 for 2.16+).

First Use Case: Generate a basic .ics file for a single event:

use Eluceo\iCal\Domain\Entity\{Event, Calendar};
use Eluceo\iCal\Domain\ValueObject\{SingleDay, Date};
use Eluceo\iCal\Presentation\Factory\CalendarFactory;

$event = (new Event())
    ->setSummary('Team Meeting')
    ->setOccurrence(
        new SingleDay(
            new Date(\DateTimeImmutable::createFromFormat('Y-m-d', '2024-10-15'))
        )
    );

$calendar = new Calendar([$event]);
$factory = new CalendarFactory();
$ical = $factory->createCalendar($calendar);

file_put_contents('meeting.ics', (string) $ical);

Key Classes to Explore:
- Domain: Event, Calendar, RecurrenceRule, TimeZone.
- Presentation: CalendarFactory, Component, Property.
- Value Objects: Date, DateTime, Period, Geo.
Documentation:
- Official docs: ical.poerschke.nrw.
- Examples: GitHub/examples.

Implementation Patterns

1. Event Creation Workflow

Pattern: Chain setters for clarity and immutability.

$event = (new Event())
    ->setSummary('Project Deadline')
    ->setDescription('Submit deliverables by EOD.')
    ->setOrganizer(new Organizer('mailto:[email protected]'))
    ->setStatus('CONFIRMED')
    ->addCategory(['work', 'urgent'])
    ->setUrl('https://app.example.com/project/123');

Recurring Events:

use Eluceo\iCal\Domain\ValueObject\RecurrenceRule;

$rule = new RecurrenceRule('WEEKLY', 'FREQ=WEEKLY;BYDAY=MO,WE,FR');
$event->addRecurrenceRule($rule);

2. Time Zone Handling

Pattern: Use TimeZone for timezone-aware events.

use Eluceo\iCal\Domain\ValueObject\{DateTime, TimeZone};

$timeZone = TimeZone::createFromPhpDateTimeZone(
    new \DateTimeZone('America/New_York'),
    new \DateTimeImmutable('2024-10-15T09:00:00')
);

$event->setOccurrence(
    new DateTime($timeZone, new \DateTimeImmutable('2024-10-15T09:00:00'))
);

3. Calendar Integration

Pattern: Batch events and customize calendar properties.

$events = collect(range(1, 5))->map(fn($i) =>
    (new Event())
        ->setSummary("Event $i")
        ->setOccurrence(new SingleDay(new Date(\DateTimeImmutable::createFromFormat('Y-m-d', "2024-10-$i"))))
);

$calendar = new Calendar($events->toArray());
$calendar->setProductId('MyApp/1.0')
         ->setTimeZone(TimeZone::createFromPhpDateTimeZone(new \DateTimeZone('UTC')))
         ->setPublishedTTL('P1D'); // Update every day

4. Output Strategies

Pattern A: File Download

header('Content-Type: text/calendar; charset=utf-8');
header('Content-Disposition: attachment; filename="calendar.ics"');
echo $ical;

Pattern B: API Response (Laravel)

return response($ical, 200, [
    'Content-Type' => 'text/calendar',
    'Content-Disposition' => 'attachment; filename="calendar.ics"',
]);

Pattern C: In-Memory Processing

$icalString = (string) $ical;
// Parse/modify with `Eluceo\iCal\Presentation\Parser\Parser` if needed.

5. Recurrence Rules

Pattern: Combine rules for complex schedules.

$rule1 = new RecurrenceRule('DAILY', 'FREQ=DAILY;COUNT=5');
$rule2 = new RecurrenceRule('WEEKLY', 'FREQ=WEEKLY;BYDAY=MO');
$event->addRecurrenceRule($rule1);
$event->addRecurrenceRule($rule2);

6. Extending Properties

Pattern: Add custom properties (e.g., X-PROPERTY).

use Eluceo\iCal\Domain\ValueObject\Property\Text;

$event->addProperty(new Text('X-CUSTOM', 'CustomValue'));

Gotchas and Tips

1. Time Zone Pitfalls

Issue: Events appear misaligned in clients (e.g., Outlook). Fix: Explicitly set TimeZone on Calendar and Event:
```
$calendar->setTimeZone(TimeZone::createFromPhpDateTimeZone(new \DateTimeZone('UTC')));
```
Gotcha: DateTime vs. Date:
- Use Date for all-day events (no time).
- Use DateTime for timed events (with TimeZone).

2. Recurrence Rule Quirks

Issue: Rules with BYSETPOS or BYMONTHDAY may not render correctly. Fix: Escape values manually if needed (e.g., BYDAY=MO,WE,FR → BYDAY=MO;WE;FR).
Tip: Validate rules with RFC 5545 or tools like icalendar.org.

3. Performance Tips

Large Calendars: Use Calendar::setPublishedTTL('P1W') to reduce sync frequency.

Memory: For >10K events, stream output instead of building the entire string in memory:

$stream = fopen('php://output', 'w');
fwrite($stream, (string) $ical);
fclose($stream);

4. Debugging

Invalid ICS: Validate output with:

icsvalidate calendar.ics  # Requires `icalendar` CLI tool

Common Errors:
- DTSTART/DTEND missing: Ensure Occurrence is set.
- Malformed RRULE: Use RecurrenceRule::validate() or check RFC compliance.
- UTF-8 issues: Explicitly set charset in headers:
```
header('Content-Type: text/calendar; charset=UTF-8');
```

5. Laravel-Specific Tips

Service Provider:

$this->app->singleton(CalendarFactory::class, fn() => new CalendarFactory());

Jobs: Queue ICS generation for long-running tasks:

GenerateIcsJob::dispatch($events)->onQueue('ical');

Storage: Use storage_path('app/ics') for temporary files.

6. Extension Points

Custom Properties: Extend Eluceo\iCal\Domain\ValueObject\Property\AbstractProperty.
Parsing: Use Eluceo\iCal\Presentation\Parser\Parser to read existing .ics files.

Factories: Override CalendarFactory to modify default properties:

class CustomCalendarFactory extends CalendarFactory {
    protected function getProperties(): array {
        return array_merge(parent::getProperties(), [
            new ProductId('MyApp/2.0'),
        ]);
    }
}

7. Common Anti-Patterns

Avoid: Modifying Domain objects after factory creation (immutable design).
Avoid: Hardcoding time zones (use TimeZone objects).

Avoid: Skipping DTSTAMP (required by RFC 5545):

$event->setDtStamp(new \DateTimeImmutable());

8. Edge Cases

All-Day Events: Ensure DTEND is set to DTSTART + 1 day:

$event->setOccurrence(new Period(
    new DateTime($timeZone, $start),
    new Date

Ical Laravel Package