inc/iCalendar.php

   1 <?php
   2 /**
   3 * A Class for handling iCalendar data.
   4 *
   5 * When parsed the underlying structure is roughly as follows:
   6 *
   7 *   iCalendar( array(iCalComponent), array(iCalProp) )
   8 *
   9 * each iCalComponent is similarly structured:
  10 *
  11 *   iCalComponent( array(iCalComponent), array(iCalProp) )
  12 *
  13 * Once parsed, $ical->component will point to the wrapping VCALENDAR component of
  14 * the iCalendar.  This will be fine for simple iCalendar usage as sampled below,
  15 * but more complex iCalendar such as a VEVENT with RRULE which has repeat overrides
  16 * will need quite a bit more thought to process correctly.
  17 *
  18 * @example
  19 * To create a new iCalendar from several data values:
  20 *   $ical = new iCalendar( array('DTSTART' => $dtstart, 'SUMMARY' => $summary, 'DURATION' => $duration ) );
  21 *
  22 * @example
  23 * To render it as an iCalendar string:
  24 *   echo $ical->Render();
  25 *
  26 * @example
  27 * To render just the VEVENTs in the iCalendar with a restricted list of properties:
  28 *   echo $ical->Render( false, 'VEVENT', array( 'DTSTART', 'DURATION', 'DTEND', 'RRULE', 'SUMMARY') );
  29 *
  30 * @example
  31 * To parse an existing iCalendar string for manipulation:
  32 *   $ical = new iCalendar( array('icalendar' => $icalendar_text ) );
  33 *
  34 * @example
  35 * To clear any 'VALARM' components in an iCalendar object
  36 *   $ical->component->ClearComponents('VALARM');
  37 *
  38 * @example
  39 * To replace any 'RRULE' property in an iCalendar object
  40 *   $ical->component->SetProperties( 'RRULE', $rrule_definition );
  41 *
  42 * @package awl
  43 * @subpackage iCalendar
  44 * @author Andrew McMillan <andrew@mcmillan.net.nz>
  45 * @copyright Catalyst IT Ltd, Morphoss Ltd <http://www.morphoss.com/>
  46 * @license   http://gnu.org/copyleft/gpl.html GNU GPL v2 or later
  47 *
  48 */
  49 require_once('XMLElement.php');
  50 require_once('AwlQuery.php');
  51
  52 /**
  53 * A Class for representing properties within an iCalendar
  54 *
  55 * @package awl
  56 */
  57 class iCalProp {
  58   /**#@+
  59    * @access private
  60    */
  61
  62   /**
  63    * The name of this property
  64    *
  65    * @var string
  66    */
  67   var $name;
  68
  69   /**
  70    * An array of parameters to this property, represented as key/value pairs.
  71    *
  72    * @var array
  73    */
  74   var $parameters;
  75
  76   /**
  77    * The value of this property.
  78    *
  79    * @var string
  80    */
  81   var $content;
  82
  83   /**
  84    * The original value that this was parsed from, if that's the way it happened.
  85    *
  86    * @var string
  87    */
  88   var $rendered;
  89
  90   /**#@-*/
  91
  92   /**
  93    * The constructor parses the incoming string, which is formatted as per RFC2445 as a
  94    *   propname[;param1=pval1[; ... ]]:propvalue
  95    * however we allow ourselves to assume that the RFC2445 content unescaping has already
  96    * happened when iCalComponent::ParseFrom() called iCalComponent::UnwrapComponent().
  97    *
  98    * @param string $propstring The string from the iCalendar which contains this property.
  99    */
 100   function iCalProp( $propstring = null ) {
 101     $this->name = "";
 102     $this->content = "";
 103     $this->parameters = array();
 104     unset($this->rendered);
 105     if ( $propstring != null && gettype($propstring) == 'string' ) {
 106       $this->ParseFrom($propstring);
 107     }
 108   }
 109
 110
 111   /**
 112    * The constructor parses the incoming string, which is formatted as per RFC2445 as a
 113    *   propname[;param1=pval1[; ... ]]:propvalue
 114    * however we allow ourselves to assume that the RFC2445 content unescaping has already
 115    * happened when iCalComponent::ParseFrom() called iCalComponent::UnwrapComponent().
 116    *
 117    * @param string $propstring The string from the iCalendar which contains this property.
 118    */
 119   function ParseFrom( $propstring ) {
 120     $this->rendered = (strlen($propstring) < 72 ? $propstring : null);  // Only pre-rendered if we didn't unescape it
 121
 122     $unescaped = preg_replace( '{\\\\[nN]}', "\n", $propstring);
 123
 124     // Split into two parts on : which is not preceded by a \
 125     list( $start, $values) = @preg_split( '{(?<!\\\\):}', $unescaped, 2);
 126     $this->content = preg_replace( "/\\\\([,;:\"\\\\])/", '$1', $values);
 127
 128     // Split on ; which is not preceded by a \
 129     $parameters = preg_split( '{(?<!\\\\);}', $start);
 130
 131     $parameters = explode(';',$start);
 132     $this->name = array_shift( $parameters );
 133     $this->parameters = array();
 134     foreach( $parameters AS $k => $v ) {
 135       $pos = strpos($v,'=');
 136       $name = substr( $v, 0, $pos);
 137       $value = substr( $v, $pos + 1);
 138       $this->parameters[$name] = $value;
 139     }
 140 //    dbg_error_log('iCalendar', " iCalProp::ParseFrom found '%s' = '%s' with %d parameters", $this->name, substr($this->content,0,200), count($this->parameters) );
 141   }
 142
 143
 144   /**
 145    * Get/Set name property
 146    *
 147    * @param string $newname [optional] A new name for the property
 148    *
 149    * @return string The name for the property.
 150    */
 151   function Name( $newname = null ) {
 152     if ( $newname != null ) {
 153       $this->name = $newname;
 154       if ( isset($this->rendered) ) unset($this->rendered);
 155 //      dbg_error_log('iCalendar', " iCalProp::Name(%s)", $this->name );
 156     }
 157     return $this->name;
 158   }
 159
 160
 161   /**
 162    * Get/Set the content of the property
 163    *
 164    * @param string $newvalue [optional] A new value for the property
 165    *
 166    * @return string The value of the property.
 167    */
 168   function Value( $newvalue = null ) {
 169     if ( $newvalue != null ) {
 170       $this->content = $newvalue;
 171       if ( isset($this->rendered) ) unset($this->rendered);
 172     }
 173     return $this->content;
 174   }
 175
 176
 177   /**
 178    * Get/Set parameters in their entirety
 179    *
 180    * @param array $newparams An array of new parameter key/value pairs
 181    *
 182    * @return array The current array of parameters for the property.
 183    */
 184   function Parameters( $newparams = null ) {
 185     if ( $newparams != null ) {
 186       $this->parameters = $newparams;
 187       if ( isset($this->rendered) ) unset($this->rendered);
 188     }
 189     return $this->parameters;
 190   }
 191
 192
 193   /**
 194    * Test if our value contains a string
 195    *
 196    * @param string $search The needle which we shall search the haystack for.
 197    *
 198    * @return string The name for the property.
 199    */
 200   function TextMatch( $search ) {
 201     if ( isset($this->content) ) {
 202       return (stristr( $this->content, $search ) !== false);
 203     }
 204     return false;
 205   }
 206
 207
 208   /**
 209    * Get the value of a parameter
 210    *
 211    * @param string $name The name of the parameter to retrieve the value for
 212    *
 213    * @return string The value of the parameter
 214    */
 215   function GetParameterValue( $name ) {
 216     if ( isset($this->parameters[$name]) ) return $this->parameters[$name];
 217   }
 218
 219   /**
 220    * Set the value of a parameter
 221    *
 222    * @param string $name The name of the parameter to set the value for
 223    *
 224    * @param string $value The value of the parameter
 225    */
 226   function SetParameterValue( $name, $value ) {
 227     if ( isset($this->rendered) ) unset($this->rendered);
 228     $this->parameters[$name] = $value;
 229   }
 230
 231   /**
 232   * Render the set of parameters as key1=value1[;key2=value2[; ...]] with
 233   * any colons or semicolons escaped.
 234   */
 235   function RenderParameters() {
 236     $rendered = "";
 237     foreach( $this->parameters AS $k => $v ) {
 238       $escaped = preg_replace( "/([;:])/", '\\\\$1', $v);
 239       $rendered .= sprintf( ";%s=%s", $k, $escaped );
 240     }
 241     return $rendered;
 242   }
 243
 244
 245   /**
 246   * Render a suitably escaped RFC2445 content string.
 247   */
 248   function Render() {
 249     // If we still have the string it was parsed in from, it hasn't been screwed with
 250     // and we can just return that without modification.
 251     if ( isset($this->rendered) ) return $this->rendered;
 252
 253     $property = preg_replace( '/[;].*$/', '', $this->name );
 254     $escaped = $this->content;
 255     switch( $property ) {
 256         /** Content escaping does not apply to these properties culled from RFC2445 */
 257       case 'ATTACH':                case 'GEO':                       case 'PERCENT-COMPLETE':      case 'PRIORITY':
 258       case 'DURATION':              case 'FREEBUSY':                  case 'TZOFFSETFROM':          case 'TZOFFSETTO':
 259       case 'TZURL':                 case 'ATTENDEE':                  case 'ORGANIZER':             case 'RECURRENCE-ID':
 260       case 'URL':                   case 'EXRULE':                    case 'SEQUENCE':              case 'CREATED':
 261       case 'RRULE':                 case 'REPEAT':                    case 'TRIGGER':
 262         break;
 263
 264       case 'COMPLETED':             case 'DTEND':
 265       case 'DUE':                   case 'DTSTART':
 266       case 'DTSTAMP':               case 'LAST-MODIFIED':
 267       case 'CREATED':               case 'EXDATE':
 268       case 'RDATE':
 269         if ( isset($this->parameters['VALUE']) && $this->parameters['VALUE'] == 'DATE' ) {
 270           $escaped = substr( $escaped, 0, 8);
 271         }
 272         break;
 273
 274         /** Content escaping applies by default to other properties */
 275       default:
 276         $escaped = str_replace( '\\', '\\\\', $escaped);
 277         $escaped = preg_replace( '/\r?\n/', '\\n', $escaped);
 278         $escaped = preg_replace( "/([,;])/", '\\\\$1', $escaped);
 279     }
 280     $property = sprintf( "%s%s:", $this->name, $this->RenderParameters() );
 281     if ( (strlen($property) + strlen($escaped)) <= 72 ) {
 282       $this->rendered = $property . $escaped;
 283     }
 284     else if ( (strlen($property) + strlen($escaped)) > 72 && (strlen($property) < 72) && (strlen($escaped) < 72) ) {
 285       $this->rendered = $property . "\r\n " . $escaped;
 286     }
 287     else {
 288       $this->rendered = preg_replace( '/(.{72})/u', '$1'."\r\n ", $property . $escaped );
 289     }
 290     return $this->rendered;
 291   }
 292
 293 }
 294
 295
 296 /**
 297 * A Class for representing components within an iCalendar
 298 *
 299 * @package awl
 300 */
 301 class iCalComponent {
 302   /**#@+
 303    * @access private
 304    */
 305
 306   /**
 307    * The type of this component, such as 'VEVENT', 'VTODO', 'VTIMEZONE', etc.
 308    *
 309    * @var string
 310    */
 311   var $type;
 312
 313   /**
 314    * An array of properties, which are iCalProp objects
 315    *
 316    * @var array
 317    */
 318   var $properties;
 319
 320   /**
 321    * An array of (sub-)components, which are iCalComponent objects
 322    *
 323    * @var array
 324    */
 325   var $components;
 326
 327   /**
 328    * The rendered result (or what was originally parsed, if there have been no changes)
 329    *
 330    * @var array
 331    */
 332   var $rendered;
 333
 334   /**#@-*/
 335
 336   /**
 337   * A basic constructor
 338   */
 339   function iCalComponent( $content = null ) {
 340     $this->type = "";
 341     $this->properties = array();
 342     $this->components = array();
 343     $this->rendered = "";
 344     if ( $content != null && (gettype($content) == 'string' || gettype($content) == 'array') ) {
 345       $this->ParseFrom($content);
 346     }
 347   }
 348
 349
 350   /**
 351   * Apply standard properties for a VCalendar
 352   * @param array $extra_properties Key/value pairs of additional properties
 353   */
 354   function VCalendar( $extra_properties = null ) {
 355     $this->SetType('VCALENDAR');
 356     $this->AddProperty('PRODID', '-//davical.org//NONSGML AWL Calendar//EN');
 357     $this->AddProperty('VERSION', '2.0');
 358     $this->AddProperty('CALSCALE', 'GREGORIAN');
 359     if ( is_array($extra_properties) ) {
 360       foreach( $extra_properties AS $k => $v ) {
 361         $this->AddProperty($k,$v);
 362       }
 363     }
 364   }
 365
 366   /**
 367   * Collect an array of all parameters of our properties which are the specified type
 368   * Mainly used for collecting the full variety of references TZIDs
 369   */
 370   function CollectParameterValues( $parameter_name ) {
 371     $values = array();
 372     foreach( $this->components AS $k => $v ) {
 373       $also = $v->CollectParameterValues($parameter_name);
 374       $values = array_merge( $values, $also );
 375     }
 376     foreach( $this->properties AS $k => $v ) {
 377       $also = $v->GetParameterValue($parameter_name);
 378       if ( isset($also) && $also != "" ) {
 379 //        dbg_error_log( 'iCalendar', "::CollectParameterValues(%s) : Found '%s'", $parameter_name, $also);
 380         $values[$also] = 1;
 381       }
 382     }
 383     return $values;
 384   }
 385
 386
 387   /**
 388   * Parse the text $content into sets of iCalProp & iCalComponent within this iCalComponent
 389   * @param string $content The raw RFC2445-compliant iCalendar component, including BEGIN:TYPE & END:TYPE
 390   */
 391   function ParseFrom( $content ) {
 392     $this->rendered = $content;
 393     $content = $this->UnwrapComponent($content);
 394
 395     $type = false;
 396     $subtype = false;
 397     $finish = null;
 398     $subfinish = null;
 399
 400     $length = strlen($content);
 401     $linefrom = 0;
 402     while( $linefrom < $length ) {
 403       $lineto = strpos( $content, "\n", $linefrom );
 404       if ( $lineto === false ) {
 405         $lineto = strpos( $content, "\r", $linefrom );
 406       }
 407       if ( $lineto > 0 ) {
 408         $line = substr( $content, $linefrom, $lineto - $linefrom);
 409         $linefrom = $lineto + 1;
 410       }
 411       else {
 412         $line = substr( $content, $linefrom );
 413         $linefrom = $length;
 414       }
 415       if ( preg_match('/^\s*$/', $line ) ) continue;
 416       $line = rtrim( $line, "\r\n" );
 417 //      dbg_error_log( 'iCalendar',  "::ParseFrom: Parsing line: $line");
 418
 419       if ( $type === false ) {
 420         if ( preg_match( '/^BEGIN:(.+)$/', $line, $matches ) ) {
 421           // We have found the start of the main component
 422           $type = $matches[1];
 423           $finish = "END:$type";
 424           $this->type = $type;
 425           dbg_error_log( 'iCalendar', "::ParseFrom: Start component of type '%s'", $type);
 426         }
 427         else {
 428           dbg_error_log( 'iCalendar', "::ParseFrom: Ignoring crap before start of component: $line");
 429           // unset($lines[$k]);  // The content has crap before the start
 430           if ( $line != "" ) $this->rendered = null;
 431         }
 432       }
 433       else if ( $type == null ) {
 434         dbg_error_log( 'iCalendar', "::ParseFrom: Ignoring crap after end of component");
 435         if ( $line != "" ) $this->rendered = null;
 436       }
 437       else if ( $line == $finish ) {
 438         dbg_error_log( 'iCalendar', "::ParseFrom: End of component");
 439         $type = null;  // We have reached the end of our component
 440       }
 441       else {
 442         if ( $subtype === false && preg_match( '/^BEGIN:(.+)$/', $line, $matches ) ) {
 443           // We have found the start of a sub-component
 444           $subtype = $matches[1];
 445           $subfinish = "END:$subtype";
 446           $subcomponent = $line . "\r\n";
 447           dbg_error_log( 'iCalendar', "::ParseFrom: Found a subcomponent '%s'", $subtype);
 448         }
 449         else if ( $subtype ) {
 450           // We are inside a sub-component
 451           $subcomponent .= $this->WrapComponent($line);
 452           if ( $line == $subfinish ) {
 453             dbg_error_log( 'iCalendar', "::ParseFrom: End of subcomponent '%s'", $subtype);
 454             // We have found the end of a sub-component
 455             $this->components[] = new iCalComponent($subcomponent);
 456             $subtype = false;
 457           }
 458 //          else
 459 //            dbg_error_log( 'iCalendar', "::ParseFrom: Inside a subcomponent '%s'", $subtype );
 460         }
 461         else {
 462 //          dbg_error_log( 'iCalendar', "::ParseFrom: Parse property of component");
 463           // It must be a normal property line within a component.
 464           $this->properties[] = new iCalProp($line);
 465         }
 466       }
 467     }
 468   }
 469
 470
 471   /**
 472     * This unescapes the (CRLF + linear space) wrapping specified in RFC2445. According
 473     * to RFC2445 we should always end with CRLF but the CalDAV spec says that normalising
 474     * XML parsers often muck with it and may remove the CR.  We accept either case.
 475     */
 476   function UnwrapComponent( $content ) {
 477     return preg_replace('/\r?\n[ \t]/', '', $content );
 478   }
 479
 480   /**
 481     * This imposes the (CRLF + linear space) wrapping specified in RFC2445. According
 482     * to RFC2445 we should always end with CRLF but the CalDAV spec says that normalising
 483     * XML parsers often muck with it and may remove the CR.  We output RFC2445 compliance.
 484     *
 485     * In order to preserve pre-existing wrapping in the component, we split the incoming
 486     * string on line breaks before running wordwrap over each component of that.
 487     */
 488   function WrapComponent( $content ) {
 489     $strs = preg_split( "/\r?\n/", $content );
 490     $wrapped = "";
 491     foreach ($strs as $str) {
 492       $wrapped .= preg_replace( '/(.{72})/u', '$1'."\r\n ", $str ) ."\r\n";
 493     }
 494     return $wrapped;
 495   }
 496
 497   /**
 498   * Return the type of component which this is
 499   */
 500   function GetType() {
 501     return $this->type;
 502   }
 503
 504
 505   /**
 506   * Set the type of component which this is
 507   */
 508   function SetType( $type ) {
 509     if ( isset($this->rendered) ) unset($this->rendered);
 510     $this->type = $type;
 511     return $this->type;
 512   }
 513
 514
 515   /**
 516   * Get all properties, or the properties matching a particular type
 517   */
 518   function GetProperties( $type = null ) {
 519     $properties = array();
 520     foreach( $this->properties AS $k => $v ) {
 521       if ( $type == null || $v->Name() == $type ) {
 522         $properties[$k] = $v;
 523       }
 524     }
 525     return $properties;
 526   }
 527
 528
 529   /**
 530   * Get the value of the first property matching the name. Obviously this isn't
 531   * so useful for properties which may occur multiply, but most don't.
 532   *
 533   * @param string $type The type of property we are after.
 534   * @return string The value of the property, or null if there was no such property.
 535   */
 536   function GetPValue( $type ) {
 537     foreach( $this->properties AS $k => $v ) {
 538       if ( $v->Name() == $type ) return $v->Value();
 539     }
 540     return null;
 541   }
 542
 543
 544   /**
 545   * Get the value of the specified parameter for the first property matching the
 546   * name. Obviously this isn't so useful for properties which may occur multiply, but most don't.
 547   *
 548   * @param string $type The type of property we are after.
 549   * @param string $type The name of the parameter we are after.
 550   * @return string The value of the parameter for the property, or null in the case that there was no such property, or no such parameter.
 551   */
 552   function GetPParamValue( $type, $parameter_name ) {
 553     foreach( $this->properties AS $k => $v ) {
 554       if ( $v->Name() == $type ) return $v->GetParameterValue($parameter_name);
 555     }
 556     return null;
 557   }
 558
 559
 560   /**
 561   * Clear all properties, or the properties matching a particular type
 562   * @param string $type The type of property - omit for all properties
 563   */
 564   function ClearProperties( $type = null ) {
 565     if ( $type != null ) {
 566       // First remove all the existing ones of that type
 567       foreach( $this->properties AS $k => $v ) {
 568         if ( $v->Name() == $type ) {
 569           unset($this->properties[$k]);
 570           if ( isset($this->rendered) ) unset($this->rendered);
 571         }
 572       }
 573       $this->properties = array_values($this->properties);
 574     }
 575     else {
 576       if ( isset($this->rendered) ) unset($this->rendered);
 577       $this->properties = array();
 578     }
 579   }
 580
 581
 582   /**
 583   * Set all properties, or the ones matching a particular type
 584   */
 585   function SetProperties( $new_properties, $type = null ) {
 586     if ( isset($this->rendered) && count($new_properties) > 0 ) unset($this->rendered);
 587     $this->ClearProperties($type);
 588     foreach( $new_properties AS $k => $v ) {
 589       $this->AddProperty($v);
 590     }
 591   }
 592
 593
 594   /**
 595   * Adds a new property
 596   *
 597   * @param iCalProp $new_property The new property to append to the set, or a string with the name
 598   * @param string $value The value of the new property (default: param 1 is an iCalProp with everything
 599   * @param array $parameters The key/value parameter pairs (default: none, or param 1 is an iCalProp with everything)
 600   */
 601   function AddProperty( $new_property, $value = null, $parameters = null ) {
 602     if ( isset($this->rendered) ) unset($this->rendered);
 603     if ( isset($value) && gettype($new_property) == 'string' ) {
 604       $new_prop = new iCalProp();
 605       $new_prop->Name($new_property);
 606       $new_prop->Value($value);
 607       if ( $parameters != null ) $new_prop->Parameters($parameters);
 608       dbg_error_log('iCalendar'," Adding new property '%s'", $new_prop->Render() );
 609       $this->properties[] = $new_prop;
 610     }
 611     else if ( gettype($new_property) ) {
 612       $this->properties[] = $new_property;
 613     }
 614   }
 615
 616
 617   /**
 618   * Get all sub-components, or at least get those matching a type
 619   * @return array an array of the sub-components
 620   */
 621   function &FirstNonTimezone( $type = null ) {
 622     foreach( $this->components AS $k => $v ) {
 623       if ( $v->GetType() != 'VTIMEZONE' ) return $this->components[$k];
 624     }
 625     $result = false;
 626     return $result;
 627   }
 628
 629
 630   /**
 631   * Return true if the person identified by the email address is down as an
 632   * organizer for this meeting.
 633   * @param string $email The e-mail address of the person we're seeking.
 634   * @return boolean true if we found 'em, false if we didn't.
 635   */
 636   function IsOrganizer( $email ) {
 637     if ( !preg_match( '#^mailto:#', $email ) ) $email = 'mailto:'.$email;
 638     $props = $this->GetPropertiesByPath('!VTIMEZONE/ORGANIZER');
 639     foreach( $props AS $k => $prop ) {
 640       if ( $prop->Value() == $email ) return true;
 641     }
 642     return false;
 643   }
 644
 645
 646   /**
 647   * Return true if the person identified by the email address is down as an
 648   * attendee or organizer for this meeting.
 649   * @param string $email The e-mail address of the person we're seeking.
 650   * @return boolean true if we found 'em, false if we didn't.
 651   */
 652   function IsAttendee( $email ) {
 653     if ( !preg_match( '#^mailto:#', $email ) ) $email = 'mailto:'.$email;
 654     if ( $this->IsOrganizer($email) ) return true; /** an organizer is an attendee, as far as we're concerned */
 655     $props = $this->GetPropertiesByPath('!VTIMEZONE/ATTENDEE');
 656     foreach( $props AS $k => $prop ) {
 657       if ( $prop->Value() == $email ) return true;
 658     }
 659     return false;
 660   }
 661
 662
 663   /**
 664   * Get all sub-components, or at least get those matching a type, or failling to match,
 665   * should the second parameter be set to false.
 666   *
 667   * @param string $type The type to match (default: All)
 668   * @param boolean $normal_match Set to false to invert the match (default: true)
 669   * @return array an array of the sub-components
 670   */
 671   function GetComponents( $type = null, $normal_match = true ) {
 672     $components = $this->components;
 673     if ( $type != null ) {
 674       foreach( $components AS $k => $v ) {
 675         if ( ($v->GetType() != $type) === $normal_match ) {
 676           unset($components[$k]);
 677         }
 678       }
 679       $components = array_values($components);
 680     }
 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       // First remove all the existing ones of that type
 692       foreach( $this->components AS $k => $v ) {
 693         if ( $v->GetType() == $type ) {
 694           unset($this->components[$k]);
 695           if ( isset($this->rendered) ) unset($this->rendered);
 696         }
 697         else {
 698           if ( ! $this->components[$k]->ClearComponents($type) ) {
 699             if ( isset($this->rendered) ) unset($this->rendered);
 700           }
 701         }
 702       }
 703       return isset($this->rendered);
 704     }
 705     else {
 706       if ( isset($this->rendered) ) unset($this->rendered);
 707       $this->components = array();
 708     }
 709   }
 710
 711
 712   /**
 713   * Sets some or all sub-components of the component to the supplied new components
 714   *
 715   * @param array of iCalComponent $new_components The new components to replace the existing ones
 716   * @param string $type The type of components to be replaced.  Defaults to null, which means all components will be replaced.
 717   */
 718   function SetComponents( $new_component, $type = null ) {
 719     if ( isset($this->rendered) ) unset($this->rendered);
 720     if ( count($new_component) > 0 ) $this->ClearComponents($type);
 721     foreach( $new_component AS $k => $v ) {
 722       $this->components[] = $v;
 723     }
 724   }
 725
 726
 727   /**
 728   * Adds a new subcomponent
 729   *
 730   * @param iCalComponent $new_component The new component to append to the set
 731   */
 732   function AddComponent( $new_component ) {
 733     if ( is_array($new_component) && count($new_component) == 0 ) return;
 734     if ( isset($this->rendered) ) unset($this->rendered);
 735     if ( is_array($new_component) ) {
 736       foreach( $new_component AS $k => $v ) {
 737         $this->components[] = $v;
 738       }
 739     }
 740     else {
 741       $this->components[] = $new_component;
 742     }
 743   }
 744
 745
 746   /**
 747   * Mask components, removing any that are not of the types in the list
 748   * @param array $keep An array of component types to be kept
 749   */
 750   function MaskComponents( $keep ) {
 751     foreach( $this->components AS $k => $v ) {
 752       if ( ! in_array( $v->GetType(), $keep ) ) {
 753         unset($this->components[$k]);
 754         if ( isset($this->rendered) ) unset($this->rendered);
 755       }
 756       else {
 757         $v->MaskComponents($keep);
 758       }
 759     }
 760   }
 761
 762
 763   /**
 764   * Mask properties, removing any that are not in the list
 765   * @param array $keep An array of property names to be kept
 766   * @param array $component_list An array of component types to check within
 767   */
 768   function MaskProperties( $keep, $component_list=null ) {
 769     foreach( $this->components AS $k => $v ) {
 770       $v->MaskProperties($keep, $component_list);
 771     }
 772
 773     if ( !isset($component_list) || in_array($this->GetType(),$component_list) ) {
 774       foreach( $this->components AS $k => $v ) {
 775         if ( ! in_array( $v->GetType(), $keep ) ) {
 776           unset($this->components[$k]);
 777           if ( isset($this->rendered) ) unset($this->rendered);
 778         }
 779       }
 780     }
 781   }
 782
 783
 784   /**
 785   * Clone this component (and subcomponents) into a confidential version of it.  A confidential
 786   * event will be scrubbed of any identifying characteristics other than time/date, repeat, uid
 787   * and a summary which is just a translated 'Busy'.
 788   */
 789   function CloneConfidential() {
 790     $confidential = clone($this);
 791     $keep_properties = array( 'DTSTAMP', 'DTSTART', 'RRULE', 'DURATION', 'DTEND', 'DUE', 'UID', 'CLASS', 'TRANSP', 'CREATED', 'LAST-MODIFIED' );
 792     $resource_components = array( 'VEVENT', 'VTODO', 'VJOURNAL' );
 793     $confidential->MaskComponents(array( 'VTIMEZONE', 'VEVENT', 'VTODO', 'VJOURNAL' ));
 794     $confidential->MaskProperties($keep_properties, $resource_components );
 795     if ( in_array( $confidential->GetType(), $resource_components ) ) {
 796       $confidential->AddProperty( 'SUMMARY', translate('Busy') );
 797     }
 798     foreach( $confidential->components AS $k => $v ) {
 799       if ( in_array( $v->GetType(), $resource_components ) ) {
 800         $v->AddProperty( 'SUMMARY', translate('Busy') );
 801       }
 802     }
 803
 804     return $confidential;
 805   }
 806
 807     /**
 808      * this function supstitute function from vCalendar::RenderWithoutWrap
 809      * NOTE: vCalendar::RenderWithoutWrap - return string without \r\n on end
 810      *          thats here removed the tail of iCalendar::Render
 811      *          which return \r\n on end
 812      * @param null $restricted_properties
 813      * @return string - rendered string
 814      */
 815     function RenderWithoutWrap($restricted_properties = null){
 816       // substr - remove new line of end, because new line
 817       // are handled in vComponent::RenderWithoutWrap
 818       return substr($this->Render($restricted_properties), 0 , -2);
 819   }
 820
 821
 822   /**
 823   *  Renders the component, possibly restricted to only the listed properties
 824   */
 825   function Render( $restricted_properties = null) {
 826
 827     $unrestricted = (!isset($restricted_properties) || count($restricted_properties) == 0);
 828
 829     if ( isset($this->rendered) && $unrestricted )
 830       return $this->rendered;
 831
 832     $rendered = "BEGIN:$this->type\r\n";
 833     foreach( $this->properties AS $k => $v ) {
 834       if ( method_exists($v, 'Render') ) {
 835         if ( $unrestricted || isset($restricted_properties[$v]) ) $rendered .= $v->Render() . "\r\n";
 836       }
 837     }
 838     foreach( $this->components AS $v ) {   $rendered .= $v->Render();  }
 839     $rendered .= "END:$this->type\r\n";
 840
 841     $rendered = preg_replace('{(?<!\r)\n}', "\r\n", $rendered);
 842     if ( $unrestricted ) $this->rendered = $rendered;
 843
 844     return $rendered;
 845   }
 846
 847
 848   /**
 849   * Return an array of properties matching the specified path
 850   *
 851   * @return array An array of iCalProp within the tree which match the path given, in the form
 852   *  [/]COMPONENT[/...]/PROPERTY in a syntax kind of similar to our poor man's XML queries. We
 853   *  also allow COMPONENT and PROPERTY to be !COMPONENT and !PROPERTY for ++fun.
 854   *
 855   * @note At some point post PHP4 this could be re-done with an iterator, which should be more efficient for common use cases.
 856   */
 857   function GetPropertiesByPath( $path ) {
 858     $properties = array();
 859     dbg_error_log( 'iCalendar', "GetPropertiesByPath: Querying within '%s' for path '%s'", $this->type, $path );
 860     if ( !preg_match( '#(/?)(!?)([^/]+)(/?.*)$#', $path, $matches ) ) return $properties;
 861
 862     $adrift = ($matches[1] == '');
 863     $normal = ($matches[2] == '');
 864     $ourtest = $matches[3];
 865     $therest = $matches[4];
 866     dbg_error_log( 'iCalendar', "GetPropertiesByPath: Matches: %s -- %s -- %s -- %s\n", $matches[1], $matches[2], $matches[3], $matches[4] );
 867     if ( $ourtest == '*' || (($ourtest == $this->type) === $normal) && $therest != '' ) {
 868       if ( preg_match( '#^/(!?)([^/]+)$#', $therest, $matches ) ) {
 869         $normmatch = ($matches[1] =='');
 870         $proptest  = $matches[2];
 871         foreach( $this->properties AS $k => $v ) {
 872           if ( $proptest == '*' || (($v->Name() == $proptest) === $normmatch ) ) {
 873             $properties[] = $v;
 874           }
 875         }
 876       }
 877       else {
 878         /**
 879         * There is more to the path, so we recurse into that sub-part
 880         */
 881         foreach( $this->components AS $k => $v ) {
 882           $properties = array_merge( $properties, $v->GetPropertiesByPath($therest) );
 883         }
 884       }
 885     }
 886
 887     if ( $adrift ) {
 888       /**
 889       * Our input $path was not rooted, so we recurse further
 890       */
 891       foreach( $this->components AS $k => $v ) {
 892         $properties = array_merge( $properties, $v->GetPropertiesByPath($path) );
 893       }
 894     }
 895     dbg_error_log('iCalendar', "GetPropertiesByPath: Found %d within '%s' for path '%s'\n", count($properties), $this->type, $path );
 896     return $properties;
 897   }
 898
 899 }
 900
 901 /**
 902 ************************************************************************************
 903 * Everything below here is deprecated and should be avoided in favour
 904 * of using, improving and enhancing the more sensible structures above.
 905 ************************************************************************************
 906 */
 907
 908 /**
 909 * A Class for handling Events on a calendar (DEPRECATED)
 910 *
 911 * @package awl
 912 */
 913 class iCalendar {  // DEPRECATED
 914   /**#@+
 915   * @access private
 916   */
 917
 918   /**
 919   * The component-ised version of the iCalendar
 920   * @var component iCalComponent
 921   */
 922   var $component;
 923
 924   /**
 925   * An array of arbitrary properties, containing arbitrary arrays of arbitrary properties
 926   * @var properties array
 927   */
 928   var $properties;
 929
 930   /**
 931   * An array of the lines of this iCalendar resource
 932   * @var lines array
 933   */
 934   var $lines;
 935
 936   /**
 937   * The typical location name for the standard timezone such as "Pacific/Auckland"
 938   * @var tz_locn string
 939   */
 940   var $tz_locn;
 941
 942   /**
 943   * The type of iCalendar data VEVENT/VTODO/VJOURNAL
 944   * @var type string
 945   */
 946   var $type;
 947
 948   /**#@-*/
 949
 950   /**
 951   * @DEPRECATED: This class will be removed soon.
 952   * The constructor takes an array of args.  If there is an element called 'icalendar'
 953   * then that will be parsed into the iCalendar object.  Otherwise the array elements
 954   * are converted into properties of the iCalendar object directly.
 955   */
 956   function iCalendar( $args ) {
 957     global $c;
 958
 959     deprecated('iCalendar::iCalendar');
 960     $this->tz_locn = "";
 961     if ( !isset($args) || !(is_array($args) || is_object($args)) ) return;
 962     if ( is_object($args) ) {
 963       settype($args,'array');
 964     }
 965
 966     $this->component = new iCalComponent();
 967     if ( isset($args['icalendar']) ) {
 968       $this->component->ParseFrom($args['icalendar']);
 969       $this->lines = preg_split('/\r?\n/', $args['icalendar'] );
 970       $this->SaveTimeZones();
 971       $first =& $this->component->FirstNonTimezone();
 972       if ( $first ) {
 973         $this->type = $first->GetType();
 974         $this->properties = $first->GetProperties();
 975       }
 976       else {
 977         $this->properties = array();
 978       }
 979       $this->properties['VCALENDAR'] = array('***ERROR*** This class is being referenced in an unsupported way!');
 980       return;
 981     }
 982
 983     if ( isset($args['type'] ) ) {
 984       $this->type = $args['type'];
 985       unset( $args['type'] );
 986     }
 987     else {
 988       $this->type = 'VEVENT';  // Default to event
 989     }
 990     $this->component->SetType('VCALENDAR');
 991     $this->component->SetProperties(
 992         array(
 993           new iCalProp('VERSION:2.0'),
 994           new iCalProp('PRODID:-//davical.org//NONSGML AWL Calendar//EN'),
 995           new iCalProp('CALSCALE:GREGORIAN')
 996         )
 997     );
 998     $first = new iCalComponent();
 999     $first->SetType($this->type);
1000     $this->properties = array();
1001
1002     foreach( $args AS $k => $v ) {
1003       dbg_error_log( 'iCalendar', ":Initialise: %s to >>>%s<<<", $k, $v );
1004       $property = new iCalProp();
1005       $property->Name($k);
1006       $property->Value($v);
1007       $this->properties[] = $property;
1008     }
1009     $first->SetProperties($this->properties);
1010     $this->component->SetComponents( array($first) );
1011
1012     $this->properties['VCALENDAR'] = array('***ERROR*** This class is being referenced in an unsupported way!');
1013
1014     /**
1015     * @todo Need to handle timezones!!!
1016     */
1017     if ( $this->tz_locn == "" ) {
1018       $this->tz_locn = $this->Get("tzid");
1019       if ( (!isset($this->tz_locn) || $this->tz_locn == "") && isset($c->local_tzid) ) {
1020         $this->tz_locn = $c->local_tzid;
1021       }
1022     }
1023   }
1024
1025
1026   /**
1027   * @DEPRECATED: This class will be removed soon.
1028   * Save any timezones by TZID in the PostgreSQL database for future re-use.
1029   */
1030   function SaveTimeZones() {
1031     global $c;
1032
1033     deprecated('iCalendar::SaveTimeZones');
1034     $this->tzid_list = array_keys($this->component->CollectParameterValues('TZID'));
1035     if ( ! isset($this->tzid) && count($this->tzid_list) > 0 ) {
1036       dbg_error_log( 'iCalendar', "::TZID_List[0] = '%s', count=%d", $this->tzid_list[0], count($this->tzid_list) );
1037       $this->tzid = $this->tzid_list[0];
1038     }
1039
1040     $timezones = $this->component->GetComponents('VTIMEZONE');
1041     if ( $timezones === false || count($timezones) == 0 ) return;
1042     $this->vtimezone = $timezones[0]->Render();  // Backward compatibility
1043
1044     $tzid = $this->Get('TZID');
1045     if ( isset($c->save_time_zone_defs) && $c->save_time_zone_defs ) {
1046       foreach( $timezones AS $k => $tz ) {
1047         $tzid = $tz->GetPValue('TZID');
1048
1049         $qry = new AwlQuery( "SELECT tz_locn FROM time_zone WHERE tz_id = ?;", $tzid );
1050         if ( $qry->Exec('iCalendar') && $qry->rows() == 1 ) {
1051           $row = $qry->Fetch();
1052           if ( !isset($first_tzid) ) $first_tzid = $row->tz_locn;
1053           continue;
1054         }
1055
1056         if ( $tzid != "" && $qry->rows() == 0 ) {
1057
1058           $tzname = $tz->GetPValue('X-LIC-LOCATION');
1059           if ( !isset($tzname) ) $tzname = olson_from_tzstring($tzid);
1060
1061           $qry2 = new AwlQuery( "INSERT INTO time_zone (tz_id, tz_locn, tz_spec) VALUES( ?, ?, ? );",
1062                                       $tzid, $tzname, $tz->Render() );
1063           $qry2->Exec('iCalendar');
1064         }
1065       }
1066     }
1067     if ( ! isset($this->tzid) && isset($first_tzid) ) $this->tzid = $first_tzid;
1068
1069     if ( (!isset($this->tz_locn) || $this->tz_locn == '') && isset($first_tzid) && $first_tzid != '' ) {
1070       $tzname = preg_replace('#^(.*[^a-z])?([a-z]+/[a-z]+)$#i','$2', $first_tzid );
1071       if ( preg_match( '#\S+/\S+#', $tzname) ) {
1072         $this->tz_locn = $tzname;
1073       }
1074       dbg_error_log( 'iCalendar', " TZCrap1: TZID '%s', Location '%s', Perhaps: %s", $tzid, $this->tz_locn, $tzname );
1075     }
1076
1077     if ( (!isset($this->tz_locn) || $this->tz_locn == "") && isset($c->local_tzid) ) {
1078       $this->tz_locn = $c->local_tzid;
1079     }
1080     if ( ! isset($this->tzid) && isset($this->tz_locn) ) $this->tzid = $this->tz_locn;
1081   }
1082
1083
1084   /**
1085   * An array of property names that we should always want when rendering an iCalendar
1086   *
1087   * @DEPRECATED: This class will be removed soon.
1088   * @todo Remove this function.
1089   */
1090   function DefaultPropertyList() {
1091     dbg_error_log( "LOG", " iCalendar: Call to deprecated method '%s'", 'DefaultPropertyList' );
1092     return array( "UID" => 1, "DTSTAMP" => 1, "DTSTART" => 1, "DURATION" => 1,
1093                   "LAST-MODIFIED" => 1,"CLASS" => 1, "TRANSP" => 1, "SEQUENCE" => 1,
1094                   "DUE" => 1, "SUMMARY" => 1, "RRULE" => 1 );
1095   }
1096
1097   /**
1098   * A function to extract the contents of a BEGIN:SOMETHING to END:SOMETHING (perhaps multiply)
1099   * and return just that bit (or, of course, those bits :-)
1100   *
1101   * @var string The type of thing(s) we want returned.
1102   * @var integer The number of SOMETHINGS we want to get.
1103   *
1104   * @return string A string from BEGIN:SOMETHING to END:SOMETHING, possibly multiple of these
1105   *
1106   * @DEPRECATED: This class will be removed soon.
1107   * @todo Remove this function.
1108   */
1109   function JustThisBitPlease( $type, $count=1 ) {
1110     deprecated('iCalendar::JustThisBitPlease' );
1111     $answer = "";
1112     $intags = false;
1113     $start = "BEGIN:$type";
1114     $finish = "END:$type";
1115     dbg_error_log( 'iCalendar', ":JTBP: Looking for %d subsets of type %s", $count, $type );
1116     reset($this->lines);
1117     foreach( $this->lines AS $k => $v ) {
1118       if ( !$intags && $v == $start ) {
1119         $answer .= $v . "\n";
1120         $intags = true;
1121       }
1122       else if ( $intags && $v == $finish ) {
1123         $answer .= $v . "\n";
1124         $intags = false;
1125       }
1126       else if ( $intags ) {
1127         $answer .= $v . "\n";
1128       }
1129     }
1130     return $answer;
1131   }
1132
1133
1134   /**
1135   * Function to parse lines from BEGIN:SOMETHING to END:SOMETHING into a nested array structure
1136   *
1137   * @var string The "SOMETHING" from the BEGIN:SOMETHING line we just met
1138   * @return arrayref An array of the things we found between (excluding) the BEGIN & END, some of which might be sub-arrays
1139   *
1140   * @DEPRECATED: This class will be removed soon.
1141   * @todo Remove this function.
1142   */
1143   function &ParseSomeLines( $type ) {
1144     deprecated('iCalendar::ParseSomeLines' );
1145     $props = array();
1146     $properties =& $props;
1147     while( isset($this->lines[$this->_current_parse_line]) ) {
1148       $i = $this->_current_parse_line++;
1149       $line =& $this->lines[$i];
1150       dbg_error_log( 'iCalendar', ":Parse:%s LINE %03d: >>>%s<<<", $type, $i, $line );
1151       if ( $this->parsing_vtimezone ) {
1152         $this->vtimezone .= $line."\n";
1153       }
1154       if ( preg_match( '/^(BEGIN|END):([^:]+)$/', $line, $matches ) ) {
1155         if ( $matches[1] == 'END' && $matches[2] == $type ) {
1156           if ( $type == 'VTIMEZONE' ) {
1157             $this->parsing_vtimezone = false;
1158           }
1159           return $properties;
1160         }
1161         else if( $matches[1] == 'END' ) {
1162           dbg_error_log("ERROR"," iCalendar: parse error: Unexpected END:%s when we were looking for END:%s", $matches[2], $type );
1163           return $properties;
1164         }
1165         else if( $matches[1] == 'BEGIN' ) {
1166           $subtype = $matches[2];
1167           if ( $subtype == 'VTIMEZONE' ) {
1168             $this->parsing_vtimezone = true;
1169             $this->vtimezone = $line."\n";
1170           }
1171           if ( !isset($properties['INSIDE']) ) $properties['INSIDE'] = array();
1172           $properties['INSIDE'][] = $subtype;
1173           if ( !isset($properties[$subtype]) ) $properties[$subtype] = array();
1174           $properties[$subtype][] = $this->ParseSomeLines($subtype);
1175         }
1176       }
1177       else {
1178         // Parse the property
1179         @list( $property, $value ) = explode(':', $line, 2 );
1180         if ( strpos( $property, ';' ) > 0 ) {
1181           $parameterlist = explode(';', $property );
1182           $property = array_shift($parameterlist);
1183           foreach( $parameterlist AS $pk => $pv ) {
1184             if ( $pv == "VALUE=DATE" ) {
1185               $value .= 'T000000';
1186             }
1187             elseif ( preg_match('/^([^;:=]+)=([^;:=]+)$/', $pv, $matches) ) {
1188               switch( $matches[1] ) {
1189                 case 'TZID': $properties['TZID'] = $matches[2];  break;
1190                 default:
1191                   dbg_error_log( 'iCalendar', " FYI: Ignoring Resource '%s', Property '%s', Parameter '%s', Value '%s'", $type, $property, $matches[1], $matches[2] );
1192               }
1193             }
1194           }
1195         }
1196         if ( $this->parsing_vtimezone && (!isset($this->tz_locn) || $this->tz_locn == "") && $property == 'X-LIC-LOCATION' ) {
1197           $this->tz_locn = $value;
1198         }
1199         $properties[strtoupper($property)] = $this->RFC2445ContentUnescape($value);
1200       }
1201     }
1202     return $properties;
1203   }
1204
1205
1206   /**
1207   * Build the iCalendar object from a text string which is a single iCalendar resource
1208   *
1209   * @var string The RFC2445 iCalendar resource to be parsed
1210   *
1211   * @DEPRECATED: This class will be removed soon.
1212   * @todo Remove this function.
1213   */
1214   function BuildFromText( $icalendar ) {
1215     deprecated('iCalendar::BuildFromText' );
1216     /**
1217      * This unescapes the (CRLF + linear space) wrapping specified in RFC2445. According
1218      * to RFC2445 we should always end with CRLF but the CalDAV spec says that normalising
1219      * XML parsers often muck with it and may remove the CR.
1220      */
1221     $icalendar = preg_replace('/\r?\n[ \t]/', '', $icalendar );
1222
1223     $this->lines = preg_split('/\r?\n/', $icalendar );
1224
1225     $this->_current_parse_line = 0;
1226     $this->properties = $this->ParseSomeLines('');
1227
1228     /**
1229     * Our 'type' is the type of non-timezone inside a VCALENDAR
1230     */
1231     if ( isset($this->properties['VCALENDAR'][0]['INSIDE']) ) {
1232       foreach ( $this->properties['VCALENDAR'][0]['INSIDE']  AS $k => $v ) {
1233         if ( $v == 'VTIMEZONE' ) continue;
1234         $this->type = $v;
1235         break;
1236       }
1237     }
1238
1239   }
1240
1241
1242   /**
1243   * Returns a content string with the RFC2445 escaping removed
1244   *
1245   * @param string $escaped The incoming string to be escaped.
1246   * @return string The string with RFC2445 content escaping removed.
1247   *
1248   * @DEPRECATED: This class will be removed soon.
1249   * @todo Remove this function.
1250   */
1251   function RFC2445ContentUnescape( $escaped ) {
1252     deprecated( 'RFC2445ContentUnescape' );
1253     $unescaped = str_replace( '\\n', "\n", $escaped);
1254     $unescaped = str_replace( '\\N', "\n", $unescaped);
1255     $unescaped = preg_replace( "/\\\\([,;:\"\\\\])/", '$1', $unescaped);
1256     return $unescaped;
1257   }
1258
1259
1260
1261   /**
1262   * Do what must be done with time zones from on file.  Attempt to turn
1263   * them into something that PostgreSQL can understand...
1264   *
1265   * @DEPRECATED: This class will be removed soon.
1266   * @todo Remove this function.
1267   */
1268   function DealWithTimeZones() {
1269     global $c;
1270
1271     deprecated('iCalendar::DealWithTimeZones' );
1272     $tzid = $this->Get('TZID');
1273     if ( isset($c->save_time_zone_defs) && $c->save_time_zone_defs ) {
1274       $qry = new AwlQuery( "SELECT tz_locn FROM time_zone WHERE tz_id = ?;", $tzid );
1275       if ( $qry->Exec('iCalendar') && $qry->rows() == 1 ) {
1276         $row = $qry->Fetch();
1277         $this->tz_locn = $row->tz_locn;
1278       }
1279       dbg_error_log( 'iCalendar', " TZCrap2: TZID '%s', DB Rows=%d, Location '%s'", $tzid, $qry->rows(), $this->tz_locn );
1280     }
1281
1282     if ( (!isset($this->tz_locn) || $this->tz_locn == '') && $tzid != '' ) {
1283       /**
1284       * In case there was no X-LIC-LOCATION defined, let's hope there is something in the TZID
1285       * that we can use.  We are looking for a string like "Pacific/Auckland" if possible.
1286       */
1287       $tzname = preg_replace('#^(.*[^a-z])?([a-z]+/[a-z]+)$#i','$1',$tzid );
1288       /**
1289       * Unfortunately this kind of thing will never work well :-(
1290       *
1291       if ( strstr( $tzname, ' ' ) ) {
1292         $words = preg_split('/\s/', $tzname );
1293         $tzabbr = '';
1294         foreach( $words AS $i => $word ) {
1295           $tzabbr .= substr( $word, 0, 1);
1296         }
1297         $this->tz_locn = $tzabbr;
1298       }
1299       */
1300       if ( preg_match( '#\S+/\S+#', $tzname) ) {
1301         $this->tz_locn = $tzname;
1302       }
1303       dbg_error_log( 'iCalendar', " TZCrap3: TZID '%s', Location '%s', Perhaps: %s", $tzid, $this->tz_locn, $tzname );
1304     }
1305
1306     if ( $tzid != '' && isset($c->save_time_zone_defs) && $c->save_time_zone_defs && $qry->rows() != 1 && isset($this->vtimezone) && $this->vtimezone != "" ) {
1307       $qry2 = new AwlQuery( "INSERT INTO time_zone (tz_id, tz_locn, tz_spec) VALUES( ?, ?, ? );",
1308                                    $tzid, $this->tz_locn, $this->vtimezone );
1309       $qry2->Exec('iCalendar');
1310     }
1311
1312     if ( (!isset($this->tz_locn) || $this->tz_locn == "") && isset($c->local_tzid) ) {
1313       $this->tz_locn = $c->local_tzid;
1314     }
1315   }
1316
1317
1318   /**
1319   * Get the value of a property in the first non-VTIMEZONE
1320   * @DEPRECATED: This class will be removed soon.
1321   */
1322   function Get( $key ) {
1323     deprecated('iCalendar::Get' );
1324     if ( strtoupper($key) == 'TZID' ) {
1325       // backward compatibility hack
1326       dbg_error_log( 'iCalendar', " Get(TZID): TZID '%s', Location '%s'", (isset($this->tzid)?$this->tzid:"[not set]"), $this->tz_locn );
1327       if ( isset($this->tzid) ) return $this->tzid;
1328       return $this->tz_locn;
1329     }
1330     /**
1331     * The property we work on is the first non-VTIMEZONE we find.
1332     */
1333     $component =& $this->component->FirstNonTimezone();
1334     if ( $component === false ) return null;
1335     return $component->GetPValue(strtoupper($key));
1336   }
1337
1338
1339   /**
1340   * Set the value of a property
1341   * @DEPRECATED: This class will be removed soon.
1342   */
1343   function Set( $key, $value ) {
1344     deprecated('iCalendar::Set' );
1345     if ( $value == "" ) return;
1346     $key = strtoupper($key);
1347     $property = new iCalProp();
1348     $property->Name($key);
1349     $property->Value($value);
1350     if (isset($this->component->rendered) ) unset( $this->component->rendered );
1351     $component =& $this->component->FirstNonTimezone();
1352     $component->SetProperties( array($property), $key);
1353     return $this->Get($key);
1354   }
1355
1356
1357   /**
1358   * @DEPRECATED: This class will be removed soon.
1359   * Add a new property/value, regardless of whether it exists already
1360   *
1361   * @param string $key The property key
1362   * @param string $value The property value
1363   * @param string $parameters Any parameters to set for the property, as an array of key/value pairs
1364   */
1365   function Add( $key, $value, $parameters = null ) {
1366     deprecated('iCalendar::Add' );
1367     if ( $value == "" ) return;
1368     $key = strtoupper($key);
1369     $property = new iCalProp();
1370     $property->Name($key);
1371     $property->Value($value);
1372     if ( isset($parameters) && is_array($parameters) ) {
1373       $property->parameters = $parameters;
1374     }
1375     $component =& $this->component->FirstNonTimezone();
1376     $component->AddProperty($property);
1377     if (isset($this->component->rendered) ) unset( $this->component->rendered );
1378   }
1379
1380
1381   /**
1382   * @DEPRECATED: This class will be removed soon.
1383   * Get all sub-components, or at least get those matching a type, or failling to match,
1384   * should the second parameter be set to false.
1385   *
1386   * @param string $type The type to match (default: All)
1387   * @param boolean $normal_match Set to false to invert the match (default: true)
1388   * @return array an array of the sub-components
1389   */
1390   function GetComponents( $type = null, $normal_match = true ) {
1391     deprecated('iCalendar::GetComponents' );
1392     return $this->component->GetComponents($type,$normal_match);
1393   }
1394
1395
1396   /**
1397   * @DEPRECATED: This class will be removed soon.
1398   * Clear all components, or the components matching a particular type
1399   * @param string $type The type of component - omit for all components
1400   */
1401   function ClearComponents( $type = null ) {
1402     deprecated('iCalendar::ClearComponents' );
1403     $this->component->ClearComponents($type);
1404   }
1405
1406
1407   /**
1408   * @DEPRECATED: This class will be removed soon.
1409   * Sets some or all sub-components of the component to the supplied new components
1410   *
1411   * @param array of iCalComponent $new_components The new components to replace the existing ones
1412   * @param string $type The type of components to be replaced.  Defaults to null, which means all components will be replaced.
1413   */
1414   function SetComponents( $new_component, $type = null ) {
1415     deprecated('iCalendar::SetComponents' );
1416     $this->component->SetComponents( $new_component, $type );
1417   }
1418
1419
1420   /**
1421   * @DEPRECATED: This class will be removed soon.
1422   * Adds a new subcomponent
1423   *
1424   * @param iCalComponent $new_component The new component to append to the set
1425   */
1426   function AddComponent( $new_component ) {
1427     deprecated('iCalendar::AddComponent' );
1428     $this->component->AddComponent($new_component);
1429   }
1430
1431
1432   /**
1433   * @DEPRECATED: This class will be removed soon.
1434   * Mask components, removing any that are not of the types in the list
1435   * @param array $keep An array of component types to be kept
1436   */
1437   function MaskComponents( $keep ) {
1438     deprecated('iCalendar::MaskComponents' );
1439     $this->component->MaskComponents($keep);
1440   }
1441
1442
1443   /**
1444   * @DEPRECATED: This class will be removed soon.
1445   * Returns a PostgreSQL Date Format string suitable for returning HTTP (RFC2068) dates
1446   * Preferred is "Sun, 06 Nov 1994 08:49:37 GMT" so we do that.
1447   */
1448   static function HttpDateFormat() {
1449     deprecated('iCalendar::HttpDateFormat() use AwlDatabase::HttpDateFormat instead.' );
1450     return "'Dy, DD Mon IYYY HH24:MI:SS \"GMT\"'";
1451   }
1452
1453
1454   /**
1455   * @DEPRECATED: This class will be removed soon.
1456   * Returns a PostgreSQL Date Format string suitable for returning iCal dates
1457   */
1458   static function SqlDateFormat() {
1459     deprecated('iCalendar::SqlDateFormat() use AwlDatabase::SqlDateFormat instead.' );
1460     return "'YYYYMMDD\"T\"HH24MISS'";
1461   }
1462
1463
1464   /**
1465   * @DEPRECATED: This class will be removed soon.
1466   * Returns a PostgreSQL Date Format string suitable for returning dates which
1467   * have been cast to UTC
1468   */
1469   static function SqlUTCFormat() {
1470     deprecated('iCalendar::SqlUTCFormat() use AwlDatabase::SqlUTCFormat instead.' );
1471     return "'YYYYMMDD\"T\"HH24MISS\"Z\"'";
1472   }
1473
1474
1475   /**
1476   * @DEPRECATED: This class will be removed soon.
1477   * Returns a PostgreSQL Date Format string suitable for returning iCal durations
1478   *  - this doesn't work for negative intervals, but events should not have such!
1479   */
1480   static function SqlDurationFormat() {
1481     deprecated('iCalendar::SqlDurationFormat() use AwlDatabase::SqlDurationFormat instead.' );
1482     return "'\"PT\"HH24\"H\"MI\"M\"'";
1483   }
1484
1485   /**
1486   * @DEPRECATED: This class will be removed soon.
1487   * Returns a suitably escaped RFC2445 content string.
1488   *
1489   * @param string $name The incoming name[;param] prefixing the string.
1490   * @param string $value The incoming string to be escaped.
1491   *
1492   * @deprecated This function is deprecated and will be removed eventually.
1493   * @todo Remove this function.
1494   */
1495   function RFC2445ContentEscape( $name, $value ) {
1496     deprecated('iCalendar::RFC2445ContentEscape' );
1497     $property = preg_replace( '/[;].*$/', '', $name );
1498     switch( $property ) {
1499         /** Content escaping does not apply to these properties culled from RFC2445 */
1500       case 'ATTACH':                case 'GEO':                       case 'PERCENT-COMPLETE':      case 'PRIORITY':
1501       case 'COMPLETED':             case 'DTEND':                     case 'DUE':                   case 'DTSTART':
1502       case 'DURATION':              case 'FREEBUSY':                  case 'TZOFFSETFROM':          case 'TZOFFSETTO':
1503       case 'TZURL':                 case 'ATTENDEE':                  case 'ORGANIZER':             case 'RECURRENCE-ID':
1504       case 'URL':                   case 'EXDATE':                    case 'EXRULE':                case 'RDATE':
1505       case 'RRULE':                 case 'REPEAT':                    case 'TRIGGER':               case 'CREATED':
1506       case 'DTSTAMP':               case 'LAST-MODIFIED':             case 'SEQUENCE':
1507         break;
1508
1509         /** Content escaping applies by default to other properties */
1510       default:
1511         $value = str_replace( '\\', '\\\\', $value);
1512         $value = preg_replace( '/\r?\n/', '\\n', $value);
1513         $value = preg_replace( "/([,;:\"])/", '\\\\$1', $value);
1514     }
1515     $result = preg_replace( '/(.{72})/u', '$1'."\r\n ", $name.':'.$value ) ."\r\n";
1516     return $result;
1517   }
1518
1519   /**
1520   * @DEPRECATED: This class will be removed soon.
1521    * Return all sub-components of the given type, which are part of the
1522    * component we pass in as an array of lines.
1523    *
1524    * @param array $component The component to be parsed
1525    * @param string $type The type of sub-components to be extracted
1526    * @param int $count The number of sub-components to extract (default: 9999)
1527    *
1528    * @return array The sub-component lines
1529    */
1530   function ExtractSubComponent( $component, $type, $count=9999 ) {
1531     deprecated('iCalendar::ExtractSubComponent' );
1532     $answer = array();
1533     $intags = false;
1534     $start = "BEGIN:$type";
1535     $finish = "END:$type";
1536     dbg_error_log( 'iCalendar', ":ExtractSubComponent: Looking for %d subsets of type %s", $count, $type );
1537     reset($component);
1538     foreach( $component AS $k => $v ) {
1539       if ( !$intags && $v == $start ) {
1540         $answer[] = $v;
1541         $intags = true;
1542       }
1543       else if ( $intags && $v == $finish ) {
1544         $answer[] = $v;
1545         $intags = false;
1546       }
1547       else if ( $intags ) {
1548         $answer[] = $v;
1549       }
1550     }
1551     return $answer;
1552   }
1553
1554
1555   /**
1556   * @DEPRECATED: This class will be removed soon.
1557    * Extract a particular property from the provided component.  In doing so we
1558    * assume that the content was unescaped when iCalComponent::ParseFrom()
1559    * called iCalComponent::UnwrapComponent().
1560    *
1561    * @param array $component An array of lines of this component
1562    * @param string $type The type of parameter
1563    *
1564    * @return array An array of iCalProperty objects
1565    */
1566   function ExtractProperty( $component, $type, $count=9999 ) {
1567     deprecated('iCalendar::ExtractProperty' );
1568     $answer = array();
1569     dbg_error_log( 'iCalendar', ":ExtractProperty: Looking for %d properties of type %s", $count, $type );
1570     reset($component);
1571     foreach( $component AS $k => $v ) {
1572       if ( preg_match( "/$type"."[;:]/i", $v ) ) {
1573         $answer[] = new iCalProp($v);
1574         dbg_error_log( 'iCalendar', ":ExtractProperty: Found property %s", $type );
1575         if ( --$count < 1 ) return $answer;
1576       }
1577     }
1578     return $answer;
1579   }
1580
1581
1582   /**
1583   * @DEPRECATED: This class will be removed soon.
1584    * Applies the filter conditions, possibly recursively, to the value which will be either
1585    * a single property, or an array of lines of the component under test.
1586    *
1587    * @todo Eventually we need to handle all of these possibilities, which will mean writing
1588    * several routines:
1589    *  - Get Property from Component
1590    *  - Get Parameter from Property
1591    *  - Test TimeRange
1592    * For the moment we will leave these, until there is a perceived need.
1593    *
1594    * @param array $filter An array of XMLElement defining the filter(s)
1595    * @param mixed $value Either a string which is the single property, or an array of lines, for the component.
1596    * @return boolean Whether the filter passed / failed.
1597    */
1598   function ApplyFilter( $filter, $value ) {
1599     deprecated('iCalendar::ApplyFilter' );
1600     foreach( $filter AS $k => $v ) {
1601       $tag = $v->GetNSTag();
1602       $value_type = gettype($value);
1603       $value_defined = (isset($value) && $value_type == 'string') || ($value_type == 'array' && count($value) > 0 );
1604       if ( $tag == 'urn:ietf:params:xml:ns:caldav:is-not-defined' && $value_defined ) {
1605         dbg_error_log( 'iCalendar', ":ApplyFilter: Value is set ('%s'), want unset, for filter %s", count($value), $tag );
1606         return false;
1607       }
1608       elseif ( $tag == 'urn:ietf:params:xml:ns:caldav:is-defined' && !$value_defined ) {
1609         dbg_error_log( 'iCalendar', ":ApplyFilter: Want value, but it is not set for filter %s", $tag );
1610         return false;
1611       }
1612       else {
1613         dbg_error_log( 'iCalendar', ":ApplyFilter: Have values for '%s' filter", $tag );
1614         switch( $tag ) {
1615           case 'urn:ietf:params:xml:ns:caldav:time-range':
1616             /** todo:: While this is unimplemented here at present, most time-range tests should occur at the SQL level. */
1617             break;
1618           case 'urn:ietf:params:xml:ns:caldav:text-match':
1619             $search = $v->GetContent();
1620             // In this case $value will either be a string, or an array of iCalProp objects
1621             // since TEXT-MATCH does not apply to COMPONENT level - only property/parameter
1622             if ( !is_string($value) ) {
1623               if ( is_array($value) ) {
1624                 $match = false;
1625                 foreach( $value AS $k1 => $v1 ) {
1626                   // $v1 MUST be an iCalProp object
1627                   if ( $match = $v1->TextMatch($search)) break;
1628                 }
1629               }
1630               else {
1631                 dbg_error_log( 'iCalendar', ":ApplyFilter: TEXT-MATCH will only work on strings or arrays of iCalProp.  %s unsupported", gettype($value) );
1632                 return true;  // We return _true_ in this case, so the client sees the item
1633               }
1634             }
1635             else {
1636               $match = (stristr( $value, $search ) !== false);
1637             }
1638             $negate = $v->GetAttribute("negate-condition");
1639             if ( isset($negate) && strtolower($negate) == "yes" ) $match = !$match;
1640 //            dbg_error_log( 'iCalendar', ":ApplyFilter: TEXT-MATCH returning %s", ($match?"yes":"no") );
1641             return $match;
1642             break;
1643           case 'urn:ietf:params:xml:ns:caldav:comp-filter':
1644             $subfilter = $v->GetContent();
1645             $component = $this->ExtractSubComponent($value,$v->GetAttribute("name"));
1646             if ( ! $this->ApplyFilter($subfilter,$component) ) return false;
1647             break;
1648           case 'urn:ietf:params:xml:ns:caldav:prop-filter':
1649             $subfilter = $v->GetContent();
1650             $properties = $this->ExtractProperty($value,$v->GetAttribute("name"));
1651             if ( ! $this->ApplyFilter($subfilter,$properties) ) return false;
1652             break;
1653           case 'urn:ietf:params:xml:ns:caldav:param-filter':
1654             $subfilter = $v->GetContent();
1655             $parameter = $this->ExtractParameter($value,$v->GetAttribute("NAME"));
1656             if ( ! $this->ApplyFilter($subfilter,$parameter) ) return false;
1657             break;
1658         }
1659       }
1660     }
1661     return true;
1662   }
1663
1664   /**
1665   * @DEPRECATED: This class will be removed soon.
1666    * Test a PROP-FILTER or COMP-FILTER and return a true/false
1667    * COMP-FILTER (is-defined | is-not-defined | (time-range?, prop-filter*, comp-filter*))
1668    * PROP-FILTER (is-defined | is-not-defined | ((time-range | text-match)?, param-filter*))
1669    *
1670    * @param array $filter An array of XMLElement defining the filter
1671    *
1672    * @return boolean Whether or not this iCalendar passes the test
1673    */
1674   function TestFilter( $filters ) {
1675     deprecated('iCalendar::TestFilter' );
1676
1677 //    dbg_error_log('iCalendar', ':TestFilter we have %d filters to test', count($filters) );
1678     foreach( $filters AS $k => $v ) {
1679       $tag = $v->GetNSTag();
1680 //      dbg_error_log('iCalendar', ':TestFilter working on tag "%s" %s"', $k, $tag );
1681       $name = $v->GetAttribute("name");
1682       $filter = $v->GetContent();
1683       if ( $tag == "urn:ietf:params:xml:ns:caldav:prop-filter" ) {
1684         $value = $this->ExtractProperty($this->lines,$name);
1685       }
1686       else {
1687         $value = $this->ExtractSubComponent($this->lines,$v->GetAttribute("name"));
1688       }
1689       if ( count($value) == 0 ) unset($value);
1690       if ( ! $this->ApplyFilter($filter,$value) ) return false;
1691     }
1692     return true;
1693   }
1694
1695   /**
1696   * @DEPRECATED: This class will be removed soon.
1697   * Returns the header we always use at the start of our iCalendar resources
1698   *
1699   * @todo Remove this function.
1700   */
1701   static function iCalHeader() {
1702     deprecated('iCalendar::iCalHeader' );
1703     return <<<EOTXT
1704 BEGIN:VCALENDAR\r
1705 VERSION:2.0\r
1706 PRODID:-//davical.org//NONSGML AWL Calendar//EN\r
1707
1708 EOTXT;
1709   }
1710
1711
1712
1713   /**
1714   * @DEPRECATED: This class will be removed soon.
1715   * Returns the footer we always use at the finish of our iCalendar resources
1716   *
1717   * @todo Remove this function.
1718   */
1719   static function iCalFooter() {
1720     deprecated('iCalendar::iCalFooter' );
1721     return "END:VCALENDAR\r\n";
1722   }
1723
1724
1725   /**
1726   * @DEPRECATED: This class will be removed soon.
1727   * Render the iCalendar object as a text string which is a single VEVENT (or other)
1728   *
1729   * @param boolean $as_calendar Whether or not to wrap the event in a VCALENDAR
1730   * @param string $type The type of iCalendar object (VEVENT, VTODO, VFREEBUSY etc.)
1731   * @param array $restrict_properties The names of the properties we want in our rendered result.
1732   */
1733   function Render( $as_calendar = true, $type = null, $restrict_properties = null ) {
1734     deprecated('iCalendar::Render' );
1735     if ( $as_calendar ) {
1736       return $this->component->Render();
1737     }
1738     else {
1739       $components = $this->component->GetComponents($type);
1740       $rendered = "";
1741       foreach( $components AS $k => $v ) {
1742         $rendered .= $v->Render($restrict_properties);
1743       }
1744       return $rendered;
1745     }
1746   }
1747
1748 }