inc/vComponent.php

   1 <?php
   2 /**
   3 * A Class for handling vCalendar & vCard data.
   4 *
   5 * When parsed the underlying structure is roughly as follows:
   6 *
   7 *   vComponent( array(vComponent), array(vProperty) )
   8 *
   9 * @package awl
  10 * @subpackage vComponent
  11 * @author Andrew McMillan <andrew@mcmillan.net.nz>
  12 * @copyright Morphoss Ltd <http://www.morphoss.com/>
  13 * @license   http://gnu.org/copyleft/gpl.html GNU GPL v2 or later
  14 *
  15 */
  16 require_once('XMLElement.php');
  17
  18 /**
  19 * A Class for representing properties within a vComponent (VCALENDAR or VCARD)
  20 *
  21 * @package awl
  22 */
  23 class vProperty {
  24   /**#@+
  25    * @access private
  26    */
  27
  28   /**
  29    * The name of this property
  30    *
  31    * @var string
  32    */
  33   protected $name;
  34
  35   /**
  36    * An array of parameters to this property, represented as key/value pairs.
  37    *
  38    * @var array
  39    */
  40   protected $parameters;
  41
  42   /**
  43    * The value of this property.
  44    *
  45    * @var string
  46    */
  47   protected $content;
  48
  49   /**
  50    * The original value that this was parsed from, if that's the way it happened.
  51    *
  52    * @var string
  53    */
  54   protected $rendered;
  55
  56   /**#@-*/
  57
  58   /**
  59    * The constructor parses the incoming string, which is formatted as per RFC2445 as a
  60    *   propname[;param1=pval1[; ... ]]:propvalue
  61    * however we allow ourselves to assume that the RFC2445 content unescaping has already
  62    * happened when vComponent::ParseFrom() called vComponent::UnwrapComponent().
  63    *
  64    * @param string $propstring The string from the vComponent which contains this property.
  65    */
  66   function __construct( $propstring = null ) {
  67     $this->name = "";
  68     $this->content = "";
  69     $this->parameters = array();
  70     unset($this->rendered);
  71     if ( $propstring != null && gettype($propstring) == 'string' ) {
  72       $this->ParseFrom($propstring);
  73     }
  74   }
  75
  76
  77   /**
  78    * The constructor parses the incoming string, which is formatted as per RFC2445 as a
  79    *   propname[;param1=pval1[; ... ]]:propvalue
  80    * however we allow ourselves to assume that the RFC2445 content unescaping has already
  81    * happened when vComponent::ParseFrom() called vComponent::UnwrapComponent().
  82    *
  83    * @param string $propstring The string from the vComponent which contains this property.
  84    */
  85   function ParseFrom( $propstring ) {
  86     $this->rendered = (strlen($propstring) < 73 ? $propstring : null);  // Only pre-rendered if we didn't unescape it
  87
  88     $unescaped = preg_replace( '{\\\\[nN]}', "\n", $propstring);
  89
  90     // Split into two parts on : which is not preceded by a \
  91     list( $start, $values) = preg_split( '{(?<!\\\\):}', $unescaped, 2);
  92     $this->content = preg_replace( "/\\\\([,;:\"\\\\])/", '$1', $values);
  93
  94     // Split on ; which is not preceded by a \
  95     $parameters = preg_split( '{(?<!\\\\);}', $start);
  96
  97     $this->name = strtoupper(array_shift( $parameters ));
  98     $this->parameters = array();
  99     foreach( $parameters AS $k => $v ) {
 100       $pos = strpos($v,'=');
 101       $name = strtoupper(substr( $v, 0, $pos));
 102       $value = substr( $v, $pos + 1);
 103       $this->parameters[$name] = $value;
 104     }
 105 //    dbg_error_log('vComponent', " vProperty::ParseFrom found '%s' = '%s' with %d parameters", $this->name, substr($this->content,0,200), count($this->parameters) );
 106   }
 107
 108
 109   /**
 110    * Get/Set name property
 111    *
 112    * @param string $newname [optional] A new name for the property
 113    *
 114    * @return string The name for the property.
 115    */
 116   function Name( $newname = null ) {
 117     if ( $newname != null ) {
 118       $this->name = strtoupper($newname);
 119       if ( isset($this->rendered) ) unset($this->rendered);
 120 //      dbg_error_log('vComponent', " vProperty::Name(%s)", $this->name );
 121     }
 122     return $this->name;
 123   }
 124
 125
 126   /**
 127    * Get/Set the content of the property
 128    *
 129    * @param string $newvalue [optional] A new value for the property
 130    *
 131    * @return string The value of the property.
 132    */
 133   function Value( $newvalue = null ) {
 134     if ( $newvalue != null ) {
 135       $this->content = $newvalue;
 136       if ( isset($this->rendered) ) unset($this->rendered);
 137     }
 138     return $this->content;
 139   }
 140
 141
 142   /**
 143    * Get/Set parameters in their entirety
 144    *
 145    * @param array $newparams An array of new parameter key/value pairs
 146    *
 147    * @return array The current array of parameters for the property.
 148    */
 149   function Parameters( $newparams = null ) {
 150     if ( $newparams != null ) {
 151       $this->parameters = array();
 152       foreach( $newparams AS $k => $v ) {
 153         $this->parameters[strtoupper($k)] = $v;
 154       }
 155       if ( isset($this->rendered) ) unset($this->rendered);
 156     }
 157     return $this->parameters;
 158   }
 159
 160
 161   /**
 162    * Test if our value contains a string
 163    *
 164    * @param string $search The needle which we shall search the haystack for.
 165    *
 166    * @return string The name for the property.
 167    */
 168   function TextMatch( $search ) {
 169     if ( isset($this->content) ) return strstr( $this->content, $search );
 170     return false;
 171   }
 172
 173
 174   /**
 175    * Get the value of a parameter
 176    *
 177    * @param string $name The name of the parameter to retrieve the value for
 178    *
 179    * @return string The value of the parameter
 180    */
 181   function GetParameterValue( $name ) {
 182     $name = strtoupper($name);
 183     if ( isset($this->parameters[$name]) ) return $this->parameters[$name];
 184     return null;
 185   }
 186
 187   /**
 188    * Set the value of a parameter
 189    *
 190    * @param string $name The name of the parameter to set the value for
 191    *
 192    * @param string $value The value of the parameter
 193    */
 194   function SetParameterValue( $name, $value ) {
 195     if ( isset($this->rendered) ) unset($this->rendered);
 196     $this->parameters[strtoupper($name)] = $value;
 197   }
 198
 199   /**
 200   * Render the set of parameters as key1=value1[;key2=value2[; ...]] with
 201   * any colons or semicolons escaped.
 202   */
 203   function RenderParameters() {
 204     $rendered = "";
 205     foreach( $this->parameters AS $k => $v ) {
 206       $escaped = preg_replace( "/([;:\"])/", '\\\\$1', $v);
 207       $rendered .= sprintf( ";%s=%s", $k, $escaped );
 208     }
 209     return $rendered;
 210   }
 211
 212
 213   /**
 214   * Render a suitably escaped RFC2445 content string.
 215   */
 216   function Render() {
 217     // If we still have the string it was parsed in from, it hasn't been screwed with
 218     // and we can just return that without modification.
 219     if ( isset($this->rendered) ) return $this->rendered;
 220
 221     $property = preg_replace( '/[;].*$/', '', $this->name );
 222     $escaped = $this->content;
 223     switch( $property ) {
 224         /** Content escaping does not apply to these properties culled from RFC2445 */
 225       case 'ATTACH':                case 'GEO':                       case 'PERCENT-COMPLETE':      case 'PRIORITY':
 226       case 'DURATION':              case 'FREEBUSY':                  case 'TZOFFSETFROM':          case 'TZOFFSETTO':
 227       case 'TZURL':                 case 'ATTENDEE':                  case 'ORGANIZER':             case 'RECURRENCE-ID':
 228       case 'URL':                   case 'EXRULE':                    case 'SEQUENCE':              case 'CREATED':
 229       case 'RRULE':                 case 'REPEAT':                    case 'TRIGGER':               case 'RDATE':
 230       case 'COMPLETED':             case 'DTEND':                     case 'DUE':                   case 'DTSTART':
 231       case 'DTSTAMP':               case 'LAST-MODIFIED':             case 'CREATED':               case 'EXDATE':
 232         break;
 233
 234         /** Content escaping applies by default to other properties */
 235       default:
 236         $escaped = str_replace( '\\', '\\\\', $escaped);
 237         $escaped = preg_replace( '/\r?\n/', '\\n', $escaped);
 238         $escaped = preg_replace( "/([,;\"])/", '\\\\$1', $escaped);
 239     }
 240
 241     $property = sprintf( "%s%s:", $this->name, $this->RenderParameters() );
 242     if ( (strlen($property) + strlen($escaped)) <= 72 ) {
 243       $this->rendered = $property . $escaped;
 244     }
 245     else if ( (strlen($property) + strlen($escaped)) > 72 && (strlen($property) <= 72) && (strlen($escaped) <= 72) ) {
 246       $this->rendered = $property . "\r\n " . $escaped;
 247     }
 248     else {
 249       $this->rendered = preg_replace( '/(.{72})/u', '$1'."\r\n ", $property.$escaped );
 250     }
 251     return $this->rendered;
 252   }
 253
 254
 255   public function __toString() {
 256     return $this->Render();
 257   }
 258
 259
 260   /**
 261    * Test a PROP-FILTER or PARAM-FILTER and return a true/false
 262    * PROP-FILTER (is-defined | is-not-defined | ((time-range | text-match)?, param-filter*))
 263    * PARAM-FILTER (is-defined | is-not-defined | ((time-range | text-match)?, param-filter*))
 264    *
 265    * @param array $filter An array of XMLElement defining the filter
 266    *
 267    * @return boolean Whether or not this vProperty passes the test
 268    */
 269   function TestFilter( $filters ) {
 270     foreach( $filters AS $k => $v ) {
 271       $tag = $v->GetTag();
 272       switch( $tag ) {
 273         case 'urn:ietf:params:xml:ns:caldav:is-defined':
 274         case 'urn:ietf:params:xml:ns:carddav:is-defined':
 275           break;
 276
 277         case 'urn:ietf:params:xml:ns:caldav:is-not-defined':
 278         case 'urn:ietf:params:xml:ns:carddav:is-not-defined':
 279           return false;
 280           break;
 281
 282         case 'urn:ietf:params:xml:ns:caldav:time-range':
 283           /** @todo: While this is unimplemented here at present, most time-range tests should occur at the SQL level. */
 284           break;
 285
 286         case 'urn:ietf:params:xml:ns:carddav:text-match':
 287         case 'urn:ietf:params:xml:ns:caldav:text-match':
 288           $search = $v->GetContent();
 289           $match = $this->TextMatch($search);
 290           $negate = $v->GetAttribute("negate-condition");
 291           if ( isset($negate) && strtolower($negate) == "yes" && $match ) {
 292             return false;
 293           }
 294           if ( ! $match ) return false;
 295           break;
 296
 297         case 'urn:ietf:params:xml:ns:carddav:param-filter':
 298         case 'urn:ietf:params:xml:ns:caldav:param-filter':
 299           $subfilter = $v->GetContent();
 300           $parameter = $this->GetParameterValue($v->GetAttribute("name"));
 301           if ( ! $this->TestParamFilter($subfilter,$parameter) ) return false;
 302           break;
 303
 304         default:
 305           dbg_error_log( 'vComponent', ' vProperty::TestFilter: unhandled tag "%s"', $tag );
 306           break;
 307       }
 308     }
 309     return true;
 310   }
 311
 312
 313   function TestParamFilter( $filters, $parameter_value ) {
 314     foreach( $filters AS $k => $v ) {
 315       $subtag = $v->GetTag();
 316       switch( $subtag ) {
 317         case 'urn:ietf:params:xml:ns:caldav:is-defined':
 318         case 'urn:ietf:params:xml:ns:carddav:is-defined':
 319           break;
 320
 321         case 'urn:ietf:params:xml:ns:caldav:is-not-defined':
 322         case 'urn:ietf:params:xml:ns:carddav:is-not-defined':
 323           return false;
 324           break;
 325
 326         case 'urn:ietf:params:xml:ns:caldav:time-range':
 327           /** @todo: While this is unimplemented here at present, most time-range tests should occur at the SQL level. */
 328           break;
 329
 330         case 'urn:ietf:params:xml:ns:carddav:text-match':
 331         case 'urn:ietf:params:xml:ns:caldav:text-match':
 332           $search = $v->GetContent();
 333           $match = false;
 334           if ( isset($parameter_value) ) $match = strstr( $this->content, $search );
 335           $negate = $v->GetAttribute("negate-condition");
 336           if ( isset($negate) && strtolower($negate) == "yes" && $match ) {
 337             return false;
 338           }
 339           if ( ! $match ) return false;
 340           break;
 341
 342         default:
 343           dbg_error_log( 'vComponent', ' vProperty::TestParamFilter: unhandled tag "%s"', $tag );
 344           break;
 345       }
 346     }
 347     return true;
 348   }
 349 }
 350
 351
 352 /**
 353 * A Class for representing components within an vComponent
 354 *
 355 * @package awl
 356 */
 357 class vComponent {
 358   /**#@+
 359    * @access private
 360    */
 361
 362   /**
 363    * The type of this component, such as 'VEVENT', 'VTODO', 'VTIMEZONE', 'VCARD', etc.
 364    *
 365    * @var string
 366    */
 367   protected $type;
 368
 369   /**
 370    * An array of properties, which are vProperty objects
 371    *
 372    * @var array
 373    */
 374   protected $properties;
 375
 376   /**
 377    * An array of (sub-)components, which are vComponent objects
 378    *
 379    * @var array
 380    */
 381   protected $components;
 382
 383   /**
 384    * The rendered result (or what was originally parsed, if there have been no changes)
 385    *
 386    * @var array
 387    */
 388   protected $rendered;
 389
 390   /**#@-*/
 391
 392   /**
 393   * A basic constructor
 394   */
 395   function __construct( $content = null ) {
 396     $this->type = "";
 397     $this->properties = array();
 398     $this->components = array();
 399     $this->rendered = "";
 400     if ( $content != null && (gettype($content) == 'string' || gettype($content) == 'array') ) {
 401       $this->ParseFrom($content);
 402     }
 403   }
 404
 405
 406   /**
 407   * Collect an array of all parameters of our properties which are the specified type
 408   * Mainly used for collecting the full variety of references TZIDs
 409   */
 410   function CollectParameterValues( $parameter_name ) {
 411     $values = array();
 412     foreach( $this->components AS $k => $v ) {
 413       $also = $v->CollectParameterValues($parameter_name);
 414       $values = array_merge( $values, $also );
 415     }
 416     foreach( $this->properties AS $k => $v ) {
 417       $also = $v->GetParameterValue($parameter_name);
 418       if ( isset($also) && $also != "" ) {
 419 //        dbg_error_log( 'vComponent', "::CollectParameterValues(%s) : Found '%s'", $parameter_name, $also);
 420         $values[$also] = 1;
 421       }
 422     }
 423     return $values;
 424   }
 425
 426
 427   /**
 428   * Parse the text $content into sets of vProperty & vComponent within this vComponent
 429   * @param string $content The raw RFC2445-compliant vComponent component, including BEGIN:TYPE & END:TYPE
 430   */
 431   function ParseFrom( $content ) {
 432     $this->rendered = $content;
 433     $content = $this->UnwrapComponent($content);
 434
 435     $type = false;
 436     $subtype = false;
 437     $finish = null;
 438     $subfinish = null;
 439
 440     $length = strlen($content);
 441     $linefrom = 0;
 442     while( $linefrom < $length ) {
 443       $lineto = strpos( $content, "\n", $linefrom );
 444       if ( $lineto === false ) {
 445         $lineto = strpos( $content, "\r", $linefrom );
 446       }
 447       if ( $lineto > 0 ) {
 448         $line = substr( $content, $linefrom, $lineto - $linefrom);
 449         $linefrom = $lineto + 1;
 450       }
 451       else {
 452         $line = substr( $content, $linefrom );
 453         $linefrom = $length;
 454       }
 455       if ( preg_match('/^\s*$/', $line ) ) continue;
 456       $line = rtrim( $line, "\r\n" );
 457 //      dbg_error_log( 'vComponent',  "::ParseFrom: Parsing line: $line");
 458
 459       if ( $type === false ) {
 460         if ( preg_match( '/^BEGIN:(.+)$/i', $line, $matches ) ) {
 461           // We have found the start of the main component
 462           $type = strtoupper($matches[1]);
 463           $finish = 'END:'.$type;
 464           $this->type = $type;
 465           dbg_error_log( 'vComponent', "::ParseFrom: Start component of type '%s'", $type);
 466         }
 467         else {
 468           dbg_error_log( 'vComponent', "::ParseFrom: Ignoring crap before start of component: $line");
 469           // unset($lines[$k]);  // The content has crap before the start
 470           if ( $line != "" ) $this->rendered = null;
 471         }
 472       }
 473       else if ( $type == null ) {
 474         dbg_error_log( 'vComponent', "::ParseFrom: Ignoring crap after end of component");
 475         if ( $line != "" ) $this->rendered = null;
 476       }
 477       else if ( strtoupper($line) == $finish ) {
 478         dbg_error_log( 'vComponent', "::ParseFrom: End of component");
 479         $type = null;  // We have reached the end of our component
 480       }
 481       else {
 482         if ( $subtype === false && preg_match( '/^BEGIN:(.+)$/i', $line, $matches ) ) {
 483           // We have found the start of a sub-component
 484           $subtype = strtoupper($matches[1]);
 485           $subfinish = "END:$subtype";
 486           $subcomponent = $line . "\r\n";
 487           dbg_error_log( 'vComponent', "::ParseFrom: Found a subcomponent '%s'", $subtype);
 488         }
 489         else if ( $subtype ) {
 490           // We are inside a sub-component
 491           $subcomponent .= $this->WrapComponent($line);
 492           if ( strtoupper($line) == $subfinish ) {
 493             dbg_error_log( 'vComponent', "::ParseFrom: End of subcomponent '%s'", $subtype);
 494             // We have found the end of a sub-component
 495             $this->components[] = new vComponent($subcomponent);
 496             $subtype = false;
 497           }
 498 //          else
 499 //            dbg_error_log( 'vComponent', "::ParseFrom: Inside a subcomponent '%s'", $subtype );
 500         }
 501         else {
 502 //          dbg_error_log( 'vComponent', "::ParseFrom: Parse property of component");
 503           // It must be a normal property line within a component.
 504           $this->properties[] = new vProperty($line);
 505         }
 506       }
 507     }
 508   }
 509
 510
 511   /**
 512     * This unescapes the (CRLF + linear space) wrapping specified in RFC2445. According
 513     * to RFC2445 we should always end with CRLF but the CalDAV spec says that normalising
 514     * XML parsers often muck with it and may remove the CR.  We accept either case.
 515     */
 516   function UnwrapComponent( $content ) {
 517     return preg_replace('/\r?\n[ \t]/', '', $content );
 518   }
 519
 520   /**
 521     * This imposes the (CRLF + linear space) wrapping specified in RFC2445. According
 522     * to RFC2445 we should always end with CRLF but the CalDAV spec says that normalising
 523     * XML parsers often muck with it and may remove the CR.  We output RFC2445 compliance.
 524     *
 525     * In order to preserve pre-existing wrapping in the component, we split the incoming
 526     * string on line breaks before running wordwrap over each component of that.
 527     */
 528   function WrapComponent( $content ) {
 529     $strs = preg_split( "/\r?\n/", $content );
 530     $wrapped = "";
 531     foreach ($strs as $str) {
 532       $wrapped .= preg_replace( '/(.{72})/u', '$1'."\r\n ", $str ) ."\r\n";
 533     }
 534     return $wrapped;
 535   }
 536
 537   /**
 538   * Return the type of component which this is
 539   */
 540   function GetType() {
 541     return $this->type;
 542   }
 543
 544
 545   /**
 546   * Set the type of component which this is
 547   */
 548   function SetType( $type ) {
 549     if ( isset($this->rendered) ) unset($this->rendered);
 550     $this->type = strtoupper($type);
 551     return $this->type;
 552   }
 553
 554
 555   /**
 556   * Return the first instance of a property of this name
 557   */
 558   function GetProperty( $type ) {
 559     foreach( $this->properties AS $k => $v ) {
 560       if ( is_object($v) && $v->Name() == $type ) {
 561         return $v;
 562       }
 563       else if ( !is_object($v) ) {
 564         debug_error_log("ERROR", 'vComponent::GetProperty(): Trying to get %s on %s which is not an object!', $type, $v );
 565       }
 566     }
 567     /** So we can call methods on the result of this, make sure we always return a vProperty of some kind */
 568     return null;
 569   }
 570
 571
 572   /**
 573   * Get all properties, or the properties matching a particular type, or matching an
 574   * array associating property names with true values: array( 'PROPERTY' => true, 'PROPERTY2' => true )
 575   */
 576   function GetProperties( $type = null ) {
 577     $properties = array();
 578     $testtypes = (gettype($type) == 'string' ? array( $type => true ) : $type );
 579     foreach( $this->properties AS $k => $v ) {
 580       if ( $type == null || (isset($testtypes[$v->Name()]) && $testtypes[$v->Name()]) ) {
 581         $properties[] = $v;
 582       }
 583     }
 584     return $properties;
 585   }
 586
 587
 588   /**
 589   * Clear all properties, or the properties matching a particular type
 590   * @param string|array $type The type of property - omit for all properties - or an
 591   * array associating property names with true values: array( 'PROPERTY' => true, 'PROPERTY2' => true )
 592   */
 593   function ClearProperties( $type = null ) {
 594     if ( $type != null ) {
 595       $testtypes = (gettype($type) == 'string' ? array( $type => true ) : $type );
 596       // First remove all the existing ones of that type
 597       foreach( $this->properties AS $k => $v ) {
 598         if ( isset($testtypes[$v->Name()]) && $testtypes[$v->Name()] ) {
 599           unset($this->properties[$k]);
 600           if ( isset($this->rendered) ) unset($this->rendered);
 601         }
 602       }
 603       $this->properties = array_values($this->properties);
 604     }
 605     else {
 606       if ( isset($this->rendered) ) unset($this->rendered);
 607       $this->properties = array();
 608     }
 609   }
 610
 611
 612   /**
 613   * Set all properties, or the ones matching a particular type
 614   */
 615   function SetProperties( $new_properties, $type = null ) {
 616     if ( isset($this->rendered) && count($new_properties) > 0 ) unset($this->rendered);
 617     $this->ClearProperties($type);
 618     foreach( $new_properties AS $k => $v ) {
 619       $this->AddProperty($v);
 620     }
 621   }
 622
 623
 624   /**
 625   * Adds a new property
 626   *
 627   * @param vProperty $new_property The new property to append to the set, or a string with the name
 628   * @param string $value The value of the new property (default: param 1 is an vProperty with everything
 629   * @param array $parameters The key/value parameter pairs (default: none, or param 1 is an vProperty with everything)
 630   */
 631   function AddProperty( $new_property, $value = null, $parameters = null ) {
 632     if ( isset($this->rendered) ) unset($this->rendered);
 633     if ( isset($value) && gettype($new_property) == 'string' ) {
 634       $new_prop = new vProperty();
 635       $new_prop->Name($new_property);
 636       $new_prop->Value($value);
 637       if ( $parameters != null ) $new_prop->Parameters($parameters);
 638       dbg_error_log('vComponent'," Adding new property '%s'", $new_prop->Render() );
 639       $this->properties[] = $new_prop;
 640     }
 641     else if ( gettype($new_property) ) {
 642       $this->properties[] = $new_property;
 643     }
 644   }
 645
 646
 647   /**
 648    * Return number of components
 649    */
 650   function ComponentCount() {
 651     return count($this->components);
 652   }
 653
 654
 655   /**
 656   * Get all sub-components, or at least get those matching a type, or failling to match,
 657   * should the second parameter be set to false. Component types may be a string or an array
 658   * associating property names with true values: array( 'TYPE' => true, 'TYPE2' => true )
 659   *
 660   * @param mixed $type The type(s) to match (default: All)
 661   * @param boolean $normal_match Set to false to invert the match (default: true)
 662   * @return array an array of the sub-components
 663   */
 664   function GetComponents( $type = null, $normal_match = true ) {
 665     $components = $this->components;
 666     if ( $type != null ) {
 667       $testtypes = (gettype($type) == 'string' ? array( $type => true ) : $type );
 668       foreach( $components AS $k => $v ) {
 669 //        printf( "Type: %s, %s, %s\n", $v->GetType(),
 670 //                 ($normal_match && isset($testtypes[$v->GetType()]) && $testtypes[$v->GetType()] ? 'true':'false'),
 671 //                 ( !$normal_match && (!isset($testtypes[$v->GetType()]) || !$testtypes[$v->GetType()]) ? 'true':'false')
 672 //               );
 673         if ( !($normal_match && isset($testtypes[$v->GetType()]) && $testtypes[$v->GetType()] )
 674             && !( !$normal_match && (!isset($testtypes[$v->GetType()]) || !$testtypes[$v->GetType()])) ) {
 675           unset($components[$k]);
 676         }
 677       }
 678       $components = array_values($components);
 679     }
 680 //    print_r($components);
 681     return $components;
 682   }
 683
 684
 685   /**
 686   * Clear all components, or the components matching a particular type
 687   * @param string $type The type of component - omit for all components
 688   */
 689   function ClearComponents( $type = null ) {
 690     if ( $type != null ) {
 691       $testtypes = (gettype($type) == 'string' ? array( $type => true ) : $type );
 692       // First remove all the existing ones of that type
 693       foreach( $this->components AS $k => $v ) {
 694         if ( isset($testtypes[$v->GetType()]) && $testtypes[$v->GetType()] ) {
 695           unset($this->components[$k]);
 696           if ( isset($this->rendered) ) unset($this->rendered);
 697         }
 698         else {
 699           if ( ! $this->components[$k]->ClearComponents($testtypes) ) {
 700             if ( isset($this->rendered) ) unset($this->rendered);
 701           }
 702         }
 703       }
 704       return isset($this->rendered);
 705     }
 706     else {
 707       if ( isset($this->rendered) ) unset($this->rendered);
 708       $this->components = array();
 709     }
 710   }
 711
 712
 713   /**
 714   * Sets some or all sub-components of the component to the supplied new components
 715   *
 716   * @param array of vComponent $new_components The new components to replace the existing ones
 717   * @param string $type The type of components to be replaced.  Defaults to null, which means all components will be replaced.
 718   */
 719   function SetComponents( $new_component, $type = null ) {
 720     if ( isset($this->rendered) ) unset($this->rendered);
 721     $this->ClearComponents($type);
 722     foreach( $new_component AS $k => $v ) {
 723       $this->components[] = $v;
 724     }
 725   }
 726
 727
 728   /**
 729   * Adds a new subcomponent
 730   *
 731   * @param vComponent $new_component The new component to append to the set
 732   */
 733   function AddComponent( $new_component ) {
 734     if ( is_array($new_component) && count($new_component) == 0 ) return;
 735     if ( isset($this->rendered) ) unset($this->rendered);
 736     if ( is_array($new_component) ) {
 737       foreach( $new_component AS $k => $v ) {
 738         $this->components[] = $v;
 739       }
 740     }
 741     else {
 742       $this->components[] = $new_component;
 743     }
 744   }
 745
 746
 747   /**
 748   * Mask components, removing any that are not of the types in the list
 749   * @param array $keep An array of component types to be kept
 750   */
 751   function MaskComponents( $keep ) {
 752     foreach( $this->components AS $k => $v ) {
 753       if ( !isset($keep[$v->GetType()]) || !$keep[$v->GetType()] ) {
 754         unset($this->components[$k]);
 755         if ( isset($this->rendered) ) unset($this->rendered);
 756       }
 757       else {
 758         $v->MaskComponents($keep);
 759       }
 760     }
 761   }
 762
 763
 764   /**
 765   * Mask properties, removing any that are not in the list
 766   * @param array $keep An array of property names to be kept
 767   * @param array $component_list An array of component types to check within
 768   */
 769   function MaskProperties( $keep, $component_list=null ) {
 770     if ( !isset($component_list) || $component_list[$this->GetType()] ) {
 771       foreach( $this->properties AS $k => $v ) {
 772         if ( !isset($keep[$v->Name()]) || !$keep[$v->Name()] ) {
 773           unset($this->properties[$k]);
 774           if ( isset($this->rendered) ) unset($this->rendered);
 775         }
 776       }
 777     }
 778     foreach( $this->components AS $k => $v ) {
 779       $v->MaskProperties($keep, $component_list);
 780     }
 781   }
 782
 783
 784   /**
 785   *  Renders the component, possibly restricted to only the listed properties
 786   */
 787   function Render( $restricted_properties = null) {
 788
 789     $unrestricted = (!isset($restricted_properties) || count($restricted_properties) == 0);
 790
 791     if ( isset($this->rendered) && $unrestricted )
 792       return $this->rendered;
 793
 794     $rendered = "BEGIN:$this->type\r\n";
 795     foreach( $this->properties AS $k => $v ) {
 796       if ( method_exists($v, 'Render') ) {
 797         if ( $unrestricted || isset($restricted_properties[$v]) ) $rendered .= $v->Render() . "\r\n";
 798       }
 799     }
 800     foreach( $this->components AS $v ) {   $rendered .= $v->Render();  }
 801     $rendered .= "END:$this->type\r\n";
 802
 803     if ( $unrestricted ) $this->rendered = $rendered;
 804
 805     return $rendered;
 806   }
 807
 808
 809
 810   public function __toString() {
 811     return $this->Render();
 812   }
 813
 814
 815   /**
 816   * Return an array of properties matching the specified path
 817   *
 818   * @return array An array of vProperty within the tree which match the path given, in the form
 819   *  [/]COMPONENT[/...]/PROPERTY in a syntax kind of similar to our poor man's XML queries. We
 820   *  also allow COMPONENT and PROPERTY to be !COMPONENT and !PROPERTY for ++fun.
 821   *
 822   * @note At some point post PHP4 this could be re-done with an iterator, which should be more efficient for common use cases.
 823   */
 824   function GetPropertiesByPath( $path ) {
 825     $properties = array();
 826     dbg_error_log( 'vComponent', "GetPropertiesByPath: Querying within '%s' for path '%s'", $this->type, $path );
 827     if ( !preg_match( '#(/?)(!?)([^/]+)(/?.*)$#', $path, $matches ) ) return $properties;
 828
 829     $anchored = ($matches[1] == '/');
 830     $inverted = ($matches[2] == '!');
 831     $ourtest = $matches[3];
 832     $therest = $matches[4];
 833     dbg_error_log( 'vComponent', "GetPropertiesByPath: Matches: %s -- %s -- %s -- %s\n", $matches[1], $matches[2], $matches[3], $matches[4] );
 834     if ( $ourtest == '*' || (($ourtest == $this->type) !== $inverted) && $therest != '' ) {
 835       if ( preg_match( '#^/(!?)([^/]+)$#', $therest, $matches ) ) {
 836         $normmatch = ($matches[1] =='');
 837         $proptest  = $matches[2];
 838         foreach( $this->properties AS $k => $v ) {
 839           if ( $proptest == '*' || (($v->Name() == $proptest) === $normmatch ) ) {
 840             $properties[] = $v;
 841           }
 842         }
 843       }
 844       else {
 845         /**
 846         * There is more to the path, so we recurse into that sub-part
 847         */
 848         foreach( $this->components AS $k => $v ) {
 849           $properties = array_merge( $properties, $v->GetPropertiesByPath($therest) );
 850         }
 851       }
 852     }
 853
 854     if ( ! $anchored ) {
 855       /**
 856       * Our input $path was not rooted, so we recurse further
 857       */
 858       foreach( $this->components AS $k => $v ) {
 859         $properties = array_merge( $properties, $v->GetPropertiesByPath($path) );
 860       }
 861     }
 862     dbg_error_log('vComponent', "GetPropertiesByPath: Found %d within '%s' for path '%s'\n", count($properties), $this->type, $path );
 863     return $properties;
 864   }
 865
 866
 867
 868   /**
 869    * Test a PROP-FILTER or COMP-FILTER and return a true/false
 870    * COMP-FILTER (is-defined | is-not-defined | (time-range?, prop-filter*, comp-filter*))
 871    * PROP-FILTER (is-defined | is-not-defined | ((time-range | text-match)?, param-filter*))
 872    *
 873    * @param array $filter An array of XMLElement defining the filter
 874    *
 875    * @return boolean Whether or not this vComponent passes the test
 876    */
 877   function TestFilter( $filters ) {
 878     foreach( $filters AS $k => $v ) {
 879       $tag = $v->GetTag();
 880       switch( $tag ) {
 881         case 'urn:ietf:params:xml:ns:caldav:is-defined':
 882         case 'urn:ietf:params:xml:ns:carddav:is-defined':
 883           break;
 884
 885         case 'urn:ietf:params:xml:ns:caldav:is-not-defined':
 886         case 'urn:ietf:params:xml:ns:carddav:is-not-defined':
 887           return false;
 888           break;
 889
 890         case 'urn:ietf:params:xml:ns:caldav:comp-filter':
 891           $subfilter = $v->GetContent();
 892           $subcomponents = $this->GetComponents($v->GetAttribute("name"));
 893           if ( count($subcomponents) > 0 ) {
 894             foreach( $subcomponents AS $kk => $subcomponent ) {
 895               if ( ! $subcomponent->TestFilter($subfilter) ) return false;
 896             }
 897           }
 898           else {
 899             if ( $subfilter[0] == 'urn:ietf:params:xml:ns:caldav:is-defined'
 900                  || $subfilter[0] == 'urn:ietf:params:xml:ns:carddav:is-defined' ) {
 901               return false;
 902             }
 903           }
 904           break;
 905
 906         case 'urn:ietf:params:xml:ns:carddav:prop-filter':
 907         case 'urn:ietf:params:xml:ns:caldav:prop-filter':
 908           $subfilter = $v->GetContent();
 909           $properties = $this->GetProperties($v->GetAttribute("name"));
 910           if ( count($properties) > 0 ) {
 911             foreach( $properties AS $kk => $property ) {
 912               if ( !$property->TestFilter($subfilter) ) return false;
 913             }
 914           }
 915           else {
 916             if ( $subfilter[0] == 'urn:ietf:params:xml:ns:caldav:is-defined'
 917                  || $subfilter[0] == 'urn:ietf:params:xml:ns:carddav:is-defined' ) {
 918               return false;
 919             }
 920           }
 921           break;
 922       }
 923     }
 924     return true;
 925   }
 926
 927 }
 928