Validation and configuration
Invalid content and warnings
read*() methods throw InvalidCalendar for invalid iCalendar content. Their try*() counterparts return null only for that exception; source, size, and configuration failures still throw their specific exceptions. The reader does not repair rejected content.
Validation includes BOOLEAN/FLOAT values and basic RRULE syntax and combinations. Invalid rules fail during reading; valid rules that cannot be expanded raise UnsupportedRecurrence when you call occurrencesBetween().
use Mattmy\ICalendar\Exceptions\InvalidCalendar;
use Mattmy\ICalendar\Facades\ICalendar;
try {
$calendar = ICalendar::read($contents);
} catch (InvalidCalendar $exception) {
$issues = $exception->issues();
}issues() explains rejected content; $calendar->warnings() reports issues with readable content or configuration. Both return Collection<int, CalendarIssue>.
CalendarIssue
| Member | Type and meaning |
|---|---|
level | int: CalendarIssue::LEVEL_WARNING (2) or CalendarIssue::LEVEL_ERROR (3). |
code | string: parser_error, invalid_root_component, validation_error, validation_warning, invalid_timezone_configuration, or mapping_warning. |
message | string: human-readable detail; do not use it as a machine code. |
source | string: parser, validator, configuration, or mapping. |
line | ?int: optional source line. |
component, property | ?string: optional affected iCalendar names. |
toArray() and jsonSerialize() return the same seven fixed keys.
Configuration
Publish config/icalendar_reader.php when the defaults do not fit your application:
php artisan vendor:publish --tag=icalendar-reader-configreturn [
'max_bytes' => 10 * 1024 * 1024,
'floating_timezone' => null,
];max_bytes must be a positive integer. The limit is enforced against bytes actually read, not client-provided metadata. An invalid value throws InvalidConfiguration.
floating_timezone sets the timezone for DATE values and date-times without Z or TZID. Use an IANA timezone name, such as Asia/Taipei, or null:
- A valid non-null package value is used.
- An invalid non-null package value produces a warning and uses UTC; it does not fall back to
app.timezone. - When the package value is
null, a validapp.timezoneis used. - When both the package value is
nullandapp.timezoneis invalid, a warning is produced and UTC is used.
The package validates app.timezone in every case, so an invalid application setting remains visible as a warning even when a valid package override is used.
Exception reference
All package exceptions implement ICalendarException.
| Exception | Meaning |
|---|---|
InvalidCalendar | Syntax, root, or validation failure; inspect issues(). |
CalendarFileNotFound | Local or upload backing file does not exist. |
CalendarFileUnreadable | An existing file or stream cannot be read. |
CalendarTooLarge | Actual input exceeds max_bytes. |
InvalidCalendarSource | Wrong resource type, unreadable stream mode, or invalid upload. |
InvalidConfiguration | max_bytes is not a positive integer. |
UnsupportedRecurrence | A valid recurrence series cannot be expanded safely. |
UnresolvableEventRange | eventsBetween() cannot determine a required end time; also applies to non-recurring events in occurrencesBetween(). The entire query fails. |
RecurrenceLimitExceeded | An occurrence query evaluated more than 3,500 candidates; request a narrower range. |
PHP's InvalidArgumentException is used for blank lookup names or invalid query ranges; JsonException is used for JSON encoding failures. These are not package exceptions.