Back to index

awl  0.53
Public Member Functions | Public Attributes
iCalComponent Class Reference

List of all members.

Public Member Functions

 iCalComponent ($content=null)
 

@-


 VCalendar ($extra_properties=null)
 Apply standard properties for a VCalendar.
 CollectParameterValues ($parameter_name)
 Collect an array of all parameters of our properties which are the specified type Mainly used for collecting the full variety of references TZIDs.
 ParseFrom ($content)
 Parse the text $content into sets of iCalProp & iCalComponent within this iCalComponent.
 UnwrapComponent ($content)
 This unescapes the (CRLF + linear space) wrapping specified in RFC2445.
 WrapComponent ($content)
 This imposes the (CRLF + linear space) wrapping specified in RFC2445.
 GetType ()
 Return the type of component which this is.
 SetType ($type)
 Set the type of component which this is.
 GetProperties ($type=null)
 Get all properties, or the properties matching a particular type.
 GetPValue ($type)
 Get the value of the first property matching the name.
 GetPParamValue ($type, $parameter_name)
 Get the value of the specified parameter for the first property matching the name.
 ClearProperties ($type=null)
 Clear all properties, or the properties matching a particular type.
 SetProperties ($new_properties, $type=null)
 Set all properties, or the ones matching a particular type.
 AddProperty ($new_property, $value=null, $parameters=null)
 Adds a new property.
FirstNonTimezone ($type=null)
 Get all sub-components, or at least get those matching a type.
 IsOrganizer ($email)
 Return true if the person identified by the email address is down as an organizer for this meeting.
 IsAttendee ($email)
 Return true if the person identified by the email address is down as an attendee or organizer for this meeting.
 GetComponents ($type=null, $normal_match=true)
 Get all sub-components, or at least get those matching a type, or failling to match, should the second parameter be set to false.
 ClearComponents ($type=null)
 Clear all components, or the components matching a particular type.
 SetComponents ($new_component, $type=null)
 Sets some or all sub-components of the component to the supplied new components.
 AddComponent ($new_component)
 Adds a new subcomponent.
 MaskComponents ($keep)
 Mask components, removing any that are not of the types in the list.
 MaskProperties ($keep, $component_list=null)
 Mask properties, removing any that are not in the list.
 CloneConfidential ()
 Clone this component (and subcomponents) into a confidential version of it.
 Render ($restricted_properties=null)
 Renders the component, possibly restricted to only the listed properties.
 GetPropertiesByPath ($path)
 Return an array of properties matching the specified path.

Public Attributes

 $type
 $properties
 $components
 $rendered

Detailed Description

Definition at line 301 of file iCalendar.php.


Member Function Documentation

iCalComponent::AddComponent ( new_component)

Adds a new subcomponent.

Parameters:
iCalComponent$new_componentThe new component to append to the set

Definition at line 732 of file iCalendar.php.

                                          {
    if ( is_array($new_component) && count($new_component) == 0 ) return;
    if ( isset($this->rendered) ) unset($this->rendered);
    if ( is_array($new_component) ) {
      foreach( $new_component AS $k => $v ) {
        $this->components[] = $v;
      }
    }
    else {
      $this->components[] = $new_component;
    }
  }
iCalComponent::AddProperty ( new_property,
value = null,
parameters = null 
)

Adds a new property.

Parameters:
iCalProp$new_propertyThe new property to append to the set, or a string with the name
string$valueThe value of the new property (default: param 1 is an iCalProp with everything
array$parametersThe key/value parameter pairs (default: none, or param 1 is an iCalProp with everything)

Definition at line 601 of file iCalendar.php.

                                                                           {
    if ( isset($this->rendered) ) unset($this->rendered);
    if ( isset($value) && gettype($new_property) == 'string' ) {
      $new_prop = new iCalProp();
      $new_prop->Name($new_property);
      $new_prop->Value($value);
      if ( $parameters != null ) $new_prop->Parameters($parameters);
      dbg_error_log('iCalendar'," Adding new property '%s'", $new_prop->Render() );
      $this->properties[] = $new_prop;
    }
    else if ( gettype($new_property) ) {
      $this->properties[] = $new_property;
    }
  }

Here is the caller graph for this function:

iCalComponent::ClearComponents ( type = null)

Clear all components, or the components matching a particular type.

Parameters:
string$typeThe type of component - omit for all components

Definition at line 689 of file iCalendar.php.

                                           {
    if ( $type != null ) {
      // First remove all the existing ones of that type
      foreach( $this->components AS $k => $v ) {
        if ( $v->GetType() == $type ) {
          unset($this->components[$k]);
          if ( isset($this->rendered) ) unset($this->rendered);
        }
        else {
          if ( ! $this->components[$k]->ClearComponents($type) ) {
            if ( isset($this->rendered) ) unset($this->rendered);
          }
        }
      }
      return isset($this->rendered);
    }
    else {
      if ( isset($this->rendered) ) unset($this->rendered);
      $this->components = array();
    }
  }

Here is the caller graph for this function:

iCalComponent::ClearProperties ( type = null)

Clear all properties, or the properties matching a particular type.

Parameters:
string$typeThe type of property - omit for all properties

Definition at line 564 of file iCalendar.php.

                                           {
    if ( $type != null ) {
      // First remove all the existing ones of that type
      foreach( $this->properties AS $k => $v ) {
        if ( $v->Name() == $type ) {
          unset($this->properties[$k]);
          if ( isset($this->rendered) ) unset($this->rendered);
        }
      }
      $this->properties = array_values($this->properties);
    }
    else {
      if ( isset($this->rendered) ) unset($this->rendered);
      $this->properties = array();
    }
  }

Here is the caller graph for this function:

Clone this component (and subcomponents) into a confidential version of it.

A confidential event will be scrubbed of any identifying characteristics other than time/date, repeat, uid and a summary which is just a translated 'Busy'.

Definition at line 789 of file iCalendar.php.

                               {
    $confidential = clone($this);
    $keep_properties = array( 'DTSTAMP', 'DTSTART', 'RRULE', 'DURATION', 'DTEND', 'DUE', 'UID', 'CLASS', 'TRANSP', 'CREATED', 'LAST-MODIFIED' );
    $resource_components = array( 'VEVENT', 'VTODO', 'VJOURNAL' );
    $confidential->MaskComponents(array( 'VTIMEZONE', 'VEVENT', 'VTODO', 'VJOURNAL' ));
    $confidential->MaskProperties($keep_properties, $resource_components );
    if ( in_array( $confidential->GetType(), $resource_components ) ) {
      $confidential->AddProperty( 'SUMMARY', translate('Busy') );
    }
    foreach( $confidential->components AS $k => $v ) {
      if ( in_array( $v->GetType(), $resource_components ) ) {
        $v->AddProperty( 'SUMMARY', translate('Busy') );
      }
    }

    return $confidential;
  }

Collect an array of all parameters of our properties which are the specified type Mainly used for collecting the full variety of references TZIDs.

Definition at line 370 of file iCalendar.php.

                                                     {
    $values = array();
    foreach( $this->components AS $k => $v ) {
      $also = $v->CollectParameterValues($parameter_name);
      $values = array_merge( $values, $also );
    }
    foreach( $this->properties AS $k => $v ) {
      $also = $v->GetParameterValue($parameter_name);
      if ( isset($also) && $also != "" ) {
//        dbg_error_log( 'iCalendar', "::CollectParameterValues(%s) : Found '%s'", $parameter_name, $also);
        $values[$also] = 1;
      }
    }
    return $values;
  }
& iCalComponent::FirstNonTimezone ( type = null)

Get all sub-components, or at least get those matching a type.

Returns:
array an array of the sub-components

Definition at line 621 of file iCalendar.php.

                                             {
    foreach( $this->components AS $k => $v ) {
      if ( $v->GetType() != 'VTIMEZONE' ) return $this->components[$k];
    }
    $result = false;
    return $result;
  }
iCalComponent::GetComponents ( type = null,
normal_match = true 
)

Get all sub-components, or at least get those matching a type, or failling to match, should the second parameter be set to false.

Parameters:
string$typeThe type to match (default: All)
boolean$normal_matchSet to false to invert the match (default: true)
Returns:
array an array of the sub-components

Definition at line 671 of file iCalendar.php.

                                                               {
    $components = $this->components;
    if ( $type != null ) {
      foreach( $components AS $k => $v ) {
        if ( ($v->GetType() != $type) === $normal_match ) {
          unset($components[$k]);
        }
      }
      $components = array_values($components);
    }
    return $components;
  }
iCalComponent::GetPParamValue ( type,
parameter_name 
)

Get the value of the specified parameter for the first property matching the name.

Obviously this isn't so useful for properties which may occur multiply, but most don't.

Parameters:
string$typeThe type of property we are after.
string$typeThe name of the parameter we are after.
Returns:
string The value of the parameter for the property, or null in the case that there was no such property, or no such parameter.

Definition at line 552 of file iCalendar.php.

                                                    {
    foreach( $this->properties AS $k => $v ) {
      if ( $v->Name() == $type ) return $v->GetParameterValue($parameter_name);
    }
    return null;
  }
iCalComponent::GetProperties ( type = null)

Get all properties, or the properties matching a particular type.

Definition at line 518 of file iCalendar.php.

                                         {
    $properties = array();
    foreach( $this->properties AS $k => $v ) {
      if ( $type == null || $v->Name() == $type ) {
        $properties[$k] = $v;
      }
    }
    return $properties;
  }

Return an array of properties matching the specified path.

Returns:
array An array of iCalProp within the tree which match the path given, in the form [/]COMPONENT[/...]/PROPERTY in a syntax kind of similar to our poor man's XML queries. We also allow COMPONENT and PROPERTY to be !COMPONENT and !PROPERTY for ++fun.
Note:
At some point post PHP4 this could be re-done with an iterator, which should be more efficient for common use cases.

There is more to the path, so we recurse into that sub-part

Our input $path was not rooted, so we recurse further

Definition at line 843 of file iCalendar.php.

                                        {
    $properties = array();
    dbg_error_log( 'iCalendar', "GetPropertiesByPath: Querying within '%s' for path '%s'", $this->type, $path );
    if ( !preg_match( '#(/?)(!?)([^/]+)(/?.*)$#', $path, $matches ) ) return $properties;

    $adrift = ($matches[1] == '');
    $normal = ($matches[2] == '');
    $ourtest = $matches[3];
    $therest = $matches[4];
    dbg_error_log( 'iCalendar', "GetPropertiesByPath: Matches: %s -- %s -- %s -- %s\n", $matches[1], $matches[2], $matches[3], $matches[4] );
    if ( $ourtest == '*' || (($ourtest == $this->type) === $normal) && $therest != '' ) {
      if ( preg_match( '#^/(!?)([^/]+)$#', $therest, $matches ) ) {
        $normmatch = ($matches[1] =='');
        $proptest  = $matches[2];
        foreach( $this->properties AS $k => $v ) {
          if ( $proptest == '*' || (($v->Name() == $proptest) === $normmatch ) ) {
            $properties[] = $v;
          }
        }
      }
      else {
        foreach( $this->components AS $k => $v ) {
          $properties = array_merge( $properties, $v->GetPropertiesByPath($therest) );
        }
      }
    }

    if ( $adrift ) {
      foreach( $this->components AS $k => $v ) {
        $properties = array_merge( $properties, $v->GetPropertiesByPath($path) );
      }
    }
    dbg_error_log('iCalendar', "GetPropertiesByPath: Found %d within '%s' for path '%s'\n", count($properties), $this->type, $path );
    return $properties;
  }

Here is the caller graph for this function:

Get the value of the first property matching the name.

Obviously this isn't so useful for properties which may occur multiply, but most don't.

Parameters:
string$typeThe type of property we are after.
Returns:
string The value of the property, or null if there was no such property.

Definition at line 536 of file iCalendar.php.

                              {
    foreach( $this->properties AS $k => $v ) {
      if ( $v->Name() == $type ) return $v->Value();
    }
    return null;
  }

Return the type of component which this is.

Definition at line 500 of file iCalendar.php.

                     {
    return $this->type;
  }

Here is the caller graph for this function:

iCalComponent::iCalComponent ( content = null)

@-

A basic constructor

Definition at line 339 of file iCalendar.php.

                                            {
    $this->type = "";
    $this->properties = array();
    $this->components = array();
    $this->rendered = "";
    if ( $content != null && (gettype($content) == 'string' || gettype($content) == 'array') ) {
      $this->ParseFrom($content);
    }
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Return true if the person identified by the email address is down as an attendee or organizer for this meeting.

Parameters:
string$emailThe e-mail address of the person we're seeking.
Returns:
boolean true if we found 'em, false if we didn't.

an organizer is an attendee, as far as we're concerned

Definition at line 652 of file iCalendar.php.

                                {
    if ( !preg_match( '#^mailto:#', $email ) ) $email = 'mailto:'.$email;
    if ( $this->IsOrganizer($email) ) return true; 
    $props = $this->GetPropertiesByPath('!VTIMEZONE/ATTENDEE');
    foreach( $props AS $k => $prop ) {
      if ( $prop->Value() == $email ) return true;
    }
    return false;
  }

Here is the call graph for this function:

Return true if the person identified by the email address is down as an organizer for this meeting.

Parameters:
string$emailThe e-mail address of the person we're seeking.
Returns:
boolean true if we found 'em, false if we didn't.

Definition at line 636 of file iCalendar.php.

                                 {
    if ( !preg_match( '#^mailto:#', $email ) ) $email = 'mailto:'.$email;
    $props = $this->GetPropertiesByPath('!VTIMEZONE/ORGANIZER');
    foreach( $props AS $k => $prop ) {
      if ( $prop->Value() == $email ) return true;
    }
    return false;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Mask components, removing any that are not of the types in the list.

Parameters:
array$keepAn array of component types to be kept

Definition at line 750 of file iCalendar.php.

                                   {
    foreach( $this->components AS $k => $v ) {
      if ( ! in_array( $v->GetType(), $keep ) ) {
        unset($this->components[$k]);
        if ( isset($this->rendered) ) unset($this->rendered);
      }
      else {
        $v->MaskComponents($keep);
      }
    }
  }
iCalComponent::MaskProperties ( keep,
component_list = null 
)

Mask properties, removing any that are not in the list.

Parameters:
array$keepAn array of property names to be kept
array$component_listAn array of component types to check within

Definition at line 768 of file iCalendar.php.

                                                         {
    foreach( $this->components AS $k => $v ) {
      $v->MaskProperties($keep, $component_list);
    }

    if ( !isset($component_list) || in_array($this->GetType(),$component_list) ) {
      foreach( $this->components AS $k => $v ) {
        if ( ! in_array( $v->GetType(), $keep ) ) {
          unset($this->components[$k]);
          if ( isset($this->rendered) ) unset($this->rendered);
        }
      }
    }
  }

Here is the call graph for this function:

iCalComponent::ParseFrom ( content)

Parse the text $content into sets of iCalProp & iCalComponent within this iCalComponent.

Parameters:
string$contentThe raw RFC2445-compliant iCalendar component, including BEGIN:TYPE & END:TYPE

Definition at line 391 of file iCalendar.php.

                                 {
    $this->rendered = $content;
    $content = $this->UnwrapComponent($content);

    $type = false;
    $subtype = false;
    $finish = null;
    $subfinish = null;

    $length = strlen($content);
    $linefrom = 0;
    while( $linefrom < $length ) {
      $lineto = strpos( $content, "\n", $linefrom );
      if ( $lineto === false ) {
        $lineto = strpos( $content, "\r", $linefrom );
      }
      if ( $lineto > 0 ) {
        $line = substr( $content, $linefrom, $lineto - $linefrom);
        $linefrom = $lineto + 1;
      }
      else {
        $line = substr( $content, $linefrom );
        $linefrom = $length;
      }
      if ( preg_match('/^\s*$/', $line ) ) continue;
      $line = rtrim( $line, "\r\n" );
//      dbg_error_log( 'iCalendar',  "::ParseFrom: Parsing line: $line");

      if ( $type === false ) {
        if ( preg_match( '/^BEGIN:(.+)$/', $line, $matches ) ) {
          // We have found the start of the main component
          $type = $matches[1];
          $finish = "END:$type";
          $this->type = $type;
          dbg_error_log( 'iCalendar', "::ParseFrom: Start component of type '%s'", $type);
        }
        else {
          dbg_error_log( 'iCalendar', "::ParseFrom: Ignoring crap before start of component: $line");
          // unset($lines[$k]);  // The content has crap before the start
          if ( $line != "" ) $this->rendered = null;
        }
      }
      else if ( $type == null ) {
        dbg_error_log( 'iCalendar', "::ParseFrom: Ignoring crap after end of component");
        if ( $line != "" ) $this->rendered = null;
      }
      else if ( $line == $finish ) {
        dbg_error_log( 'iCalendar', "::ParseFrom: End of component");
        $type = null;  // We have reached the end of our component
      }
      else {
        if ( $subtype === false && preg_match( '/^BEGIN:(.+)$/', $line, $matches ) ) {
          // We have found the start of a sub-component
          $subtype = $matches[1];
          $subfinish = "END:$subtype";
          $subcomponent = $line . "\r\n";
          dbg_error_log( 'iCalendar', "::ParseFrom: Found a subcomponent '%s'", $subtype);
        }
        else if ( $subtype ) {
          // We are inside a sub-component
          $subcomponent .= $this->WrapComponent($line);
          if ( $line == $subfinish ) {
            dbg_error_log( 'iCalendar', "::ParseFrom: End of subcomponent '%s'", $subtype);
            // We have found the end of a sub-component
            $this->components[] = new iCalComponent($subcomponent);
            $subtype = false;
          }
//          else
//            dbg_error_log( 'iCalendar', "::ParseFrom: Inside a subcomponent '%s'", $subtype );
        }
        else {
//          dbg_error_log( 'iCalendar', "::ParseFrom: Parse property of component");
          // It must be a normal property line within a component.
          $this->properties[] = new iCalProp($line);
        }
      }
    }
  }

Here is the call graph for this function:

Here is the caller graph for this function:

iCalComponent::Render ( restricted_properties = null)

Renders the component, possibly restricted to only the listed properties.

Definition at line 811 of file iCalendar.php.

                                                  {

    $unrestricted = (!isset($restricted_properties) || count($restricted_properties) == 0);

    if ( isset($this->rendered) && $unrestricted )
      return $this->rendered;

    $rendered = "BEGIN:$this->type\r\n";
    foreach( $this->properties AS $k => $v ) {
      if ( method_exists($v, 'Render') ) {
        if ( $unrestricted || isset($restricted_properties[$v]) ) $rendered .= $v->Render() . "\r\n";
      }
    }
    foreach( $this->components AS $v ) {   $rendered .= $v->Render();  }
    $rendered .= "END:$this->type\r\n";

    $rendered = preg_replace('{(?<!\r)\n}', "\r\n", $rendered);
    if ( $unrestricted ) $this->rendered = $rendered;

    return $rendered;
  }
iCalComponent::SetComponents ( new_component,
type = null 
)

Sets some or all sub-components of the component to the supplied new components.

Parameters:
arrayof iCalComponent $new_components The new components to replace the existing ones
string$typeThe type of components to be replaced. Defaults to null, which means all components will be replaced.

Definition at line 718 of file iCalendar.php.

                                                         {
    if ( isset($this->rendered) ) unset($this->rendered);
    if ( count($new_component) > 0 ) $this->ClearComponents($type);
    foreach( $new_component AS $k => $v ) {
      $this->components[] = $v;
    }
  }

Here is the call graph for this function:

iCalComponent::SetProperties ( new_properties,
type = null 
)

Set all properties, or the ones matching a particular type.

Definition at line 585 of file iCalendar.php.

                                                          {
    if ( isset($this->rendered) && count($new_properties) > 0 ) unset($this->rendered);
    $this->ClearProperties($type);
    foreach( $new_properties AS $k => $v ) {
      $this->AddProperty($v);
    }
  }

Here is the call graph for this function:

Set the type of component which this is.

Definition at line 508 of file iCalendar.php.

                            {
    if ( isset($this->rendered) ) unset($this->rendered);
    $this->type = $type;
    return $this->type;
  }

Here is the caller graph for this function:

This unescapes the (CRLF + linear space) wrapping specified in RFC2445.

According to RFC2445 we should always end with CRLF but the CalDAV spec says that normalising XML parsers often muck with it and may remove the CR. We accept either case.

Definition at line 476 of file iCalendar.php.

                                       {
    return preg_replace('/\r?\n[ \t]/', '', $content );
  }

Here is the caller graph for this function:

iCalComponent::VCalendar ( extra_properties = null)

Apply standard properties for a VCalendar.

Parameters:
array$extra_propertiesKey/value pairs of additional properties

Definition at line 354 of file iCalendar.php.

                                                 {
    $this->SetType('VCALENDAR');
    $this->AddProperty('PRODID', '-//davical.org//NONSGML AWL Calendar//EN');
    $this->AddProperty('VERSION', '2.0');
    $this->AddProperty('CALSCALE', 'GREGORIAN');
    if ( is_array($extra_properties) ) {
      foreach( $extra_properties AS $k => $v ) {
        $this->AddProperty($k,$v);
      }
    }
  }

Here is the call graph for this function:

This imposes the (CRLF + linear space) wrapping specified in RFC2445.

According to RFC2445 we should always end with CRLF but the CalDAV spec says that normalising XML parsers often muck with it and may remove the CR. We output RFC2445 compliance.

In order to preserve pre-existing wrapping in the component, we split the incoming string on line breaks before running wordwrap over each component of that.

Definition at line 488 of file iCalendar.php.

                                     {
    $strs = preg_split( "/\r?\n/", $content );
    $wrapped = "";
    foreach ($strs as $str) {
      $wrapped .= preg_replace( '/(.{72})/u', '$1'."\r\n ", $str ) ."\r\n";
    }
    return $wrapped;
  }

Here is the caller graph for this function:


Member Data Documentation

Definition at line 325 of file iCalendar.php.

Definition at line 318 of file iCalendar.php.

Definition at line 332 of file iCalendar.php.

Definition at line 311 of file iCalendar.php.


The documentation for this class was generated from the following file: