Building Your Startup: Exporting iCal Files into Calendar Events

Final product image
What You'll Be Creating

Introduction

This tutorial is part of the Building Your Startup With PHP series on Envato Tuts+. In this series, I'm guiding you through launching a startup from concept to reality using my Meeting Planner app as a real-life example. Every step along the way, I'll release the Meeting Planner code as open-source examples you can learn from. I'll also address startup-related business issues as they arise.

I'm also pleased to announce that Meeting Planner is ready to try out. You can send meeting invitations, gather feedback from your participant, and finalize the meeting, importing the iCal file I'll describe today into your calendars. So, visit MeetingPlanner.io and give it a try.

What Does This Episode Cover?

Building Your Startup - Example Invite File in Webmail

In the last tutorial, I described how I constructed command links and coded operations for participants who begin responding to email invitations, i.e. viewing the meeting page or accepting or rejecting a place or time.

I also mentioned how a woman I'd been dating suggested that she didn't know if or when she'd see me again without a meeting planner invitation, which I soon provided. And then she said she wouldn't know when or where to show up without a Google calendar entry. In today's tutorial, I'll describe how I built the iCal feature to deliver an .ics file she could import for a successful date. It's always helpful to have someone motivating development, but it's usually been colleagues or a development manager.

Just a reminder, all of the code for Meeting Planner is written in the Yii2 Framework for PHP. If you'd like to learn more about Yii2, check out our parallel series Programming With Yii2 at Envato Tuts+. 

I do participate in the comment threads below and am especially interested if you have additional ideas or want to suggest topics for future tutorials. You can also reach me on Twitter @reifman.

What Is an iCal File?

Defining iCalendar, Wikipedia says:

iCalendar is a computer file format which allows Internet users to send meeting requests and tasks to other Internet users, via email, or sharing files with an extension of .ics. 

Basically, it's a file with the .ics extension that includes pertinent information about a meeting, the organizer and attendees, the date, time and duration, the location and more, all in a format that a variety of platforms and calendar services can recognize.

While iCalendar has advanced features, at this stage of Meeting Planner's Minimum Viable Product (MVP), I wanted to ensure that our scheduled meetings could be easily imported into Google Calendar, Apple Calendar and Microsoft Outlook and be recognized by web mail services. I'll work later to extend its functionality.

Through earlier tutorials, I'd built the functionality that collected all the necessary information such as participants, dates and times and locations. Now, I just needed to publish the event details in an attachment and deliver it via email.

Building the .ics File

Instead of writing .ics code from scratch, I began with Ahmad Amin's ics File Generator and customized it. I placed the code in /common/models/Calendar.php

iCal files are different dependent on who the user is. In other words, they must be personalized for delivery. Primarily, the links back to Meeting Planner need to be customized for authentication to the holder of that particular .ics file.

During the Meeting finalization process, we build an event file for each attendee with unique, authenticated links:

Within the Meeting model, the buildCalendar method puts together all the data the generator will need for each user:

If there's a location (for in-person meetings), I include a link to the place's website (if available) and an address for embedded maps. I've decide to code dates and times in UTC format for simplicity.

The common meeting information is set up, and then the organizer and attendees are added.

Here's what a sample file looks like when it's complete:

Delivering the .ics File as an Attachment

In this earlier tutorial, I described using Yii2's built-in mailing support with the SwiftMailer extension to deliver meeting invitations. For transport delivery, I used Mailgun's SMTP service integration. 

Certainly, in the past, integrating attachments into messages was complicated, but now it's pretty easy with Yii. Here's the code to add the file to the outbound meeting invitation:

I just needed to use the $icsPath returned above and use the attachContent method to include it with the invitation email.

Here's what it looked like when it arrived in Gmail:

Building a Startup iCal Files - Gmail Invitation

When I opened the invitation file in Mac OS, Apple Calendar presented this first step to select a calendar to add the event to:

Building a Startup iCal Files - Apple Calendar Add Event Dialog Box

Here's what it looks like in my calendar's day view:

Building a Startup iCal Files - Apple Calendar Day View of Event

Once the event is added, it will look like this when you click on it:

Building a Startup iCal Files - Apple Calendar Right Pane View of Event

Overall, event generation turned out to be a fairly modest amount of work and successful in its implementations. Alpha people were impressed, and we used it for actual in-person meetings.

Issues During Development

While I was learning about .ics and experimenting with it, my webmail accounts on FastMail only intermittently recognized my .ics files as calendar invites. I needed to update the properties I included for it to be recognized in a friendly manner.

More correct structuring of the .ics file contents allowed FastMail to recognize the attachment automatically:

Building a Startup iCal Files - FastMail Recognizing ics File as Event

Unfortunately, its Add to Calendar button links to its own calendar, which I don't use. Again, to add to Apple Calendar, as with Gmail, I had to download and open the .ics file. 

Mac OS seemed to recognize the files as soon as they were opened. It would direct me towards a couple of steps of creating an Apple Calendar event (shown above).

I also needed to set a unique ID for the events so that we could send updates in the future. For now, our database meeting ID with '@meetingplanner.io' suffices, e.g. uid = [email protected].

Ensuring that time zones were adequately delivered in .ics file formats required a bit of additional research. For simplicity, I'm relying on Amin's ics generator to code dates and times in UTC format. I have more work in Meeting Planner to manage time zones for users.

I'd also left out duration and end time from Meeting Planner. This will be something I have to patch soon, likely just adding a duration (in hours) for the average meeting and allowing people to extend it as necessary.

Future Issues

Ultimately, I'd like Meeting Planner to use a broader extent of iCal's functionality. Initially, I just wanted to get the core functionality working for the MVP. Here are a few ideas below.

I may want to create a user setting in Meeting Planner that would add alarms to people's calendar entries. In iCal, this is called VALARM, e.g.:

When people update the original event, even after it's finalized, I'll want to support updates to the event in their calendar. This requires delivering a VEVENT with an identical UID but with an incremental SEQUENCE (via TutorialsBag):

Currently, I'm not tracking a sequential field for updates.

I'd also want to support cancellation files that delete the event from calendars. So, if a person cancels with Meeting Planner, we send an iCal file to attendees which removes the event from their calendar:

Over time, I'd like to cache .ics files for each event and participant for performance and storage issues. I'd like to provide some file management to reduce the eventual disk space required to store these, as they are only needed for a short amount of time and can be easily regenerated on demand.

I also want to ensure the directory in which these are stored is secured so that they can't be compromised, as they include a lot of personal and private information, such as email addresses and exactly where you can find specific people at a specific time.

In the future, I'd also like to try to integrate iCal's less regularly used advanced features to connect directly to Meeting Planner. For example, we'll be able to cancel or reschedule meetings from your iCal calendar program using Meeting Planner's programmatic interfaces, rather than having to return to the Meeting Planner website.

What's Next?

Watch for upcoming tutorials in our Building Your Startup With PHP series. In the next episode, I'll describe how to add support for registration via Google, Facebook and Twitter as well as connecting existing accounts to these social networks for the purpose of speeding adoption and simplifying usage.

Again, Meeting Planner is ready for you to begin using. Give it a try and schedule a meeting now!

Please feel free to add your questions and comments below; I try to participate in the discussions on a regular basis. You can also reach me on Twitter @reifman.

I'm also beginning to experiment with WeFunder based on the implementation of the SEC's new crowdfunding rules. Please consider following our profile. I may write about this more as part of this series.

Related Links

Tags:

Comments

Related Articles