====== qCal iCalendar Library for PHP5 ======

qCal is an open-source, object-oriented, iCalendar library for PHP5. It is written using common design patterns and best practices. As of right now, the latest version is [[http://code.google.com/p/qcal/downloads/list|0.0.2]].

===== Installation =====

  * [[Installation#downloading_and_extracting_the_library|Downloading and extracting the library]]
  * [[Installation#uploading_to_your_web_server|Uploading to your web server]]
  * [[Installation#setting_up_autoload|Setting up autoload]]
  * [[Installation#running_the_unit_tests|Running the unit tests]]

===== iCalendar v2.0 =====

qCal is a direct implementation of the [[http://www.ietf.org/rfc/rfc2445.txt|iCalendar 2.0 specification]]. If you aren't familiar with the specification, I would recommend you at least glance over the following section before attempting to work with qCal. qCal assumes at least a rudimentary understanding of the spec. I will do my best to summarize it here, but it is an extremely long and complex specification, so to completely explain it would be beyond the scope of this documentation. The specification will always be the best possible reference. And if all else fails, [[http://lukevisinoni.com/contact/|contact me]] directly and I will do my best to help you.

Understanding the specifics of iCalendar's syntax and grammar is not necessary in order to use this library, but as I stated before, it would be in your interest to at least glance over the rules for syntax and grammer in the specification.

Rather than explain the specification itself, I am going to explain how qCal's various components relate to the specification, starting with value types.


  * [[iCalendar_value_types|iCalendar Value Types]]
  * [[iCalendar_object|iCalendar Object]]
  * [[iCalendar_components|iCalendar Components]]
  * [[iCalendar_component_properties|iCalendar Component Properties]]
  * [[iCalendar_component_property_parameters|iCalendar Component Property Parameters]]

===== API Reference =====

Once you have a decent understanding of what components, properties, parameters and value types are (by reading the section above), you can finally start learning the ins and outs of working with them in this library. I wouldn't spend too much time reading about all of those things though. Working with the library is definitely the easiest way to learn them.

The following section is meant as a reference guide to all of the important classes within this library. 

==== Dates and Times ====

qCal comes packaged with a mini-library capable of doing some pretty nifty things with dates and times. It consists of:

  * **[[Date|qCal_Date]]** - Use this class when you need only a date and not a time. Example: "1986-04-23" 
  * **[[Timezone|qCal_Timezone]]** - Use this class to apply a timezone offset to any of the time components. Example: "PST (UTC -8 hours)"
  * **[[Time|qCal_Time]]** - Use this class when you need only a time and not a date. Example: "08:30:00"
  * **[[DateTime|qCal_DateTime]]** - Use this class when you need a date and a time. Example: "1986-04-23 08:30:00 PST"
  * **[[DateTime_Duration|qCal_Datetime_Duration]]** - Use this class to represent a duration of time. Example: "four weeks, three days and 5 hours"
  * **[[DateTime_Period|qCal_DateTime_Period]]** - Use this class to represent a period in time. Example: "From April 23rd, 2008 to April 26th, 2008"
  * **[[DateTime_Recur|qCal_DateTime_Recur]]** - Use this class to represent a date/time recurrence pattern. Example: "Yearly on April 23rd at 4:00pm" or "Every third Tuesday of April and May from now until five years from now"

==== Components ====

=== qCal_Component ===

This class and its descendants are used in qCal to represent [[iCalendar components]]. Each of the component types defined in the iCalendar specification has a corresponding class in qCal. In the iCalendar specification, component names are prefixed with a "V", which is a remnant of the old vCalendar spec that came before it. The only exceptions are with sub-components. The [[iCalendar_components#time_zone|VTIMEZONE component]] has two sub-components which do not have the "V" prefix (STANDARD and DAYLIGHT)

All of the following components work in the same basic manner, so first read about the qCal_Component base class and then read about the specific classes below.

**[[qCal_Component|Base qCal_Component class]]**

  * [[qCal_Component_Vcalendar]]
  * [[qCal_Component_Valarm]]
  * [[qCal_Component_Vevent]]
  * [[qCal_Component_Vfreebusy]]
  * [[qCal_Component_Vjournal]]
  * [[qCal_Component_Vtimezone]]
  * [[qCal_Component_Vtodo]]


==== Component Properties ====

This section will describe how to work with component properties.

==== Component Property Parameters ====

This section will describe how to work with component property parameters.

==== Value Types ====

This section will describe how to work with value types.

==== Parsing iCalendar Files ====

This section will describe how to work with parsers.

==== Rendering qCal Components ====

This section will describe how to work with renderers.