6 * A property in VObject is usually in the form PARAMNAME:paramValue.
7 * An example is : SUMMARY:Weekly meeting
9 * Properties can also have parameters:
10 * SUMMARY;LANG=en:Weekly meeting.
12 * Parameters can be accessed using the ArrayAccess interface.
16 * @copyright Copyright (C) 2007-2012 Rooftop Solutions. All rights reserved.
17 * @author Evert Pot (http://www.rooftopsolutions.nl/)
18 * @license http://code.google.com/p/sabredav/wiki/License Modified BSD License
20 class Sabre_VObject_Property extends Sabre_VObject_Element {
32 * This may be something like 'HOME' for vcards.
43 public $parameters = array();
53 * If properties are added to this map, they will be automatically mapped
54 * to their respective classes, if parsed by the reader or constructed with
55 * the 'create' method.
59 static public $classMap = array(
60 'COMPLETED' => 'Sabre_VObject_Property_DateTime',
61 'CREATED' => 'Sabre_VObject_Property_DateTime',
62 'DTEND' => 'Sabre_VObject_Property_DateTime',
63 'DTSTAMP' => 'Sabre_VObject_Property_DateTime',
64 'DTSTART' => 'Sabre_VObject_Property_DateTime',
65 'DUE' => 'Sabre_VObject_Property_DateTime',
66 'EXDATE' => 'Sabre_VObject_Property_MultiDateTime',
67 'LAST-MODIFIED' => 'Sabre_VObject_Property_DateTime',
68 'RECURRENCE-ID' => 'Sabre_VObject_Property_DateTime',
69 'TRIGGER' => 'Sabre_VObject_Property_DateTime',
73 * Creates the new property by name, but in addition will also see if
74 * there's a class mapped to the property name.
77 * @param string $value
78 * @return Sabre_VObject_Property
80 static public function create($name, $value = null) {
82 $name = strtoupper($name);
85 if (strpos($shortName,'.')!==false) {
86 list($group, $shortName) = explode('.', $shortName);
89 if (isset(self::$classMap[$shortName])) {
90 return new self::$classMap[$shortName]($name, $value);
92 return new self($name, $value);
98 * Creates a new property object
100 * By default this object will iterate over its own children, but this can
101 * be overridden with the iterator argument
103 * @param string $name
104 * @param string $value
105 * @param Sabre_VObject_ElementList $iterator
107 public function __construct($name, $value = null, $iterator = null) {
109 $name = strtoupper($name);
111 if (strpos($name,'.')!==false) {
112 list($group, $name) = explode('.', $name);
115 $this->group = $group;
116 if (!is_null($iterator)) $this->iterator = $iterator;
117 $this->setValue($value);
124 * Updates the internal value
126 * @param string $value
129 public function setValue($value) {
131 $this->value = $value;
136 * Turns the object back into a serialized blob.
140 public function serialize() {
143 if ($this->group) $str = $this->group . '.' . $this->name;
145 if (count($this->parameters)) {
146 foreach($this->parameters as $param) {
148 $str.=';' . $param->serialize();
160 $str.=':' . str_replace($src, $out, $this->value);
163 while(strlen($str)>0) {
164 if (strlen($str)>75) {
165 $out.= mb_strcut($str,0,75,'utf-8') . "\r\n";
166 $str = ' ' . mb_strcut($str,75,strlen($str),'utf-8');
179 * Adds a new componenten or element
181 * You can call this method with the following syntaxes:
183 * add(Sabre_VObject_Parameter $element)
184 * add(string $name, $value)
186 * The first version adds an Parameter
187 * The second adds a property as a string.
190 * @param mixed $itemValue
193 public function add($item, $itemValue = null) {
195 if ($item instanceof Sabre_VObject_Parameter) {
196 if (!is_null($itemValue)) {
197 throw new InvalidArgumentException('The second argument must not be specified, when passing a VObject');
199 $item->parent = $this;
200 $this->parameters[] = $item;
201 } elseif(is_string($item)) {
203 if (!is_scalar($itemValue) && !is_null($itemValue)) {
204 throw new InvalidArgumentException('The second argument must be scalar');
206 $parameter = new Sabre_VObject_Parameter($item,$itemValue);
207 $parameter->parent = $this;
208 $this->parameters[] = $parameter;
212 throw new InvalidArgumentException('The first argument must either be a Sabre_VObject_Element or a string');
218 /* ArrayAccess interface {{{ */
221 * Checks if an array element exists
226 public function offsetExists($name) {
228 if (is_int($name)) return parent::offsetExists($name);
230 $name = strtoupper($name);
232 foreach($this->parameters as $parameter) {
233 if ($parameter->name == $name) return true;
240 * Returns a parameter, or parameter list.
242 * @param string $name
243 * @return Sabre_VObject_Element
245 public function offsetGet($name) {
247 if (is_int($name)) return parent::offsetGet($name);
248 $name = strtoupper($name);
251 foreach($this->parameters as $parameter) {
252 if ($parameter->name == $name)
253 $result[] = $parameter;
256 if (count($result)===0) {
258 } elseif (count($result)===1) {
261 $result[0]->setIterator(new Sabre_VObject_ElementList($result));
268 * Creates a new parameter
270 * @param string $name
271 * @param mixed $value
274 public function offsetSet($name, $value) {
276 if (is_int($name)) parent::offsetSet($name, $value);
278 if (is_scalar($value)) {
279 if (!is_string($name))
280 throw new InvalidArgumentException('A parameter name must be specified. This means you cannot use the $array[]="string" to add parameters.');
282 $this->offsetUnset($name);
283 $parameter = new Sabre_VObject_Parameter($name, $value);
284 $parameter->parent = $this;
285 $this->parameters[] = $parameter;
287 } elseif ($value instanceof Sabre_VObject_Parameter) {
289 throw new InvalidArgumentException('Don\'t specify a parameter name if you\'re passing a Sabre_VObject_Parameter. Add using $array[]=$parameterObject.');
291 $value->parent = $this;
292 $this->parameters[] = $value;
294 throw new InvalidArgumentException('You can only add parameters to the property object');
300 * Removes one or more parameters with the specified name
302 * @param string $name
305 public function offsetUnset($name) {
307 if (is_int($name)) parent::offsetUnset($name);
308 $name = strtoupper($name);
310 foreach($this->parameters as $key=>$parameter) {
311 if ($parameter->name == $name) {
312 $parameter->parent = null;
313 unset($this->parameters[$key]);
323 * Called when this object is being cast to a string
327 public function __toString() {
329 return (string)$this->value;
334 * This method is automatically called when the object is cloned.
335 * Specifically, this will ensure all child elements are also cloned.
339 public function __clone() {
341 foreach($this->parameters as $key=>$child) {
342 $this->parameters[$key] = clone $child;
343 $this->parameters[$key]->parent = $this;