Skip to content

Sabre VObject Document

Jump to bottom Edit New page
Evert Pot edited this page Sep 1, 2014 · 5 revisions

Sabre\VObject\Document

Document

A document is just like a component, except that it's also the top level element.

Both a VCALENDAR and a VCARD are considered documents.

This class also provides a registry for document types.

Constants

UNKNOWN

const UNKNOWN = 1

VCALENDAR10

const VCALENDAR10 = 2

ICALENDAR20

const ICALENDAR20 = 3

VCARD21

const VCARD21 = 4

VCARD30

const VCARD30 = 5

VCARD40

const VCARD40 = 6

REPAIR

const REPAIR = 1

Properties

$defaultName

public string $defaultName

The default name for this component.

This should be 'VCALENDAR' or 'VCARD'.

  • Visibility: public
  • This property is static.

$propertyMap

public array $propertyMap = array()

List of properties, and which classes they map to.

  • Visibility: public
  • This property is static.

$componentMap

public array $componentMap = array()

List of components, along with which classes they map to.

  • Visibility: public
  • This property is static.

$valueMap

public array $valueMap = array()

List of value-types, and which classes they map to.

  • Visibility: public
  • This property is static.

$name

public string $name

Component name.

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

  • Visibility: public

$children

public array $children = array()

A list of properties and/or sub-components.

  • Visibility: public

$parent

public \Sabre\VObject\Node $parent

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

  • Visibility: public

$iterator

protected \Sabre\VObject\ElementList $iterator = null

Iterator override

  • Visibility: protected

$root

protected \Sabre\VObject\Component $root

The root document

  • Visibility: protected

Methods

__construct

void Sabre\VObject\Component::__construct(\Sabre\VObject\Document $root, string $name, array $children, boolean $defaults)

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.

Arguments

  • $root Sabre\VObject\Document
  • $name string - <p>such as VCALENDAR, VEVENT.</p>
  • $children array
  • $defaults boolean

getDocumentType

void Sabre\VObject\Document::getDocumentType()

Returns the current document type.

  • Visibility: public

create

mixed Sabre\VObject\Document::create(string $name)

Creates a new component or property.

If it's a known component, we will automatically call createComponent. otherwise, we'll assume it's a property and call createProperty instead.

  • Visibility: public

Arguments

  • $name string

createComponent

\Sabre\VObject\Component Sabre\VObject\Document::createComponent(string $name, array $children, boolean $defaults)

Creates a new component

This method automatically searches for the correct component class, based on its name.

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.

  • Visibility: public

Arguments

  • $name string
  • $children array
  • $defaults boolean

createProperty

\Sabre\VObject\Property Sabre\VObject\Document::createProperty(string $name, mixed $value, array $parameters, string $valueType)

Factory method for creating new properties

This method automatically searches for the correct property class, based on its name.

You can specify the parameters either in key=>value syntax, in which case parameters will automatically be created, or you can just pass a list of Parameter objects.

  • Visibility: public

Arguments

  • $name string
  • $value mixed
  • $parameters array
  • $valueType string - <p>Force a specific valuetype, such as URI or TEXT</p>

getClassNameForPropertyValue

void Sabre\VObject\Document::getClassNameForPropertyValue(string $valueParam)

This method returns a full class-name for a value parameter.

For instance, DTSTART may have VALUE=DATE. In that case we will look in our valueMap table and return the appropriate class name.

This method returns null if we don't have a specialized class.

  • Visibility: public

Arguments

  • $valueParam string

getClassNameForPropertyName

string Sabre\VObject\Document::getClassNameForPropertyName(string $propertyName)

Returns the default class for a property name.

  • Visibility: public

Arguments

  • $propertyName string

add

\Sabre\VObject\Node Sabre\VObject\Component::add($a1, $a2, $a3)

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 = array()) // Adds a new property add($name, array $children = array()) // Adds a new component by name.

Arguments

  • $a1 mixed
  • $a2 mixed
  • $a3 mixed

remove

void Sabre\VObject\Component::remove(mixed $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.

The removed item will be returned. In case there were more than 1 items removed, only the last one will be returned.

Arguments

  • $item mixed

children

array Sabre\VObject\Component::children()

Returns an iterable list of children

getComponents

array Sabre\VObject\Component::getComponents()

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

select

array Sabre\VObject\Component::select(string $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".

Keys are retained from the 'children' array, which may be confusing in certain cases.

Arguments

  • $name string

serialize

string Sabre\VObject\Node::serialize()

Serializes the node into a mimedir format

  • Visibility: public
  • This method is abstract.
  • This method is defined by Sabre\VObject\Node

jsonSerialize

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

  • Visibility: public
  • This method is abstract.
  • This method is defined by Sabre\VObject\Node

getDefaults

array Sabre\VObject\Component::getDefaults()

This method should return a list of default property values.

__get

\Sabre\VObject\Property Sabre\VObject\Component::__get(string $name)

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

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;

Arguments

  • $name string

__isset

boolean Sabre\VObject\Component::__isset(string $name)

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

Arguments

  • $name string

__set

void Sabre\VObject\Component::__set(string $name, mixed $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.

Arguments

  • $name string
  • $value mixed

__unset

void Sabre\VObject\Component::__unset(string $name)

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

Arguments

  • $name string

__clone

void Sabre\VObject\Component::__clone()

This method is automatically called when the object is cloned.

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

getValidationRules

mixed Sabre\VObject\Component::getValidationRules()

A simple list of validation rules.

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.

It is also possible to specify defaults and severity levels for violating the rule.

See the VEVENT implementation for getValidationRules for a more complex example.

validate

array Sabre\VObject\Node::validate(integer $options)

Validates the node for correctness.

The following options are supported: Node::REPAIR - May attempt to automatically repair the problem.

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 - An inconsequential issue 3 - A severe issue.

Arguments

  • $options integer

getIterator

\Sabre\VObject\ElementList Sabre\VObject\Node::getIterator()

Returns the iterator for this object

setIterator

void Sabre\VObject\Node::setIterator(\Sabre\VObject\ElementList $iterator)

Sets the overridden iterator

Note that this is not actually part of the iterator interface

Arguments

count

integer Sabre\VObject\Node::count()

Returns the number of elements

offsetExists

boolean Sabre\VObject\Node::offsetExists(integer $offset)

Checks if an item exists through ArrayAccess.

This method just forwards the request to the inner iterator

Arguments

  • $offset integer

offsetGet

mixed Sabre\VObject\Node::offsetGet(integer $offset)

Gets an item through ArrayAccess.

This method just forwards the request to the inner iterator

Arguments

  • $offset integer

offsetSet

void Sabre\VObject\Node::offsetSet(integer $offset, mixed $value)

Sets an item through ArrayAccess.

This method just forwards the request to the inner iterator

Arguments

  • $offset integer
  • $value mixed

offsetUnset

void Sabre\VObject\Node::offsetUnset(integer $offset)

Sets an item through ArrayAccess.

This method just forwards the request to the inner iterator

Arguments

  • $offset integer
Add a custom footer
Add a custom sidebar
Clone this wiki locally