API reference
This page lists public methods. See each object's guide for its readonly fields and examples.
Read a calendar
Import Mattmy\ICalendar\Facades\ICalendar to use these methods, or inject Mattmy\ICalendar\Reader for the same API:
read(string $contents): Calendar
tryRead(string $contents): ?Calendar
fromPath(string $path): Calendar
tryFromPath(string $path): ?Calendar
fromStream(mixed $stream): Calendar
tryFromStream(mixed $stream): ?Calendar
fromUploadedFile(UploadedFile $file): Calendar
tryFromUploadedFile(UploadedFile $file): ?CalendarA try*() method returns null only for invalid iCalendar content. See Reading input for source behavior and exceptions.
Query events, todos, journals, and warnings
$calendar->events(?string $uid = null): Collection
$calendar->hasEvents(?string $uid = null): bool
$calendar->event(string $uid): ?Event
$calendar->todos(?string $uid = null): Collection
$calendar->hasTodos(?string $uid = null): bool
$calendar->todo(string $uid): ?Todo
$calendar->journals(?string $uid = null): Collection
$calendar->hasJournals(?string $uid = null): bool
$calendar->journal(string $uid): ?Journal
$calendar->eventsBetween(DateTimeInterface $from, DateTimeInterface $until): Collection
$calendar->occurrencesBetween(DateTimeInterface $from, DateTimeInterface $until): Collection
$calendar->warnings(): Collectionevents(),todos(), andjournals()return all components, or every exact UID match, in document order.hasEvents(),hasTodos(), andhasJournals()test whether any component or UID match exists.event(),todo(), andjournal()return one exact UID match ornull.eventsBetween()returns events overlapping the requested half-open interval.occurrencesBetween()returns non-recurring events and expanded recurring occurrences overlapping the same interval.warnings()returns issues that did not prevent a result.
UID matching is case-sensitive. Singular UID lookup prefers the recurrence master when one is present. Both range methods accept DateTimeInterface, including Carbon; they throw InvalidArgumentException when $from is not earlier than $until. eventsBetween() does not expand recurrence rules. occurrencesBetween() may also throw UnsupportedRecurrence or RecurrenceLimitExceeded.
eventsBetween() throws UnresolvableEventRange when a required end time cannot be determined. The same applies to non-recurring events in occurrencesBetween(). The entire query fails. See Calendars, events, todos, and journals.
Query properties
Calendar, Event, Todo, Journal, Alarm, and Component expose:
$object->properties(?string $name = null): Collection
$object->hasProperty(?string $name = null): bool
$object->property(string $name): ?PropertyProperty and participant objects expose:
$property->parameters(): array
$property->parameter(string $name): string|array|null
$property->rawValue(): string
$property->toArray(): array
$organizer->parameters(): array
$attendee->parameters(): arrayProperty names are case-insensitive; lookup only checks direct properties. Singular lookup returns the first match or null. Parameters preserve multiple values; rawValue() returns normalized text. See Properties and components.
Query components
$calendar->components(?string $name = null): Collection
$calendar->hasComponent(?string $name = null): bool
$calendar->component(string $name): ?Component
$component->components(?string $name = null): Collectioncomponents()returns all direct children or every name match.hasComponent()tests whether the Calendar has any direct child or name match.component()returns the Calendar's first name match ornull.
Component names are case-insensitive and only direct children are examined.
Event and alarm helpers
$event->isAllDay(): bool
$trigger->isRelative(): bool
$trigger->isAbsolute(): bool
$trigger->duration(): ?DateInterval
$trigger->dateTime(): ?CarbonImmutable
$trigger->relatedTo(): ?stringisAllDay()reports whetherDTSTARTuses the DATE value type.isRelative()andisAbsolute()identify the trigger form.duration()returns a relative trigger offset ornull.dateTime()returns an absolute trigger time ornull.relatedTo()returnsSTART,END, ornullfor an absolute trigger.
See Participants and alarms for relative and absolute trigger behavior.
Convert or access complete data
$calendar->toArray(): array
$calendar->jsonSerialize(): array
$calendar->toJson(int $options = 0): string
$calendar->toComponentArray(): array
$calendar->rawComponent(): VCalendar
$event->rawComponent(): VEvent
$todo->rawComponent(): VTodo
$journal->rawComponent(): VJournal
$alarm->rawComponent(): VAlarm
$component->rawComponent(): SabreComponenttoArray()andjsonSerialize()return Calendar, Event, Todo, Journal, and warning data.toJson()JSON-encodes that data with the supplied PHP options.toComponentArray()returns the complete property and component tree.rawComponent()returns the corresponding Sabre component for advanced use.
See Arrays and JSON.
Inspect issues
$issue->toArray(): array
$issue->jsonSerialize(): array
$exception->issues(): CollectionCalendarIssue::toArray()andjsonSerialize()return one issue's seven fields.InvalidCalendar::issues()returns every reason the content was rejected.