Greg Westin: Using PHP iCalendar to View iCal Calendars Online

Apple's iCal application for OS X has a number of interesting features, including the ability to 'publish' calendars to the web so that other users can subscribe to them or view them online. Apple encourages its customers to subscribe to their .Mac service, which includes such useful things as a server to publish your calendars to and a proprietary application that converts them into web pages so that they can be viewed online.

That's all well and good, of course, but if you don't subscribe to Apple's .Mac service, you're basically left in the cold by Apple. In another article, I describe how to enable WebDAV on your own OS X computer, so that you can publish to your own computer and let the world get your calendars straight from the source, without Apple as an intermediary. If you haven't set such a system up yet, check out Setting up WebDAV on OSX for use with iCal. You don't have to publish your calendars, of course, in order to view them online. You could simply export them to an appropriate folder, for example. However, if you want your calendars to be automatically updated online whenever you make changes, publishing with WebDAV is definitely your best option.

Getting the calendars published, though, is only half of the job. Even once they're published, they can only be subscribed to or downloaded, not viewed online. For this, you need a utility called PHP iCalendar, an open source project that aims to provide the same sort of service that .Mac provides, in terms of being able to view your iCal files. In fact, I haven't seen calendars on .Mac in a while, but unless they've made some dramatic improvements, PHP iCalendar may well be superior now. For example, it provides support for viewing all of your calendars at once, while the last version of .Mac I saw only allowed you to view one calendar at a time. PHP iCalendar can also display your to-do items, which I haven't seen on any .Mac calendars.

Nota bene: A site called iCal Exchange will deal with hosting your calendars for you, and provides a way to display them, I believe using PHP iCalendar. So if you don't want to deal with running this on your own computer, check them out! Also, keep in mind that these instructions are for the normal, client version of OS X. OS X Server has all sorts of proprietary systems set up, so these instructions will not work without some modification. I don't have a copy of OS X Server to test, or I would also have instructions for that system. Someone wrote to me to point out the limited instructions by Joel Rennich, which describe how to enable WebDAV and PHP iCalendar on OS X Server. There is no information about security, but at least you can get things working.

PHP iCalendar is still undergoing very active development, so these instructions may occasionally be slightly out of date. Each update I download changes significantly from the previous version, but I have kept this page current so far, and plan to as long as this page is online. Please let me know if you have any problems getting PHP iCalendar to work using this page.

Before installing PHP iCalendar, you need to (surprise!) enable PHP. This requires another extension to Mac OS X, like WebDAV. This also comes pre-installed on Mac OS X, and can be enabled quickly. Note that this version of PHP works fine for PHP iCalendar, but if you want a fully-featured and current version of PHP, follow Marc Liyanage's instructions.

To do this, though, you need to be able to use the Terminal to edit text files. If you don't know how to do this, read The Quick and Dirty on the Terminal and Text Editors quickly before going on. When you're ready, simply open up a Terminal, then open the file /etc/httpd/httpd.conf (sudo vim /etc/httpd/httpd.conf if you use vim), and edit the following lines. First, remove the # from the beginning of the lines that say LoadModule php4_module libexec/httpd/libphp4.so and AddModule mod_php4.c. Next, search for x-httpd-php to make sure the following lines exist (they were removed from at least one version of OS X); if they do not, search for AddType app and add the following lines after the AddType for application/x-tar:

    AddType application/x-httpd-php .php
    AddType application/x-httpd-php-source .phps

Finally, you want to make sure your computer will automatically recognize that a file named index.php is a default page to show if a directory is requested. To do this, you need to search for DirectoryIndex and change the DirectoryIndex line to include index.php. On my site, index.php is the first listing, because I always want it to be displayed, if it exists, rather than a file called index.html or index.htm or index.shtml or anything like that. You might be more likely to use HTML, however, and so might want to list index.php after index.html. At any rate, you'll end up with something like this:

<IfModule mod_dir.c>
    DirectoryIndex index.html index.php
</IfModule>

Now, close that file, then simply restart your web server (or start it for the first time, as the case may be), by typing sudo apachectl graceful.

Now, back to PHP iCalendar. First of all, you need to download the file. Open up a Terminal, type cd /Library/WebServer/Documents to move to the right directory, and then type curl -O http://voxel.dl.sourceforge.net/sourceforge/phpicalendar/phpicalendar-2.2.tgz. To unstuff it, simply type tar -xzvf phpicalendar-2.2.tgz. Next, delete the old file with rm phpicalendar-2.2.tgz. To change the name of the folder from phpicalendar-2.2 to simply phpicalendar, type mv phpicalendar-2.2/ phpicalendar. Finally, type cd phpicalendar. You're now in the directory with all the PHP iCalendar files. The only thing you should need to modify is the config.inc.php file.

On line 24, you need to edit the variable to point to the location of your calendars. If you haven't published any yet, and are sure you want to use phpicalendar, you can publish into the calendars folder in the phpicalendar directory if you want to, but I wouldn't recommend it, because you might want to get rid of PHP iCalendar someday. You don't want your calendars, which may well be used for all sorts of other things than PHP iCalendar, to be stuck in the phpicalendar directory. If you used my instructions for setting up WebDAV for iCal, you'd need line 24 to look like this:

$calendar_path = "../ical";

Actually, you should use the full path, i.e.:

$calendar_path = "/Library/WebServer/Documents/ical";

If you have phpicalendar in a folder other than /Library/WebServer/Documents, or if you have your calendars someplace other than /Library/WebServer/Documents/ical, you'll need to change this appropriately.

The only other crucial change you should make is the name of the default calendar, on line 11. The default, which displays all of your calendars combined in one display, is nice so long as you don't have too many calendars. If you want the default to be a single calendar, simply change the default_cal variable to the name of the calendar you use the most, removing ".ics" from the end, substituting "32" for spaces, and making sure capitalization is correct. Make sure you use the correct file name - if you published a calendar named "Soccer Schedule" the line will look like this:

$default_cal = "Soccer32Schedule";

and not

$default_cal = "Soccer Schedule"; or
$default_cal = "soccer32schedule";

Another feature that may be crucial for you, depending upon the location of your server, is setting the time zone. In order to set your time zone (or choose the same time zone as the server), find the value you'd like in the TIMEZONES file, and use it in line 23 of config.inc.php:

$timezone = 'America/New_York';

Finally, you should also change the value of $default_path on line 29 to an appropriate value for your system. You can also, of course, change the values for the other variables, if you, for example, prefer the week view to the day view, speak Dutch, or want the week to start on Wednesday. Those should be self explanatory. I changed the values of $default_view, $week_start_day, all the event_lines variables, $allow_webcals, and $show_completed. I also added some webcals I use to $list_webcals.

Now, you're all set. Just go to http://[your ip or domain]/phpicalendar/, and you'll see your default calendar. For example, if you have your own domain name, you'd use something like http://www.mydomain.net/phpicalendar/. If, on the other hand, you don't have your own domain name, you'd use your IP address (found in System Preferences>Network): http://140.247.181.139/phpicalendar/.

Please let me know whether these instructions work for you or not, so that this document can stay current, useful, and readable.

Enjoy!

Greg

FAQ:

How do I password protect my phpicalendar directory, so that only I can see my calendars online?

If you used my instructions for setting up WebDAV for iCal, you should already have a password file ready to use for this purpose. So long as the username/password combos you entered there are OK to reuse here, all you have to do is add a few lines to the httpd.conf file you created in your /etc/httpd folder. If you want to add new users to your password file, you can do so in the same way you added users in the WebDAV setup instructions. If you haven't already created a password file, or you want to authenticate PHP iCalendar users differently from the users uploading or downloading calendars, you need to create a new password file as follows (skip the next paragraph if you have a password file you want to use):

First, make the directory that will contain the password file (if you don't already have this directory from using my WebDAV instructions): sudo mkdir /etc/httpd/passwords. To make a password file, we use the 'htdigest' command. This uses "Digest" authentication, which some browsers can't handle, but it is much more secure than the alternative, which means sending your password in plain text. The first time you use the command, use htdigest with the -c option to create the file (remember to substitute the username you want for 'greg'): sudo htdigest -c /etc/httpd/passwords/phpicalendar "PHP iCalendar access" greg. For any other users you want to add, use a command like sudo htdigest /etc/httpd/passwords/phpicalendar "PHP iCalendar access" guest. For each of these, of course, you will be asked for a password for the given user.

Now you need to edit your /etc/httpd/httpd.conf file (vim /etc/httpd/httpd.conf) to control access to the phpicalendar directory based upon that password file. If you used the WebDAV for iCal instructions to set up the password file, substitute /etc/httpd/passwords/webdav.digest for /etc/httpd/passwords/phpicalendar, and be sure to match the "AuthName" line to the phrase you put in quotes when creating the relevant users with htdigest. Also, if you want to selectively allow only certain users, rather than any user in your password file (including any 'guest' or 'anonymous' users you may have added!), use require user greg melissa, substituting the appropriate usernames, separated by spaces, rather than require valid-user. Simply add the following to the file, in an appropriate location (if you used my instructions for setting up WebDAV, put this just before the other <Location> statement; otherwise, put it before the line that says <Directory "/Library/WebServer/Documents">):

<Location /phpicalendar>
	AuthType Digest
	AuthName "PHP iCalendar access"
	AuthDigestFile "/etc/httpd/passwords/phpicalendar"
	require valid-user
</Location>

Go ahead and save that file and quit vim, and then use apachectl graceful to restart your web server. Now, if you fire up your web browser, you should get a prompt asking you for a password to access your PHP iCalendars.