Download the PHP package spatie/icalendar-generator without Composer

Generate calendars in the iCalendar format

Want to create online calendars so that you can display them on an iPhone's calendar app or in Google Calendar? This can be done by generating calendars in the iCalendar format (RFC 5545), a textual format that can be loaded by different applications.

The format of such calendars is defined in RFC 5545, which is not a pleasant reading experience. This package implements RFC 5545 and some extensions from RFC 7986 to provide you an easy to use API for creating calendars. It's not our intention to implement these RFC's entirely but to provide a straightforward API that's easy to use.

Here's an example of how to use it:

The above code will generate this string:

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

Upgrading

There were some substantial changes between v1 and v2 of the package. Check the upgrade guide for more information.

Usage

Here's how you can create a calendar:

You can give a name to the calendar:

A description can be added to a calendar:

In the end, you want to convert your calendar to text so that it can be streamed or downloaded to the user. Here's how you do that:

When streaming a calendar to an application, it is possible to set the calendar's refresh interval by duration in minutes. When setting this, the calendar application will check your server every time after the specified duration for changes to the calendar:

Event

An event can be created as follows. A name is not required, but a start date should always be given:

You can set the following properties on an event:

Want to create an event quickly with a start and end date?

You can add a location to an event a such:

You can set the organizer of an event, the email address is required, but the name can be omitted:

Attendees of an event can be added as such:

You can also set the participation status of an attendee:

There are five participation statuses:

• ParticipationStatus::accepted()
• ParticipationStatus::declined()
• ParticipationStatus::tentative()
• ParticipationStatus::needs_action()
• ParticipationStatus::delegated()

You can indicate that an attendee is required to RSVP to an event:

An event can be made transparent, so it does not overlap visually with other events in a calendar:

It is possible to create an event that spans a full day:

The status of an event can be set:

There are three event statuses:

• EventStatus::confirmed()
• EventStatus::cancelled()
• EventStatus::tentative()

An event can be classified(public, private, confidential) as such:

You can add a url attachment as such:

You can add an embedded attachment (base64) as such:

You can add an image as such:

There are four different image display types:

• Display::badge()
• Display::graphic()
• Display::fullsize()
• Display::thumbnail()

After creating your event, it should be added to a calendar. There are multiple options to do this:

Using Carbon

You can use the popular Carbon library:

Timezones

Events will use the change this.

Just a reminder: do not use PHP's setTimezone function on a DateTime object, it will change the time according to the timezone! It is better to create a new DateTime object with a timezone as such:

A point can be made for omitting timezones. For example, when you want to show an event at noon in the world. We define noon at 12 o'clock, but that time is relative. It is not the same for people in Belgium, Australia, or any other country in the world.

That's why you can disable timezones on events:

You can even disable timezones for a whole calendar:

Each calendar should have Timezone components describing the timezones used within your calendar. Although not all calendar clients require this, it is recommended to add these components.

Creating such Timezone components is quite complicated. That's why this package will automatically add them for you without configuration.

You can disable this behaviour as such:

You can manually add timezones to a calendar if desired as such:

More on these timezones later.

Alerts

Alerts allow calendar clients to send reminders about specific events. For example, Apple Mail on an iPhone will send users a notification about the event. An alert always belongs to an event has a description and a number of minutes before the event it will be triggered:

You can also trigger an alert after the event:

Or trigger an alert on a specific date:

Removing timezones on a calendar or event will also remove timezones on the alert.

Repeating events

It is possible for events to repeat, for example your monthly company dinner. This can be done as such:

And you can also repeat the event on a set of dates:

Recurrence rules

Recurrence rules or RRule's in short, make it possible to add a repeating event in your calendar by describing when it repeats within an RRule. First, we have to create an RRule:

This rule describes an event that will be repeated daily. You can also set the frequency to secondly, minutely, hourly, weekly, monthly or yearly.

The RRULE can be added to an event as such:

It is possible to finetune the RRule to your personal taste; let's have a look!

A RRule can start from a certain point in time:

And stop at a certain point:

It can only be repeated for a few times, 10 times for example:

The interval of the repetition can be changed:

When this event starts on Monday, for example, the next repetition of this event will not occur on Tuesday but Wednesday. You can do the same for all the frequencies.

It is also possible to repeat the event on a specific weekday:

Or on a specific weekday of a week in the month:

Or on the last weekday of a month:

You can repeat on a specific day in the month:

It is even possible to give an array of days in the month:

Repeating can be done for certain months (for example only in the second quarter):

Or just on one month only:

It is possible to set the day when the week starts:

You can provide a specific date on which an event won't be repeated:

It is also possible to give an array of dates on which the event won't be repeated:

Alternatively you can add RRules as a string:

If you add RRules as a string the timezones included in DTSTART and UNTIL are unknown to the package as the string is never parsed and evaluated. If they are known you can add DTSTART and UNTIL separately to help the package discover the timezones:

Use with Laravel

You can use Laravel Responses to stream to calendar applications:

If you want to add the possibility for users to download a calendar and import it into a calendar application:

Crafting Timezones

If you want to craft timezone components yourself, you're in the right place, although we advise you to read the section on timezones from the RFC first.

You can create a timezone as such:

It is possible to provide the last modified date:

Or add an url with more information about the timezone:

A timezone consists of multiple entries where the time of the timezone changed relative to UTC, such entry can be constructed for standard or daylight time:

Firstly you provide the type of entry (standard or daylight). Then a DateTime when the time changes. Lastly, an offset relative to UTC from before the change and an offset relative to UTC after the change.

It is also possible to give this entry a name and description:

An RRule for the entry can be given as such:

In the end you can add an entry to a timezone:

Or even add multiple entries:

Now we've constructed our timezone it is time(👀) to add this timezone to our calendar:

It is also possible to add multiple timezones:

Extending the package

We try to keep this package as straightforward as possible. That's why a lot of properties and subcomponents from the RFC are not included in this package. We've made it possible to add other properties or subcomponents to each component if you might need something not included in the package. But be careful! From this moment, you're on your own correctly implementing the RFC's.

Appending properties

You can add a new property to a component like this:

Here we've added a TextProperty, and this is a default key-value property type with a text as value. You can also use one of the default properties included in the package or create your own by extending the Property class.

Sometimes a property can have some additional parameters, these are key-value entries and can be added to properties as such:

Appending subcomponents

A subcomponent can be appended as such:

It is possible to create your subcomponents by extending the Component class.

Testing

Alternatives

We strive for a simple and easy to use API. Want something more? Then check out this package by Markus Poerschke.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you've found a bug regarding security please mail [email protected] instead of using the issue tracker.

Postcardware

You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Kruikstraat 22, box 12, 2018 Antwerp, Belgium.

We publish all received postcards on our company website.

Credits

• Ruben Van Assche
• All Contributors

License

The MIT License (MIT). Please see License File for more information.