Documentation

VAvailability extends Component
in package

Application

The VAvailability component.

This component adds functionality to a component, specific for VAVAILABILITY components.

PROFILE_CALDAV

If this option is set, the validator will operate on iCalendar objects on the assumption that the vcards need to be valid for CalDAV.


    public
    mixed
    PROFILE_CALDAV
    = 4

This means for example that calendars can only contain objects with identical component types and UIDs.

PROFILE_CARDDAV

If this option is set, the validator will operate on the vcards on the assumption that the vcards need to be valid for CardDAV.


    public
    mixed
    PROFILE_CARDDAV
    = 2

This means for example that the UID is required, whereas it is not for regular vcards.

REPAIR

The following constants are used by the validate() method.


    public
    mixed
    REPAIR
    = 1

If REPAIR is set, the validator will attempt to repair any broken data (if possible).

$name

Component name.


    public
        string
    $name

This will contain a string such as VEVENT, VTODO, VCALENDAR, VCARD.

$parent

Reference to the parent object, if this is not the top object.


    public
        Node
    $parent

$children

A list of properties and/or sub-components.


    protected
        array<string|int, mixed>
    $children
     = []

$iterator

Iterator override.


    protected
        ElementList
    $iterator
     = null

$root

The root document.


    protected
        Component
    $root

__clone()

This method is automatically called when the object is cloned.


    public
                __clone() : mixed

Specifically, this will ensure all child elements are also cloned.

Return values

mixed —

__construct()

Creates a new component.


    public
                __construct(Document $root, string $name[, array<string|int, mixed> $children = [] ][, bool $defaults = true ]) : mixed

You can specify the children either in key=>value syntax, in which case properties will automatically be created, or you can just pass a list of Component and Property object.

By default, a set of sensible values will be added to the component. For an iCalendar object, this may be something like CALSCALE:GREGORIAN. To ensure that this does not happen, set $defaults to false.

Parameters

$root : Document
$name : string: such as VCALENDAR, VEVENT
$children : array<string|int, mixed> = []
$defaults : bool = true

Return values

mixed —

__get()

Using 'get' you will either get a property or component.


    public
                __get(string $name) : Property

If there were no child-elements found with the specified name, null is returned.

To use this, this may look something like this:

$event = $calendar->VEVENT;

Parameters

$name : string

Return values

Property —

__isset()

This method checks if a sub-element with the specified name exists.


    public
                __isset(string $name) : bool

Parameters

$name : string

Return values

bool —

__set()

Using the setter method you can add properties or subcomponents.


    public
                __set(string $name, mixed $value) : mixed

You can either pass a Component, Property object, or a string to automatically create a Property.

If the item already exists, it will be removed. If you want to add a new item with the same name, always use the add() method.

Parameters

$name : string
$value : mixed

Return values

mixed —

__unset()

Removes all properties and components within this component with the specified name.


    public
                __unset(string $name) : mixed

Parameters

$name : string

Return values

mixed —

add()

Adds a new property or component, and returns the new item.


    public
                add() : Node

This method has 3 possible signatures:

add(Component $comp) // Adds a new component add(Property $prop) // Adds a new property add($name, $value, array $parameters = []) // Adds a new property add($name, array $children = []) // Adds a new component by name.

Return values

Node —

children()

Returns a flat list of all the properties and components in this component.


    public
                children() : array<string|int, mixed>

Return values

array<string|int, mixed> —

count()

Returns the number of elements.


    public
                count() : int

Return values

int —

destroy()

Call this method on a document if you're done using it.


    public
                destroy() : mixed

It's intended to remove all circular references, so PHP can easily clean it up.

Return values

mixed —

getComponents()

This method only returns a list of sub-components. Properties are ignored.


    public
                getComponents() : array<string|int, mixed>

Return values

array<string|int, mixed> —

getEffectiveStartEnd()

Returns the 'effective start' and 'effective end' of this VAVAILABILITY component.


    public
                getEffectiveStartEnd() : array<string|int, mixed>

We use the DTSTART and DTEND or DURATION to determine this.

The returned value is an array containing DateTimeImmutable instances. If either the start or end is 'unbounded' its value will be null instead.

Return values

array<string|int, mixed> —

getIterator()

Returns the iterator for this object.


    public
                getIterator() : ElementList

Return values

ElementList —

getValidationRules()

A simple list of validation rules.


    public
                getValidationRules() : mixed

This is simply a list of properties, and how many times they either must or must not appear.

Possible values per property:

0 - Must not appear.
1 - Must appear exactly once.
- - Must appear at least once.
- - Can appear any number of times.
? - May appear, but not more than once.

Return values

mixed —

isInTimeRange()

Returns true or false depending on if the event falls in the specified time-range. This is used for filtering purposes.


    public
                isInTimeRange(DateTimeInterface $start, DateTimeInterface $end) : bool

The rules used to determine if an event falls within the specified time-range is based on:

https://tools.ietf.org/html/draft-daboo-calendar-availability-05#section-3.1

Parameters

$start : DateTimeInterface
$end : DateTimeInterface

Return values

bool —

jsonSerialize()

This method returns an array, with the representation as it should be encoded in JSON. This is used to create jCard or jCal documents.


    public
    abstract            jsonSerialize() : array<string|int, mixed>

Return values

array<string|int, mixed> —

offsetExists()

Checks if an item exists through ArrayAccess.


    public
                offsetExists(int $offset) : bool

This method just forwards the request to the inner iterator

Parameters

$offset : int

Return values

bool —

offsetGet()

Gets an item through ArrayAccess.


    public
                offsetGet(int $offset) : mixed

This method just forwards the request to the inner iterator

Parameters

$offset : int

Return values

mixed —

offsetSet()

Sets an item through ArrayAccess.


    public
                offsetSet(int $offset, mixed $value) : mixed

This method just forwards the request to the inner iterator

Parameters

$offset : int
$value : mixed

Return values

mixed —

offsetUnset()

Sets an item through ArrayAccess.


    public
                offsetUnset(int $offset) : mixed

This method just forwards the request to the inner iterator

Parameters

$offset : int

Return values

mixed —

remove()

This method removes a component or property from this component.


    public
                remove(string|Property|Component $item) : mixed

You can either specify the item by name (like DTSTART), in which case all properties/components with that name will be removed, or you can pass an instance of a property or component, in which case only that exact item will be removed.

Parameters

$item : string|Property|Component

Return values

mixed —

select()

Returns an array with elements that match the specified name.


    public
                select(string $name) : array<string|int, mixed>

This function is also aware of MIME-Directory groups (as they appear in vcards). This means that if a property is grouped as "HOME.EMAIL", it will also be returned when searching for just "EMAIL". If you want to search for a property in a specific group, you can select on the entire string ("HOME.EMAIL"). If you want to search on a specific property that has not been assigned a group, specify ".EMAIL".

Parameters

$name : string

Return values

array<string|int, mixed> —

serialize()

Serializes the node into a mimedir format.


    public
    abstract            serialize() : string

Return values

string —

setIterator()

Sets the overridden iterator.


    public
                setIterator(ElementList $iterator) : mixed

Note that this is not actually part of the iterator interface

Parameters

$iterator : ElementList

Return values

mixed —

validate()

Validates the node for correctness.


    public
                validate(int $options) : array<string|int, mixed>

The following options are supported: Node::REPAIR - May attempt to automatically repair the problem. Node::PROFILE_CARDDAV - Validate the vCard for CardDAV purposes. Node::PROFILE_CALDAV - Validate the iCalendar for CalDAV purposes.

This method returns an array with detected problems. Every element has the following properties:

level - problem level.
message - A human-readable string describing the issue.
node - A reference to the problematic node.

The level means: 1 - The issue was repaired (only happens if REPAIR was turned on). 2 - A warning. 3 - An error.

Parameters

$options : int

Return values

array<string|int, mixed> —

xmlSerialize()

This method serializes the data into XML. This is used to create xCard or xCal documents.


    public
    abstract            xmlSerialize(Writer $writer) : mixed

Parameters

$writer : Writer: XML writer

Return values

mixed —

getDefaults()

This method should return a list of default property values.


    protected
                getDefaults() : array<string|int, mixed>

Return values

array<string|int, mixed> —