diff --git a/README.md b/README.md index 45fddea..791e1d5 100644 --- a/README.md +++ b/README.md @@ -119,59 +119,66 @@ need to be evaluated before non-fitting events can be dropped. | `$defaultWeekStart` | :ballot_box_with_check: | `MO` | The two letter representation of the first day of the week | | `$disableCharacterReplacement` | :ballot_box_with_check: | `false` | Toggles whether to disable all character replacement. Will replace curly quotes and other special characters with their standard equivalents if `false`. Can be a costly operation! | | `$eventCount` | :heavy_multiplication_x: | N/A | Tracks the number of events in the current iCal feed | -| `$filterDaysAfter` | :ballot_box_with_check: | N/A | When set the parser will ignore all events more than roughly this many days _after_ now. To be on the safe side it is advised that you make the filter window `+/- 1` day larger than necessary. For performance reasons this filter is applied before any date and time zone calculations are done. Hence, depending the time zone settings of the parser and the calendar the cut-off date is not "calibrated". You can then use `$ical->eventsFromRange()` to precisely shrink the window. | -| `$filterDaysBefore` | :ballot_box_with_check: | N/A | When set the parser will ignore all events more than roughly this many days _before_ now. See `$filterDaysAfter` above for more details. | +| `$filterDaysAfter` | :ballot_box_with_check: | `null` | When set the parser will ignore all events more than roughly this many days _after_ now. To be on the safe side it is advised that you make the filter window `+/- 1` day larger than necessary. For performance reasons this filter is applied before any date and time zone calculations are done. Hence, depending the time zone settings of the parser and the calendar the cut-off date is not "calibrated". You can then use `$ical->eventsFromRange()` to precisely shrink the window. | +| `$filterDaysBefore` | :ballot_box_with_check: | `null` | When set the parser will ignore all events more than roughly this many days _before_ now. See `$filterDaysAfter` above for more details. | | `$freeBusyCount` | :heavy_multiplication_x: | N/A | Tracks the free/busy count in the current iCal feed | | `$httpBasicAuth` | :heavy_multiplication_x: | `array()` | Holds the username and password for HTTP basic authentication | | `$replaceWindowsTimeZoneIds` | :ballot_box_with_check: | `false` | Toggles whether to replace (non-CLDR) Windows time zone IDs with their IANA equivalent e.g. "Mountain Standard Time" would be replaced with "America/Denver". As there are 130+ Windows time zone IDs that need to be searched and replaced this flag should only be turned on if you know that your calendar file contains such time zone IDs. **Microsoft Exchange** calendars are often seen using such IDs. | +| `$shouldFilterByWindow` | :heavy_multiplication_x: | `false` | True if either `$filterDaysBefore` or `$filterDaysAfter` are set | | `$skipRecurrence` | :ballot_box_with_check: | `false` | Toggles whether to skip the parsing of recurrence rules | | `$todoCount` | :heavy_multiplication_x: | N/A | Tracks the number of todos in the current iCal feed | | `$useTimeZoneWithRRules` | :ballot_box_with_check: | `false` | Toggles whether to use time zone info when parsing recurrence rules | +| `$windowMaxTimestamp` | :heavy_multiplication_x: | `null` | If `$filterDaysBefore` or `$filterDaysAfter` are set then the events are filtered according to the window defined by this field and `$windowMinTimestamp` | +| `$windowMinTimestamp` | :heavy_multiplication_x: | `null` | If `$filterDaysBefore` or `$filterDaysAfter` are set then the events are filtered according to the window defined by this field and `$windowMaxTimestamp` | #### Methods -| Method | Parameter(s) | Visibility | Description | -|---------------------------------------|------------------------------------------------------------|-------------|-------------------------------------------------------------------------------------------------------| -| `__construct` | `$files = false`, `$options = array()` | `public` | Creates the ICal object | -| `initFile` | `$file` | `protected` | Initialises lines from a file | -| `initLines` | `$lines` | `protected` | Initialises the parser using an array containing each line of iCal content | -| `initString` | `$string` | `protected` | Initialises lines from a string | -| `initUrl` | `$url`, `$username = null`, `$password = null` | `protected` | Initialises lines from a URL. Accepts a username/password combination for HTTP basic authentication | -| `addCalendarComponentWithKeyAndValue` | `$component`, `$keyword`, `$value` | `protected` | Add one key and value pair to the `$this->cal` array | -| `calendarDescription` | - | `public` | Returns the calendar description | -| `calendarName` | - | `public` | Returns the calendar name | -| `calendarTimeZone` | `$ignoreUtc` | `public` | Returns the calendar time zone | -| `cleanData` | `$data` | `protected` | Replaces curly quotes and other special characters with their standard equivalents | -| `convertDayOrdinalToPositive` | `$dayNumber`, `$weekday`, `$timestamp` | `protected` | Converts a negative day ordinal to its equivalent positive form | -| `eventsFromInterval` | `$interval` | `public` | Returns a sorted array of events following a given string, or `false` if no events exist in the range | -| `eventsFromRange` | `$rangeStart = false`, `$rangeEnd = false` | `public` | Returns a sorted array of events in a given range, or an empty array if no events exist in the range | -| `events` | - | `public` | Returns an array of Events | -| `fileOrUrl` | `$filename` | `protected` | Reads an entire file or URL into an array | -| `freeBusyEvents` | - | `public` | Returns an array of arrays with all free/busy events | -| `hasEvents` | - | `public` | Returns a boolean value whether the current calendar has events or not | -| `iCalDateToDateTime` | `$icalDate`, `$forceTimeZone = false`, `$forceUtc = false` | `public` | Returns a `DateTime` object from an iCal date time format | -| `iCalDateToUnixTimestamp` | `$icalDate`, `$forceTimeZone = false`, `$forceUtc = false` | `public` | Returns a Unix timestamp from an iCal date time format | -| `iCalDateWithTimeZone` | `$event`, `$key`, `$format = DATE_TIME_FORMAT` | `public` | Returns a date adapted to the calendar time zone depending on the event `TZID` | -| `isExdateMatch` | `$exdate`, `$anEvent`, `$recurringOffset` | `protected` | Checks if an excluded date matches a given date by reconciling time zones | -| `isFileOrUrl` | `$filename` | `protected` | Checks if a filename exists as a file or URL | -| `isValidDate` | `$value` | `public` | Checks if a date string is a valid date | -| `isValidTimeZoneId` | `$timeZone` | `protected` | Checks if a time zone is valid (IANA or CLDR) | -| `isValidIanaTimeZoneId` | `$timeZone` | `protected` | Checks if a time zone is a valid IANA time zone | -| `isValidCldrTimeZoneId` | `$timeZone`, `doConversion = false` | `protected` | Checks if a time zone is a valid CLDR time zone | -| `keyValueFromString` | `$text` | `protected` | Gets the key value pair from an iCal string | -| `mb_chr` | `$code` | `protected` | Provides a polyfill for PHP 7.2's `mb_chr()`, which is a multibyte safe version of `chr()` | -| `mb_str_replace` | `$search`, `$replace`, `$subject`, `$count = 0` | `protected` | Replaces all occurrences of a search string with a given replacement string | -| `numberOfDays` | `$days`, `$start`, `$end` | `protected` | Gets the number of days between a start and end date | -| `parseDuration` | `$date`, `$duration`, `$format = 'U'` | `protected` | Parses a duration and applies it to a date | -| `parseExdates` | `$event` | `public` | Parses a list of excluded dates to be applied to an Event | -| `processDateConversions` | - | `protected` | Processes date conversions using the time zone | -| `processEventIcalDateTime` | `$event`, `$index = 3` | `protected` | Extends the `{DTSTART\|DTEND\|RECURRENCE-ID}_array` array to include an iCal date time for each event | -| `processEvents` | - | `protected` | Performs admin tasks on all events as read from the iCal file | -| `processRecurrences` | - | `protected` | Processes recurrence rules | -| `removeUnprintableChars` | `$data` | `protected` | Removes unprintable ASCII and UTF-8 characters | -| `sortEventsWithOrder` | `$events`, `$sortOrder = SORT_ASC` | `public` | Sorts events based on a given sort order | -| `trimToRecurrenceCount` | `$rrules`, `$recurrenceEvents` | `protected` | Ensures the recurrence count is enforced against generated recurrence events | -| `unfold` | `$lines` | `protected` | Unfolds an iCal file in preparation for parsing | +| Method | Parameter(s) | Visibility | Description | +|-------------------------------------------------|------------------------------------------------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| `__construct` | `$files = false`, `$options = array()` | `public` | Creates the ICal object | +| `initFile` | `$file` | `protected` | Initialises lines from a file | +| `initLines` | `$lines` | `protected` | Initialises the parser using an array containing each line of iCal content | +| `initString` | `$string` | `protected` | Initialises lines from a string | +| `initUrl` | `$url`, `$username = null`, `$password = null` | `protected` | Initialises lines from a URL. Accepts a username/password combination for HTTP basic authentication | +| `addCalendarComponentWithKeyAndValue` | `$component`, `$keyword`, `$value` | `protected` | Add one key and value pair to the `$this->cal` array | +| `calendarDescription` | - | `public` | Returns the calendar description | +| `calendarName` | - | `public` | Returns the calendar name | +| `calendarTimeZone` | `$ignoreUtc` | `public` | Returns the calendar time zone | +| `cleanData` | `$data` | `protected` | Replaces curly quotes and other special characters with their standard equivalents | +| `convertDayOrdinalToPositive` | `$dayNumber`, `$weekday`, `$timestamp` | `protected` | Converts a negative day ordinal to its equivalent positive form | +| `eventsFromInterval` | `$interval` | `public` | Returns a sorted array of events following a given string, or `false` if no events exist in the range | +| `eventsFromRange` | `$rangeStart = false`, `$rangeEnd = false` | `public` | Returns a sorted array of events in a given range, or an empty array if no events exist in the range | +| `events` | - | `public` | Returns an array of Events | +| `fileOrUrl` | `$filename` | `protected` | Reads an entire file or URL into an array | +| `freeBusyEvents` | - | `public` | Returns an array of arrays with all free/busy events | +| `hasEvents` | - | `public` | Returns a boolean value whether the current calendar has events or not | +| `iCalDateToDateTime` | `$icalDate`, `$forceTimeZone = false`, `$forceUtc = false` | `public` | Returns a `DateTime` object from an iCal date time format | +| `iCalDateToUnixTimestamp` | `$icalDate`, `$forceTimeZone = false`, `$forceUtc = false` | `public` | Returns a Unix timestamp from an iCal date time format | +| `iCalDateWithTimeZone` | `$event`, `$key`, `$format = DATE_TIME_FORMAT` | `public` | Returns a date adapted to the calendar time zone depending on the event `TZID` | +| `isEventStartOutsideWindow` | `$event` | `protected` | Determines whether the event start date is outside `$windowMinTimestamp` / `$windowMaxTimestamp` | +| `isExdateMatch` | `$exdate`, `$anEvent`, `$recurringOffset` | `protected` | Checks if an excluded date matches a given date by reconciling time zones | +| `isFileOrUrl` | `$filename` | `protected` | Checks if a filename exists as a file or URL | +| `isOutOfRange` | `$calendarDate`, `$minTimestamp`, `$maxTimestamp` | `protected` | Determines whether a valid iCalendar date is within a given range | +| `isValidCldrTimeZoneId` | `$timeZone`, `doConversion = false` | `protected` | Checks if a time zone is a valid CLDR time zone | +| `isValidDate` | `$value` | `public` | Checks if a date string is a valid date | +| `isValidIanaTimeZoneId` | `$timeZone` | `protected` | Checks if a time zone is a valid IANA time zone | +| `isValidTimeZoneId` | `$timeZone` | `protected` | Checks if a time zone is valid (IANA or CLDR) | +| `keyValueFromString` | `$text` | `protected` | Gets the key value pair from an iCal string | +| `mb_chr` | `$code` | `protected` | Provides a polyfill for PHP 7.2's `mb_chr()`, which is a multibyte safe version of `chr()` | +| `mb_str_replace` | `$search`, `$replace`, `$subject`, `$count = 0` | `protected` | Replaces all occurrences of a search string with a given replacement string | +| `numberOfDays` | `$days`, `$start`, `$end` | `protected` | Gets the number of days between a start and end date | +| `parseDuration` | `$date`, `$duration`, `$format = 'U'` | `protected` | Parses a duration and applies it to a date | +| `parseExdates` | `$event` | `public` | Parses a list of excluded dates to be applied to an Event | +| `processDateConversions` | - | `protected` | Processes date conversions using the time zone | +| `processEventIcalDateTime` | `$event`, `$index = 3` | `protected` | Extends the `{DTSTART\|DTEND\|RECURRENCE-ID}_array` array to include an iCal date time for each event | +| `processEvents` | - | `protected` | Performs admin tasks on all events as read from the iCal file | +| `processRecurrences` | - | `protected` | Processes recurrence rules | +| `reduceEventsToMinMaxRange` | | `protected` | Reduces the number of events to the defined minimum and maximum range | +| `removeLastEventIfOutsideWindowAndNonRecurring` | | `protected` | Removes the last event (i.e. most recently parsed) if its start date is outside the window spanned by `$windowMinTimestamp` / `$windowMaxTimestamp` | +| `removeUnprintableChars` | `$data` | `protected` | Removes unprintable ASCII and UTF-8 characters | +| `sortEventsWithOrder` | `$events`, `$sortOrder = SORT_ASC` | `public` | Sorts events based on a given sort order | +| `trimToRecurrenceCount` | `$rrules`, `$recurrenceEvents` | `protected` | Ensures the recurrence count is enforced against generated recurrence events | +| `unfold` | `$lines` | `protected` | Unfolds an iCal file in preparation for parsing | #### Constants diff --git a/src/ICal/ICal.php b/src/ICal/ICal.php index 77e2a21..5266062 100644 --- a/src/ICal/ICal.php +++ b/src/ICal/ICal.php @@ -411,20 +411,27 @@ class ICal private $windowsTimeZonesIana; /** - * If $filterDaysBefore or $filterDaysBefore are set then the events are filtered according to the window defined - * by the below two fields. + * If `$filterDaysBefore` or `$filterDaysAfter` are set then the events are filtered according to the window defined + * by this field and `$windowMaxTimestamp`. * - * @var int + * @var integer */ - private $windowMinTimestamp; - private $windowMaxTimestamp; + private $windowMinTimestamp = null; /** - * True if either $filterDaysBefore or $filterDaysAfter are set. + * If `$filterDaysBefore` or `$filterDaysAfter` are set then the events are filtered according to the window defined + * by this field and `$windowMinTimestamp`. + * + * @var integer + */ + private $windowMaxTimestamp = null; + + /** + * True if either `$filterDaysBefore` or `$filterDaysAfter` are set. * * @var boolean */ - private $shouldFilterByWindow; + private $shouldFilterByWindow = false; /** * Creates the ICal object @@ -679,11 +686,11 @@ protected function initLines(array $lines) /** * Removes the last event (i.e. most recently parsed) if its start date is outside the window spanned by - * windowMinTimestamp/windowMaxTimestamp. + * `$windowMinTimestamp` / `$windowMaxTimestamp`. * * @throws \Exception */ - private function removeLastEventIfOutsideWindowAndNonRecurring() + protected function removeLastEventIfOutsideWindowAndNonRecurring() { $events = $this->cal['VEVENT']; @@ -725,14 +732,14 @@ protected function reduceEventsToMinMaxRange() } /** - * Determines whether the event start date is outside the windowMinTimestamp/windowMaxTimestamp. Returns true for - * invalid dates. + * Determines whether the event start date is outside `$windowMinTimestamp` / `$windowMaxTimestamp`. + * Returns true for invalid dates. * - * @param $event + * @param array $event * @return boolean * @throws \Exception */ - private function isEventStartOutsideWindow($event) + protected function isEventStartOutsideWindow(array $event) { return !$this->isValidDate($event['DTSTART']) || $this->isOutOfRange($event['DTSTART'], $this->windowMinTimestamp, $this->windowMaxTimestamp); }