PHPCalFeed

A simple PHP script for providing calendar feeds for your website in a variety of different formats including iCalendar, RSS, JSON and XML.

1. Why
2. Requirements
3. User Guide
4. Licence
5. Credits

1 Why?

Do you run a website with an events page? Does your site provide any kind of data feed for those events? If not, you might want to consider adding one. This allows users to have your events appear directly on their calendar as you publish them, simplifying the process of discovering, making time for, and attending your event.

PHPCalFeed aims to make the addition of a calendar feed as easy as possible. It is the "swiss army knife" of calendar feed setup; simple to drop into your site and flexible enough to suit a wide variety of setups. You provide the event information in a single file, and the script serves it up to visitors in multiple different feed formats.

2 Requirements

Essential

• Requires a webserver running PHP 5.3 or later
• Requires write permission to its directory on the webserver

Optional

• PHP's [JSON][json ext] and [Multibyte String][mbstring ext] extensions are required for JSON input and output
• PHP's [XML DOM][dom ext] and [libXML][libxml ext] extensions are required for XML and XHTML output
• PHP must be configured to allow remote requests in order to use remote file input
• PHP's OpenSSL extension is required for remote requests over HTTPS

3 User Guide

3.1 Installation

To install the script, copy the following files to your webserver using your FTP client, SCP client or similar:

• calendar.php (the PHP script)
• calendar.xsd (schema definition for XML)
• calendar-cal.css (stylesheet for HTML calendar)
• calendar-sub.css (stylesheet for subscribe button)
• calendar-sub.png (icon image for subscribe button)

3.2 Provide Event Info

The script can read event info from a CSV, JSON or ICalendar file. It can also extract event info from HTML. A CSV file is the simplest of these options. Events can be one-off occurrences or recurring events which repeat on a schedule.

See the following two sections for general information on how to set up your calendar's input file:

• 3.2.1 Local File
• 3.2.2 Remote File

And see the following sections for how to prepare the input file in your chosen data format:

• 3.2.3 CSV Input
• 3.2.4 JSON Input
• 3.2.5 ICalendar Input
• 3.2.6 HTML Input

The following sections describe how to set up input from several commonly-used sources:

• 3.2.7 Google Calendar Input
• 3.2.8 Yahoo Calendar Input
• 3.2.9 Microsoft Outlook CSV Input
• 3.2.10 Lanyrd Input
• 3.2.11 Meetup.com Input
• 3.2.12 OpenACalendar Input

3.2.1 Local File

To have PHPCalFeed read from a file on your own server, create a file called calendar-master with the appropriate file extension (see following sections). Copy the file to your webserver into the same directory as the calendar.php script. Delete the calendar-config.php file and calendar.html file if they are present. Now visit your website's calendar by entering its URL into the browser. For example:

http://your-website.com/path-to-calendar/calendar.php

The script should detect the file, identify its format automatically, and populate your website's calendar.

3.2.2 Remote File

As an alternative to a file on your own server, PHPCalFeed can read from a file on a different server. This is useful if you wish to use another calendar feed as the input, such as a public Google calendar (see Google Calendar Input for more on this). Note that your URL should begin with the http:// or https:// protocol and not webcal://. In order to connect to a remote URL, the allow_url_fopen option must be enabled for your server's PHP installation. In addition, connecting to a secure https:// URL requires the OpenSSL extension to be enabled for your installation.

To use a remote file, create the file calendar-config.php in the script directory, if it doesn't already exist, and define the url property by copying the code from the section below into the file, and replacing the example URL. Make sure to copy the code exactly, with the same letter cases, punctuation, etc:

<?php
return array(
	'url' => 'http://example.com/some-calendar.csv'
);

If the URL has the appropriate file extension (see following sections) then the script will identify the file's format automatically. Otherwise, the format must be defined explicitly using the format property, as follows:

<?php
return array(
	'url' => 'http://example.com/some-calendar',
	'format'=>'csv-remote'
);

Now delete the calendar.html file if it already exists, and visit your website's calendar by entering its URL into the browser. For example:

http://your-website.com/path-to-calendar/calendar.php

Your website's calendar will be populated from the remote file.

3.2.3 CSV Input

CSV stands for Comma-Separated Values and is a simple text format compatible with most spreadsheet applications. To supply the event information in CSV format, use the .csv file extension - for example, calendar-master.csv. Your CSV file should contain columns as follows, in any order, each with a heading on the first row of the file:

• name (required) - the title of the event
• date (required) - either a one-off date in yyyy-mm-dd format, or the spec for a recurring event as described in the Event Recurrence Specification section below. For example, 2014-02-28 or weekly on thu.
• time (optional) - the time of day at which the event starts, in the following 24 hour time format: hh:mm. For example, 21:30. Defaults to midnight.
• duration (optional) - the length of time the event continues for, as a number of days, minutes and hours in the following format: [0d][0h][0m]. For example, 3h 30m. Defaults to 24 hours.
• description (optional) - a description of the event
• url (optional) - a link to more information about the event

Below is an example:

| Name | Date | Time | Description | |-----------------|-----------------------|----------|-------------------------------------| | Halloween Party | 2013-10-31 | 20:30 | Come and have a spooktacular time! | | Cool Society | monthly on 1st tue | 18:00 | Monthly meetup for cool people only |

PHPCalFeed can read CSV data directly from a Microsoft Outlook export. For more information see Microsoft Outlook CSV Input

By default, the script will assume the data in your CSV file is separated by comma , characters. For other separators such as tab or semicolon, create the config file calendar-config.php if it doesn't already exist, and define the delimiting character with the "delimiter", as follows:

<?php
return array(
	'format' => 'csv-local',
	'delimiter' => "\t"      // a tab
);

3.2.4 JSON Input

JSON is a simple data format using nested "objects" with named "properties". Note that to use JSON input, the [JSON][json ext] and [Multibyte String][mbstring ext] extensions must be enabled for your server's PHP installation.

To supply the event information in JSON format, use the file extension .json

• for example, calendar-master.json. Your JSON file should contain a root object with the following properties:

• name (optional) - the title of the calendar, as a string
• description (optional) - a description of the calendar, as a string
• url (optional) - a link back to the calendar or related website, as a string
• events (optional)_ - an array of objects describing one-off events (see below)
• recurring-events(optional) - an array of objects describing recurring events (see below)

Each one-off event in the events array should be an object with the following properties:

• name (required) - the title of the event, as a string
• date (required) - the date on which the event starts, as a string in the following format: yyyy-mm-dd.
• time (optional) - the time of day at which the event starts, as a string in the following 24 hour time format: hh:mm. For example, 23:30. Defaults to midnight.
• duration (optional) - the length of time the event continues for, as a string containing a number of days, hours and minutes as follows: [0d][0h][0m]. For example, 3h 30m. Defaults to 24 hours.
• description (optional) - a description of the event, as a string
• url (optional) a link to more information about the event, as a string

Each recurring event in the recurring-events array should be an object with the following properties:

• name (required) - the title of the event, as a string
• recurrence (required) - a string specifying how often the event occurs. For details of the format of this property see the [Event Recurrence Specificat