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