Yohan Giarelli

Introducing CalendR

There is some boring and recurrent tasks in computer sciences. Date manipulations are. There is sometimes nice and interessant problematics, but usually, no.

That’s why I developped CalendR.

CalendR is a calendar management library based on PHP5.3+ date objects.

Ok. By what can it do ?

Well… In fact, very little things. But it’s enough to deal with usual needs.

For the big picture, CalendR allows you to create time periods, an to iterate on it. That periods are classics calendar periods (day, week, month, year).

So… Nothing that sounds like a revolution, but it gives you the ability to generate a calendar with this simple code :

<?php
$factory = new CalendR\Calendar;
$month = $factory->getMonth(2012, 06);

<table>
    <?php foreach ($month as $week): ?>
        <tr>
            <?php foreach ($week as $day): ?>
                <td<?php $month->contains($day) or print ' class="out-of-month' ?>>
                    <?php echo $day->getBegin()->format('d') ?>
                </td>
            <?php endforeach ?>
        </tr>
    <?php endforeach ?>
</table>

Could you find anything simplier ?

That’s nice, but what can i do with this calendar without events ?

Nothing. That’s why CalendR has a (simple) event management system.

Now that our calendar is generated and displayed, let’s add some events to it. One more time, it’s really simple.

$factory = new CalendR\Calendar;
$month = $factory->getMonth(2012, 06);
$events = $factory->getEvents($month);

<table>
    <?php foreach ($month as $week): ?>
        <tr>
            <?php foreach ($week as $day): ?>
                <td<?php $month->contains($day) or print ' class="out-of-month' ?>>
                    <?php echo $day->getBegin()->format('d') ?>
                    <?php if ($events->has($day)): ?>
                        <ul>
                            <?php foreach ($events->find($day) as $event): ?>
                                <li><?php echo $event->getName() ?></li>
                            <?php endforeach ?>
                        </ul>
                    <?php endif ?>
                </td>
            <?php endforeach ?>
        </tr>
    <?php endforeach ?>
</table>

How it works

All the event stuff is based on 2 Interfaces

• CalendR\Event\EventInterface
• CalendR\Event\Provider\ProviderInterface

Events

In fact, you have to implement EventInterface on your event class(es). The methods to implements are :

• getUid() : Returns an unique event identifier
• getBegin() : Returns the event begin \DateTime instance
• getEnd() : Returns the event end \DateTime instance
• contains(\DateTime $date) : Returns true if $date is during the event
• containsPeriod(PeriodInterface $period) : Returns if $period is during the event
• isDuring(PeriodInterface $period) : Returns if $period contains the event

But that’s a lot… So CalendR comes with a CalendR\Event\AbstractEvent class, that implement most of theeses methods.

Providers

Well, nice, we have defined our events. But how CalendR is supposed to retrieve them ? With a provider. The provider is a simple object providing events contained in a time period. It can be a Plain Old PHP Object, a Doctrine Repository, a Propel ActiveQuery or, why not, an object retrieving events over WebDAV.

This time, that’s easy. The ProviderInterface needs only one method to be implemented :

• getEvents(\DateTime $begin, \DateTime $end, array $options = array())

This method must returns the array of event instances that are between $begin and $end, and related to the $options options ($options can be anything).

Events returned by this method will be checked by CalendR and his EventManager, so you can make it simple. For a very small Provider working with a small set of events, you can return all your events. I will decrease performance for a big amount of events BTW.

Next, you juste have to declare your Provider by adding it to the EventManager :

    $factory = new CalendR\Calendar;
    $factory->getEventManager()->addProvider(new AwesomeEventProvider);

Ok, it can be usefuk someday. That’s all ?

No. For Symfony2 fanboys, “There is a Bundle for that”. CalendR is fully integrated to Symfony2 via (FrequenceWebCalendRBundle)[https://github.com/frequence-web/FrequenceWebCalendRBundle], wich allows you to declare your providers as service and add them to CalendR via a simple calendr.event_provider tag.

Some Twig functions are provided too, they’re useful for simple calendar rendering.

About the library installation, CalendR is available on Packagist, thanks to composer. Package name is ‘yohang/calendr’.

Final thought

CalendR is still in developement. There is some things that I don’t like, like the event retrieving. So, if you’re interested in this project, don’t wait anymore, just send me a Pull Request, it’ll make me happy :).

Repository : https://github.com/yohang/CalendR