Sabre\VObject\Component Class Reference

Component. More...

Inheritance diagram for Sabre\VObject\Component:

Collaboration diagram for Sabre\VObject\Component:

Public Member Functions
	__construct (Document $root, $name, array $children=[], $defaults=true)
	Creates a new component. More...
	add ()
	Adds a new property or component, and returns the new item. More...
	remove ($item)
	This method removes a component or property from this component. More...
	children ()
	Returns a flat list of all the properties and components in this component. More...
	getComponents ()
	This method only returns a list of sub-components. More...
	select ($name)
	Returns an array with elements that match the specified name. More...
	serialize ()
	Turns the object back into a serialized blob. More...
	jsonSerialize ()
	This method returns an array, with the representation as it should be encoded in JSON. More...
	xmlSerialize (Xml\Writer $writer)
	This method serializes the data into XML. More...
	__isset ($name)
	This method checks if a sub-element with the specified name exists. More...
	__set ($name, $value)
	Using the setter method you can add properties or subcomponents. More...
	__unset ($name)
	Removes all properties and components within this component with the specified name. More...
	__clone ()
	This method is automatically called when the object is cloned. More...
	getValidationRules ()
	validate ($options=0)
	Validates the node for correctness. More...
	destroy ()
	Call this method on a document if you're done using it. More...
Public Member Functions inherited from Sabre\VObject\Node
	serialize ()
	Serializes the node into a mimedir format. More...
	jsonSerialize ()
	This method returns an array, with the representation as it should be encoded in JSON. More...
	xmlSerialize (Xml\Writer $writer)
	This method serializes the data into XML. More...
	destroy ()
	Call this method on a document if you're done using it. More...
	getIterator ()
	Returns the iterator for this object. More...
	setIterator (ElementList $iterator)
	Sets the overridden iterator. More...
	validate ($options=0)
	Validates the node for correctness. More...
	count ()
	Returns the number of elements. More...
	offsetExists ($offset)
	Checks if an item exists through ArrayAccess. More...
	offsetGet ($offset)
	Gets an item through ArrayAccess. More...
	offsetSet ($offset, $value)
	Sets an item through ArrayAccess. More...
	offsetUnset ($offset)
	Sets an item through ArrayAccess. More...
Public Member Functions inherited from Sabre\Xml\XmlSerializable
	xmlSerialize (Writer $writer)
	The xmlSerialize method is called during xml writing. More...

Data Fields
	$name
Data Fields inherited from Sabre\VObject\Node
const	REPAIR = 1
	The following constants are used by the validate() method. More...
const	PROFILE_CARDDAV = 2
	If this option is set, the validator will operate on the vcards on the assumption that the vcards need to be valid for CardDAV. More...
const	PROFILE_CALDAV = 4
	If this option is set, the validator will operate on iCalendar objects on the assumption that the vcards need to be valid for CalDAV. More...
	$parent

Protected Member Functions
	getDefaults ()
	This method should return a list of default property values. More...

Protected Attributes
	$children = []
Protected Attributes inherited from Sabre\VObject\Node
	$iterator = null
	$root

Detailed Description

Component.

A component represents a group of properties, such as VCALENDAR, VEVENT, or VCARD.

Copyright

Copyright (C) fruux GmbH (https://fruux.com/)

Author

Evert Pot (http://evertpot.com/) @license http://sabre.io/license/ Modified BSD License

Definition at line 17 of file Component.php.

Constructor & Destructor Documentation

__construct()

Sabre\VObject\Component::__construct	(	Document	$root,
			$name,
		array	$children = [],
			$defaults = true
	)

Creates a new component.

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

Document	$root
string	$name	such as VCALENDAR, VEVENT.
array	$children
bool	$defaults

Returns

void

Definition at line 53 of file Component.php.

                                                                                        {
 
        $this->name = strtoupper($name);
        $this->root = $root;
 
        if ($defaults) {
            // This is a terribly convoluted way to do this, but this ensures
            // that the order of properties as they are specified in both
            // defaults and the childrens list, are inserted in the object in a
            // natural way.
            $list = $this->getDefaults();
            $nodes = [];
            foreach ($children as $key => $value) {
                if ($value instanceof Node) {
                    if (isset($list[$value->name])) {
                        unset($list[$value->name]);
                    }
                    $nodes[] = $value;
                } else {
                    $list[$key] = $value;
                }
            }
            foreach ($list as $key => $value) {
                $this->add($key, $value);
            }
            foreach ($nodes as $node) {
                $this->add($node);
            }
        } else {
            foreach ($children as $k => $child) {
                if ($child instanceof Node) {
                    // Component or Property
                    $this->add($child);
                } else {
 
                    // Property key=>value
                    $this->add($k, $child);
                }
            }
        }
 
    }

References Sabre\VObject\Component\$children, $key, $list, Sabre\VObject\Component\$name, $nodes, Sabre\VObject\Node\$root, Sabre\VObject\Component\add(), and Sabre\VObject\Component\getDefaults().

Here is the call graph for this function:

Member Function Documentation

__clone()

Sabre\VObject\Component::__clone

(

)

This method is automatically called when the object is cloned.

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

Returns

void

Definition at line 543 of file Component.php.

                       {
 
        foreach ($this->children as $childName => $childGroup) {
            foreach ($childGroup as $key => $child) {
                $clonedChild = clone $child;
                $clonedChild->parent = $this;
                $clonedChild->root = $this->root;
                $this->children[$childName][$key] = $clonedChild;
            }
        }
 
    }

References $key, Sabre\VObject\Node\$root, and Sabre\VObject\Component\children().

Here is the call graph for this function:

__isset()

Sabre\VObject\Component::__isset

(

$name

)

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

Parameters

string

$name

Returns

bool

Definition at line 489 of file Component.php.

                            {
 
        $matches = $this->select($name);
        return count($matches) > 0;
 
    }

References Sabre\VObject\Component\$name, Sabre\VObject\Node\count(), and Sabre\VObject\Component\select().

Here is the call graph for this function:

__set()

Sabre\VObject\Component::__set	(		$name,
			$value
	)

Using the setter method you can add properties or subcomponents.

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

string	$name
mixed	$value

Returns

void

Definition at line 510 of file Component.php.

                                  {
 
        $name = strtoupper($name);
        $this->remove($name);
        if ($value instanceof self || $value instanceof Property) {
            $this->add($value);
        } else {
            $this->add($name, $value);
        }
    }

References Sabre\VObject\Component\$name, and Sabre\VObject\Component\add().

Here is the call graph for this function:

__unset()

Sabre\VObject\Component::__unset

(

$name

)

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

Parameters

string

$name

Returns

void

Definition at line 529 of file Component.php.

                            {
 
        $this->remove($name);
 
    }

References Sabre\VObject\Component\$name.

add()

Sabre\VObject\Component::add

(

)

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

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.

Returns

Node

Definition at line 109 of file Component.php.

                   {
 
        $arguments = func_get_args();
 
        if ($arguments[0] instanceof Node) {
            if (isset($arguments[1])) {
                throw new \InvalidArgumentException('The second argument must not be specified, when passing a VObject Node');
            }
            $arguments[0]->parent = $this;
            $newNode = $arguments[0];
 
        } elseif (is_string($arguments[0])) {
 
            $newNode = call_user_func_array([$this->root, 'create'], $arguments);
 
        } else {
 
            throw new \InvalidArgumentException('The first argument must either be a \\Sabre\\VObject\\Node or a string');
 
        }
 
        $name = $newNode->name;
        if (isset($this->children[$name])) {
            $this->children[$name][] = $newNode;
        } else {
            $this->children[$name] = [$newNode];
        }
        return $newNode;
 
    }

References Sabre\VObject\Component\$name, and Sabre\VObject\Component\children().

Referenced by Sabre\VObject\Component\__construct(), Sabre\VObject\Component\__set(), Sabre\VObject\Parser\XML\createProperty(), Sabre\VObject\Parser\XML\parseComponent(), and Sabre\VObject\Component\validate().

Here is the call graph for this function:

Here is the caller graph for this function:

children()

Sabre\VObject\Component::children

(

)

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

Returns

array

Definition at line 187 of file Component.php.

                        {
 
        $result = [];
        foreach ($this->children as $childGroup) {
            $result = array_merge($result, $childGroup);
        }
        return $result;
 
    }

References $result, and Sabre\VObject\Component\children().

Referenced by Sabre\VObject\Component\__clone(), Sabre\VObject\Component\add(), Sabre\VObject\Component\children(), Sabre\VObject\Component\destroy(), Sabre\VObject\Component\getComponents(), Sabre\VObject\Component\jsonSerialize(), Sabre\VObject\Component\VCard\jsonSerialize(), Sabre\VObject\Component\remove(), Sabre\VObject\Component\select(), Sabre\VObject\Component\serialize(), Sabre\VObject\Cli\serializeComponent(), Sabre\VObject\Component\validate(), Sabre\VObject\Component\xmlSerialize(), and Sabre\VObject\Component\VCard\xmlSerialize().

Here is the call graph for this function:

Here is the caller graph for this function:

destroy()

Sabre\VObject\Component::destroy

(

)

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

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

Returns

void

Reimplemented from Sabre\VObject\Node.

Definition at line 703 of file Component.php.

                       {
 
        parent::destroy();
        foreach ($this->children as $childGroup) {
            foreach ($childGroup as $child) {
                $child->destroy();
            }
        }
        $this->children = [];
 
    }

References Sabre\VObject\Component\children().

Here is the call graph for this function:

getComponents()

Sabre\VObject\Component::getComponents

(

)

This method only returns a list of sub-components.

Properties are ignored.

Returns

array

Definition at line 203 of file Component.php.

                             {
 
        $result = [];
 
        foreach ($this->children as $childGroup) {
            foreach ($childGroup as $child) {
                if ($child instanceof self) {
                    $result[] = $child;
                }
            }
        }
        return $result;
 
    }

References $result, and Sabre\VObject\Component\children().

Here is the call graph for this function:

getDefaults()

Sabre\VObject\Component::getDefaults ( )

protected

This method should return a list of default property values.

Returns

array

Reimplemented in Sabre\VObject\Component\VCalendar, Sabre\VObject\Component\VCard, Sabre\VObject\Component\VEvent, Sabre\VObject\Component\VJournal, Sabre\VObject\Component\VTodo, and Sabre\VObject\FakeComponent.

Definition at line 440 of file Component.php.

                                     {
 
        return [];
 
    }

Referenced by Sabre\VObject\Component\__construct(), and Sabre\VObject\Component\validate().

Here is the caller graph for this function:

getValidationRules()

Sabre\VObject\Component::getValidationRules

(

)

Reimplemented in Sabre\VObject\Component\Available, Sabre\VObject\Component\VAlarm, Sabre\VObject\Component\VAvailability, Sabre\VObject\Component\VCalendar, Sabre\VObject\Component\VCard, Sabre\VObject\Component\VEvent, Sabre\VObject\Component\VFreeBusy, Sabre\VObject\Component\VJournal, Sabre\VObject\Component\VTimeZone, Sabre\VObject\Component\VTodo, and Sabre\VObject\FakeComponent.

Definition at line 577 of file Component.php.

                                  {
 
        return [];
 
    }

Referenced by Sabre\VObject\Component\validate().

Here is the caller graph for this function:

jsonSerialize()

Sabre\VObject\Component::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.

Returns

array

Reimplemented from Sabre\VObject\Node.

Reimplemented in Sabre\VObject\Component\VCard.

Definition at line 360 of file Component.php.

                             {
 
        $components = [];
        $properties = [];
 
        foreach ($this->children as $childGroup) {
            foreach ($childGroup as $child) {
                if ($child instanceof self) {
                    $components[] = $child->jsonSerialize();
                } else {
                    $properties[] = $child->jsonSerialize();
                }
            }
        }
 
        return [
            strtolower($this->name),
            $properties,
            $components
        ];
 
    }

References Sabre\VObject\Component\children().

Here is the call graph for this function:

remove()

Sabre\VObject\Component::remove

(

$item

)

This method removes a component or property from this component.

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

string | Property | Component

$item

Returns

void

Definition at line 151 of file Component.php.

                           {
 
        if (is_string($item)) {
            // If there's no dot in the name, it's an exact property name and
            // we can just wipe out all those properties.
            //
            if (strpos($item, '.') === false) {
                unset($this->children[strtoupper($item)]);
                return;
            }
            // If there was a dot, we need to ask select() to help us out and
            // then we just call remove recursively.
            foreach ($this->select($item) as $child) {
 
                $this->remove($child);
 
            }
        } else {
            foreach ($this->select($item->name) as $k => $child) {
                if ($child === $item) {
                    unset($this->children[$item->name][$k]);
                    return;
                }
            }
        }
 
        throw new \InvalidArgumentException('The item you passed to remove() was not a child of this component');
 
    }

References Sabre\VObject\Component\children(), and Sabre\VObject\Component\select().

Here is the call graph for this function:

select()

Sabre\VObject\Component::select

(

$name

)

Returns an array with elements that match the specified name.

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

string

$name

Returns

array

Definition at line 231 of file Component.php.

                           {
 
        $group = null;
        $name = strtoupper($name);
        if (strpos($name, '.') !== false) {
            list($group, $name) = explode('.', $name, 2);
        }
        if ($name === '') $name = null;
 
        if (!is_null($name)) {
 
            $result = isset($this->children[$name]) ? $this->children[$name] : [];
 
            if (is_null($group)) {
                return $result;
            } else {
                // If we have a group filter as well, we need to narrow it down
                // more.
                return array_filter(
                    $result,
                    function($child) use ($group) {
 
                        return $child instanceof Property && strtoupper($child->group) === $group;
 
                    }
                );
            }
 
        }
 
        // If we got to this point, it means there was no 'name' specified for
        // searching, implying that this is a group-only search.
        $result = [];
        foreach ($this->children as $childGroup) {
 
            foreach ($childGroup as $child) {
 
                if ($child instanceof Property && strtoupper($child->group) === $group) {
                    $result[] = $child;
                }
 
            }
 
        }
        return $result;
 
    }

References Sabre\VObject\Component\$name, $result, and Sabre\VObject\Component\children().

Referenced by Sabre\VObject\Component\__isset(), Sabre\VObject\Component\VCard\getByType(), Sabre\VObject\Component\VFreeBusy\isFree(), Sabre\VObject\Component\VCard\preferred(), Sabre\VObject\Component\remove(), Sabre\VObject\Component\validate(), and Sabre\VObject\Component\VCard\validate().

Here is the call graph for this function:

Here is the caller graph for this function:

serialize()

Sabre\VObject\Component::serialize

(

)

Turns the object back into a serialized blob.

Returns

string

Gives a component a 'score' for sorting purposes.

This is solely used by the childrenSort method.

A higher score means the item will be lower in the list. To avoid score collisions, each "score category" has a reasonable space to accomodate elements. The $key is added to the $score to preserve the original relative order of elements.

Parameters

int	$key
array	$array

Returns

int

Reimplemented from Sabre\VObject\Node.

Definition at line 284 of file Component.php.

                         {
 
        $str = "BEGIN:" . $this->name . "\r\n";
 
        $sortScore = function($key, $array) {
 
            if ($array[$key] instanceof Component) {
 
                // We want to encode VTIMEZONE first, this is a personal
                // preference.
                if ($array[$key]->name === 'VTIMEZONE') {
                    $score = 300000000;
                    return $score + $key;
                } else {
                    $score = 400000000;
                    return $score + $key;
                }
            } else {
                // Properties get encoded first
                // VCARD version 4.0 wants the VERSION property to appear first
                if ($array[$key] instanceof Property) {
                    if ($array[$key]->name === 'VERSION') {
                        $score = 100000000;
                        return $score + $key;
                    } else {
                        // All other properties
                        $score = 200000000;
                        return $score + $key;
                    }
                }
            }
 
        };
 
        $children = $this->children();
        $tmp = $children;
        uksort(
            $children,
            function($a, $b) use ($sortScore, $tmp) {
 
                $sA = $sortScore($a, $tmp);
                $sB = $sortScore($b, $tmp);
 
                return $sA - $sB;
 
            }
        );
 
        foreach ($children as $child) $str .= $child->serialize();
        $str .= "END:" . $this->name . "\r\n";
 
        return $str;
 
    }

References Sabre\VObject\Component\$children, $key, and Sabre\VObject\Component\children().

Referenced by Sabre\VObject\Cli\repair(), and Sabre\VObject\Writer\write().

Here is the call graph for this function:

Here is the caller graph for this function:

validate()

Sabre\VObject\Component::validate

(

$options = 0

)

Validates the node for correctness.

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

int

$options

Returns

array

Reimplemented from Sabre\VObject\Node.

Reimplemented in Sabre\VObject\Component\Available, Sabre\VObject\Component\VAvailability, Sabre\VObject\Component\VCalendar, Sabre\VObject\Component\VCard, and Sabre\VObject\Component\VTodo.

Definition at line 607 of file Component.php.

                                    {
 
        $rules = $this->getValidationRules();
        $defaults = $this->getDefaults();
 
        $propertyCounters = [];
 
        $messages = [];
 
        foreach ($this->children() as $child) {
            $name = strtoupper($child->name);
            if (!isset($propertyCounters[$name])) {
                $propertyCounters[$name] = 1;
            } else {
                $propertyCounters[$name]++;
            }
            $messages = array_merge($messages, $child->validate($options));
        }
 
        foreach ($rules as $propName => $rule) {
 
            switch ($rule) {
                case '0' :
                    if (isset($propertyCounters[$propName])) {
                        $messages[] = [
                            'level'   => 3,
                            'message' => $propName . ' MUST NOT appear in a ' . $this->name . ' component',
                            'node'    => $this,
                        ];
                    }
                    break;
                case '1' :
                    if (!isset($propertyCounters[$propName]) || $propertyCounters[$propName] !== 1) {
                        $repaired = false;
                        if ($options & self::REPAIR && isset($defaults[$propName])) {
                            $this->add($propName, $defaults[$propName]);
                            $repaired = true;
                        }
                        $messages[] = [
                            'level'   => $repaired ? 1 : 3,
                            'message' => $propName . ' MUST appear exactly once in a ' . $this->name . ' component',
                            'node'    => $this,
                        ];
                    }
                    break;
                case '+' :
                    if (!isset($propertyCounters[$propName]) || $propertyCounters[$propName] < 1) {
                        $messages[] = [
                            'level'   => 3,
                            'message' => $propName . ' MUST appear at least once in a ' . $this->name . ' component',
                            'node'    => $this,
                        ];
                    }
                    break;
                case '*' :
                    break;
                case '?' :
                    if (isset($propertyCounters[$propName]) && $propertyCounters[$propName] > 1) {
                        $level = 3;
 
                        // We try to repair the same property appearing multiple times with the exact same value
                        // by removing the duplicates and keeping only one property
                        if ($options & self::REPAIR) {
                            $properties = array_unique($this->select($propName), SORT_REGULAR);
 
                            if (count($properties) === 1) {
                                $this->remove($propName);
                                $this->add($properties[0]);
 
                                $level = 1;
                            }
                        }
 
                        $messages[] = [
                            'level'   => $level,
                            'message' => $propName . ' MUST NOT appear more than once in a ' . $this->name . ' component',
                            'node'    => $this,
                        ];
                    }
                    break;
 
            }
 
        }
        return $messages;
 
    }

References $messages, Sabre\VObject\Component\$name, PHPMailer\PHPMailer\$options, $rule, Sabre\VObject\Component\add(), Sabre\VObject\Component\children(), Sabre\VObject\Node\count(), Sabre\VObject\Component\getDefaults(), Sabre\VObject\Component\getValidationRules(), and Sabre\VObject\Component\select().

Referenced by Sabre\VObject\Cli\repair(), and Sabre\VObject\Cli\validate().

Here is the call graph for this function:

Here is the caller graph for this function:

xmlSerialize()

Sabre\VObject\Component::xmlSerialize

(

Xml\Writer

$writer

)

This method serializes the data into XML.

This is used to create xCard or xCal documents.

Parameters

Xml\Writer

$writer

XML writer.

Returns

void

Reimplemented from Sabre\VObject\Node.

Reimplemented in Sabre\VObject\Component\VCard.

Definition at line 391 of file Component.php.

                                              {
 
        $components = [];
        $properties = [];
 
        foreach ($this->children as $childGroup) {
            foreach ($childGroup as $child) {
                if ($child instanceof self) {
                    $components[] = $child;
                } else {
                    $properties[] = $child;
                }
            }
        }
 
        $writer->startElement(strtolower($this->name));
 
        if (!empty($properties)) {
 
            $writer->startElement('properties');
 
            foreach ($properties as $property) {
                $property->xmlSerialize($writer);
            }
 
            $writer->endElement();
 
        }
 
        if (!empty($components)) {
 
            $writer->startElement('components');
 
            foreach ($components as $component) {
                $component->xmlSerialize($writer);
            }
 
            $writer->endElement();
        }
 
        $writer->endElement();
 
    }

References Sabre\VObject\Component\children().

Referenced by Sabre\VObject\Writer\writeXml().

Here is the call graph for this function:

Here is the caller graph for this function:

Field Documentation

$children

Sabre\VObject\Component::$children = []

protected

Definition at line 33 of file Component.php.

Referenced by Sabre\VObject\Component\__construct(), Sabre\VObject\Document\createComponent(), and Sabre\VObject\Component\serialize().

$name

Sabre\VObject\Component::$name

Definition at line 26 of file Component.php.

Referenced by Sabre\VObject\Component\__construct(), Sabre\VObject\Component\__isset(), Sabre\VObject\Component\__set(), Sabre\VObject\Component\__unset(), Sabre\VObject\Component\add(), Sabre\VObject\Document\create(), Sabre\VObject\Document\createComponent(), Sabre\VObject\Document\createProperty(), Sabre\VObject\Component\select(), and Sabre\VObject\Component\validate().

---

The documentation for this class was generated from the following file:

• libs/composer/vendor/sabre/vobject/lib/Component.php