[Pkg-owncloud-commits] [php-sabre-vobject] 02/19: Moved documentation to sabre.io website.
David Prévot
taffit at moszumanska.debian.org
Sun Jun 15 02:08:53 UTC 2014
This is an automated email from the git hooks/post-receive script.
taffit pushed a commit to branch master
in repository php-sabre-vobject.
commit 59f2c0e4890e90d9ddd2a546f279ea7e9ba79a7d
Author: Evert Pot <me at evertpot.com>
Date: Mon Jun 2 17:31:24 2014 -0400
Moved documentation to sabre.io website.
---
README.md | 8 +-
doc/MigratingFrom2to3.md | 277 --------------------
doc/usage_2.md | 378 ---------------------------
doc/usage_3.md | 658 -----------------------------------------------
4 files changed, 4 insertions(+), 1317 deletions(-)
diff --git a/README.md b/README.md
index 76e3fae..68725af 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,7 @@ After that, just declare the vobject dependency as follows:
```
"require" : {
- "sabre/vobject" : "~3.1"
+ "sabre/vobject" : "~3.2"
}
```
@@ -37,9 +37,9 @@ Then, run `composer.phar update` and you should be good.
Usage
-----
-* [3.x documentation](doc/usage_3.md)
-* [2.x documentation](doc/usage_2.md)
-* [Migrating from 2.x to 3.x](doc/MigratingFrom2to3.md)
+* [3.x documentation](http://sabre.io/vobject/usage/)
+* [2.x documentation](http://sabre.io/vobject/usage_2/)
+* [Migrating from 2.x to 3.x](http://sabre.io/vobject/upgrade/)
Made at fruux
-------------
diff --git a/doc/MigratingFrom2to3.md b/doc/MigratingFrom2to3.md
deleted file mode 100644
index 9d85f91..0000000
--- a/doc/MigratingFrom2to3.md
+++ /dev/null
@@ -1,277 +0,0 @@
-Migrating from vObject 2.x to 3.x
-=================================
-
-vObject 3.0 got a major overhaul, and much better built-in support for all
-kinds of properties and escaping.
-
-This version fixes the most important bugs, specifically Issue #19.
-
-To do this, a few backwards compatibility breaks had to be made. This document
-describes each of them, as well as all the new features.
-
-New features overview
----------------------
-
-* Serializer now properly deals with escaped commas and semi-colons.
-* Properties and Parameters now have a getParts() method to grab multiple
- values.
-* You can now simply set PHP DateTime objects on DATE-TIME properties.
-* Properties such as `CALSCALE`, `VERSION` and `PRODID` will automatically be
- added.
-* [RFC6868][1] is used to serialize parameters.
-* Methods to generate [jCard][2] and [jCal][3] objects.
-* Parsing of vCard 2.1 is much, much better, including support for the broken
- vCards Microsoft generates if the `FORGIVING` option is on.
-* The `add()` methods now return the objects that have been created.
-* A brand new parser that reads from streams, lowering memory usage.
-* Components now have an easy to use `remove()` method.
-* Every property, parameter and component has a reference to the document.
-* Binary properties are automatically decoded.
-
-And since sabre/vobject 3.1:
-
-* Added a jCard and jCal parser.
-* Using the `convert()` method you can convert between vCard 2.1, 3.0 and 4.0.
-* A new cli tool with `validate`, `repair`, `color` and `convert` commands.
-
-To find how out it all works, check out the [Documentation][4].
-
-Backwards compatibility breaks
-------------------------------
-
-### Creating components
-
-Before, it was possible to create components such as `VEVENT`, `VTODO`, etc
-with this syntax:
-
-```php
-<?php
-
-$event = \Sabre\VObject\Component::create('VEVENT');
-$event->summary = 'Birthday party!';
-
-// Or:
-
-$event = new \Sabre\VObject\Component('VEVENT');
-$event->summary = 'Birthday party!';
-
-?>
-```
-
-Neither of those are legal any longer. Components now _must_ be created through
-the Document object.
-
-Example:
-
-```php
-<?php
-
- $vcalendar = new \Sabre\VObject\Component\VCalendar();
- $event = $vcalendar->createComponent('VEVENT');
- $event->summary = 'Birthday party!';
-
-?>
-```
-
-Or:
-
-```php
-$vcalendar = new \Sabre\VObject\Component\VCalendar();
-$vcalendar->add('VEVENT', [
- 'summary' => 'Birthday party!',
-]);
-```
-
-### Creating properties
-
-Creating properties works the _exact_ same way.
-
-Old:
-
-```php
-<?php
-
-$location = new \Sabre\VObject\Property('LOCATION', 'Home');
-
-// Or:
-
-$location = \Sabre\VObject\Property::create('LOCATION', 'Home');
-
-?>
-```
-
-Now you must also use the document:
-
-Example:
-
-```php
-<?php
-
-$card = new \Sabre\VObject\Component\VCard();
-$location = $card->createProperty('LOCATION','Home');
-
-?>
-```
-
-Note that in most cases, this syntax is highly recommended instead:
-
-```php
-<?php
-
-$card = new \Sabre\VObject\Component\VCard();
-$location = $card->add('LOCATION','Home');
-
-?>
-```
-
-In this case it doesn't make much of a difference, but when constructing
-highly complex objects with sub-components, this _will_ make a big difference.
-
-### Component::children() and Property::parameters() return arrays.
-
-Before vObject 3 they returned an `ElementList`.
-
-### The signature for DateTime::setDateTime has changed.
-
-Before, you would use the following 4 syntaxes to set the date and time:
-
-```php
-<?php
-
-use Sabre\VObject\Property;
-
-$now = new DateTime('now');
-
-$dt = new Property\DateTime('DTSTART');
-$dt->setDateTime($now, Property\DateTime::DATE); // Date only
-$dt->setDateTime($now, Property\DateTime::LOCAL); // Floating time
-$dt->setDateTime($now, Property\DateTime::UTC); // Convert to UTC
-$dt->setDateTime($now, Property\DateTime::LOCALTZ); // Local to timezone information.
-
-```
-
-This has completely changed:
-
-```php
-<?php
-
-// Date only
-$now = new DateTime('now');
-$dt = $calendar->create('DTSTART');
-$dt->setValue($now);
-$dt['VALUE'] = 'date';
-
-// Floating time
-$dt = $calendar->create('DTSTART');
-$dt->setValue($now, $floating = true);
-
-// Convert to UTC
-$now->setTimeZone(\DateTimeZone('UTC'));
-$dt = $calendar->create('DTSTART');
-$dt->setValue($now);
-
-// Local time + timezone information
-$dt = $calendar->create('DTSTART');
-$dt->setValue($now);
-
-?>
-```
-
-Note that the preceeding examples are all a bit convoluted.
-In most cases you just want to do something like:
-
-```php
-<?php
-
-// Assuming this a vevent
-$event->DTSTART = $now;
-
-?>
-```
-
-In addition, the `MultiDateTime` property is no more, and it's methods are
-simply merged into `DateTime`.
-
-### The $value property is now protected everywhere.
-
-Both the `Property` and the `Parameter` classes had a public `$value` property,
-which allowed you to retrieve the string value for either of those.
-
-This is now protected, so you must access it in this manner:
-
-```php
-<?php
-// Assuming $prop is a property object.
-
-$prop->setValue('Birthday');
-echo $prop->getValue();
-
-?>
-```
-
-// For properties that have more than 1 value, you can use `setParts` and
-`getParts`:
-
-
-```php
-<?php
-
-$org->setParts(['Company', 'Department']);
-print_r($org->getParts());
-
-?>
-```
-
-### Binary properties are automatically de- and encoded.
-
-The `ATTACH`, `LOGO` and `PHOTO` properties now automatically de- and encode
-their binary values. In vObject 2 they were accessed by their raw base64
-values.
-
-### Components and documents get injected with default properties.
-
-When creating a new `VCalendar`, it will automatically get the `VERSION`,
-`CALSCALE` and `PRODID` properties.
-
-If you were adding your own with this syntax:
-
-```php
-<?php
-
-$calendar = new Sabre\VObject\Component\VCalendar();
-$calendar->VERSION = '2.0';
-
-?>
-```
-
-Then nothing will go wrong, and the properties will simply be overwritten.
-However, if you used `add()` before in this manner:
-
-```php
-<?php
-
-$calendar = new Sabre\VObject\Component\VCalendar();
-$calendar->add('version', '2.0');
-
-?>
-```
-
-You will end up with 2 VERSION properties, making the document invalid.
-
-### componentMap and propertyMap properties have moved.
-
-When you wanted to automatically map certain components or properties to
-certain PHP classes, you could do so with `Component::$componentMap` and
-`Property::$propertyMap`.
-
-These properties have now moved to the document classes:
-
-* `Component\VCalendar::$propertyMap`
-* `Component\VCalendar::$componentMap`
-* `Component\VCard::$propertyMap`
-* `Component\VCard::$componentMap`
-
-[1]: http://tools.ietf.org/html/rfc6868
-[2]: http://tools.ietf.org/html/rfc7095
-[3]: http://tools.ietf.org/html/draft-ietf-jcardcal-jcal-08
-[4]: usage_3.md
diff --git a/doc/usage_2.md b/doc/usage_2.md
deleted file mode 100644
index 3cb4a3d..0000000
--- a/doc/usage_2.md
+++ /dev/null
@@ -1,378 +0,0 @@
-VObject 2.x documentation
-=========================
-
-The VObject library allows you to easily parse and manipulate [iCalendar](https://tools.ietf.org/html/rfc5545)
-and [vCard](https://tools.ietf.org/html/rfc6350) objects using PHP.
-The goal of the VObject library is to create a very complete library, with an easy to use API.
-
-This project is a spin-off from [SabreDAV](http://sabre.io/), where it has
-been used for several years. The VObject library has 100% unittest coverage.
-
-Installation
-------------
-
-VObject requires PHP 5.3, and should be installed using composer.
-The general composer instructions can be found on the [composer website](http://getcomposer.org/doc/00-intro.md composer website).
-
-After that, just declare the vobject dependency as follows:
-
-```
-"require" : {
- "sabre/vobject" : "2.1.*"
-}
-```
-
-Then, run `composer.phar update` and you should be good.
-
-Usage
------
-
-### Parsing
-
-For our example, we will be using the following vcard:
-
-```
-BEGIN:VCARD
-VERSION:3.0
-PRODID:-//Sabre//Sabre VObject 2.0//EN
-N:Planck;Max;;;
-FN:Max Planck
-EMAIL;TYPE=WORK:mplanck at example.org
-item1.TEL;TYPE=CELL:(+49)3144435678
-item1.X-ABLabel:Private cell
-item2.TEL;TYPE=WORK:(+49)5554564744
-item2.X-ABLabel:Work
-END:VCARD
-```
-
-
-If we want to just print out Max' full name, you can just use property access:
-
-
-```php
-use Sabre\VObject;
-
-$card = VObject\Reader::read($data);
-echo $card->FN;
-```
-
-### Changing properties
-
-Creating properties is pretty similar. If we like to add his birthday, we just
-set the property:
-
-```php
-$card->BDAY = '1858-04-23';
-```
-
-Note that in the previous example, we're actually updating any existing BDAY that
-may already exist. If we want to add a new property, without overwriting the previous
-we can do this with the `add` method.
-
-```php
-$card->add('EMAIL','max at example.org');
-```
-
-### Parameters
-
-If we want to also specify that this is max' home email addresses, we can do this with
-a third parameter:
-
-```
-$card->add('EMAIL', 'max at example'org', array('type' => 'HOME'));
-```
-
-If we want to read out all the email addresses and their type, this would look something
-like this:
-
-```
-foreach($card->EMAIL as $email) {
-
- echo $email['TYPE'], ' - ', $email;
-
-}
-```
-
-### Groups
-
-In our example, you can see that the TEL properties are prefixed. These are 'groups' and
-allow you to group multiple related properties together. The group can be any user-defined
-name.
-
-This particular example as generated by the OS X addressbook, which uses the `X-ABLabel`
-to allow the user to specify custom labels for properties. OS X addressbook uses groups
-to tie the label to the property.
-
-The VObject library simply ignores the group if you don't specify it, so this will work:
-
-```php
-foreach($card->TEL as $tel) {
- echo $tel, "\n";
-}
-```
-
-But if you would like to target a specific group + property, this is possible too:
-
-```php
-echo $card->{'ITEM1.TEL'};
-```
-
-So if you would like to show all the phone numbers, along with their custom label, the
-following syntax is used:
-
-```php
-foreach($card->TEL as $tel) {
-
- echo $card->{$tel->group . '.X-ABLABEL'}, ": ";
- echo $tel, "\n";
-
-}
-```
-
-### Serializing / Saving
-
-If you want to generate your updated VObject, you can simply call the serialize() method.
-
-```php
-echo $card->serialize();
-```
-
-### Components
-
-iCalendar, unlike vCards always have sub-components. Where vCards are often just a flat
-list, iCalendar objects tend to have a tree-like structure. For the following paragraphs,
-we will use the following object as the example:
-
-```
-BEGIN:VCALENDAR
-VERSION:2.0
-PRODID:-//Sabre//Sabre VObject 2.0//EN
-BEGIN:VEVENT
-SUMMARY:Curiosity landing
-DTSTART:20120806T051439Z
-LOCATION:Mars
-END:VEVENT
-END:VCALENDAR
-```
-
-Since events, tasks and journals are always in a sub component, this is also how we
-access them.
-
-```php
-use Sabre\VObject;
-
-$calendar = VObject\Reader::read($data);
-echo $calendar->VEVENT->SUMMARY;
-```
-
-Adding components to a calendar is done with a factory method:
-
-```php
-$event = VObject\Component::create('VEVENT');
-$calendar->add($event);
-
-$event->SUMMARY = 'Curiosity launch';
-$event->DTSTART = '20111126T150202Z';
-$event->LOCATION = 'Cape Carnival';
-```
-
-By the way.. cloning also works as expected, as the entire structure is cloned along with it:
-
-```php
-$clonedEvent = clone $calendar->VEVENT[0];
-$calendar->add($clonedEvent);
-```
-
-### Date and time handling
-
-If you ever had to deal with iCalendar timezones, you know it can be complicated.
-The way timezones are specified is flawed, which is something I may write an essay about some
-day. VObject does its best to determine the correct timezone. Many standard formats
-have been tested and verified, and special code has been implemented for special-casing
-microsoft generated timezone information, and others.
-
-To get a real php `DateTime` object, you can request this as follows:
-
-```php
-$event = $calendar->VEVENT;
-$start = $event->DTSTART->getDateTime();
-echo $start->format(\DateTime::W3C);
-```
-
-To set the property with a DateTime object, you can use the following syntax:
-
-```php
-$dateTime = new \DateTime('2012-08-07 23:53:00', new DateTimeZone('Europe/Amsterdam'));
-$event->DTSTART->setDateTime($dateTime, VObject\Property\DateTime::DATE);
-```
-
-The second argument specifies the type of date you're setting. The following three
-options exist:
-
-1. `LOCAL` This is a floating time, with no timezone information. This basically specifies that the event happens in whatever the timezone's currently in. This would be encoded as `DTSTART;VALUE=DATE-TIME:20120807235300`
-2. `UTC` This specifies that the time should be encoded as a UTC time. This is encoded as `DTSTART;VALUE=DATE-TIME:20120807205300Z`. Note the extra Z and the fact that it's two hours 'earlier'.
-3. `LOCALTZ` specifies that it's supposed to be encoded in its local timezone. For example `DTSTART;VALUE=DATE-TIME;TZID=Europe/Amsterdam:20120807235300`.
-4. `DATE` This is a date-only, and does not contain the time. In this case this would be encoded as `DTSTART;VALUE=DATE:20120807`.
-
-A few important notes:
-
-* When a `TZID` is specified, there should also be a matching `VTIMEZONE` object with all the timezone information. VObject cannot currently automatically embed this. However, in reality other clients seem to do fine without this information. Yet, for completeness, this will be added in the future.
-* As mentioned, the timezone-determination process may sometimes fail. Report any issues you find, and I'll be quick to add workarounds!
-
-### Recurrence rules
-
-Recurrence rules allow events to recur, for example for a weekly meeting, or an anniversary.
-This is done with the `RRULE` property. The `RRULE` property allows for a LOT of different
-rules. VObject only implements the ones that actually appear in calendar software.
-
-To read more about `RRULE` and all the options, check out [RFC5545](https://tools.ietf.org/html/rfc5545#section-3.8.5).
-VObject supports the following options:
-
-1. `UNTIL` for an end date.
-2. `INTERVAL` for for example "every 2 days".
-3. `COUNT` to stop recurring after x items.
-4. `FREQ=DAILY` to recur every day, and `BYDAY` to limit it to certain days.
-5. `FREQ=WEEKLY` to recur every week, `BYDAY` to expand this to multiple weekdays in every week and `WKST` to specify on which day the week starts.
-6. `FREQ=MONTHLY` to recur every month, `BYMONTHDAY` to expand this to certain days in a month, `BYDAY` to expand it to certain weekdays occuring in a month, and `BYSETPOS` to limit the last two expansions.
-7. `FREQ=YEARLY` to recur every year, `BYMONTH` to expand that to certain months in a year, and `BYDAY` and `BYWEEKDAY` to expand the `BYMONTH` rule even further.
-
-VObject supports the `EXDATE` property for exclusions, but not yet the `RDATE` and `EXRULE`
-properties. If you're interested in this, please file a github issue, as this will put it
-on my radar.
-
-This is a bit of a complex subject to go in excruciating detail. The
-[RFC](https://tools.ietf.org/html/rfc5545#section-3.8.5) has a lot of examples though.
-
-The hard part is not to write the RRULE, it is to expand them. The most complex and
-hard-to-read code is hidden in this component. Dragons be here.
-
-So, if we have a meeting every 2nd monday of the month, this would be specified as such:
-
-```
-BEGIN:VCALENDAR
-VERSION:2.0
-PRODID:-//Sabre//Sabre VObject 2.0//EN
-BEGIN:VEVENT
-UID:1102c450-e0d7-11e1-9b23-0800200c9a66
-DTSTART:20120109T140000Z
-RRULE:FREQ=MONTHLY;BYDAY=MO;BYSETPOS=2
-END:VEVENT
-END:VCALENDAR
-```
-
-Note that normally it's not allowed to indent the object like this, but it does make
-it easier to read. This is also the first time I added in a UID, which is required
-for all VEVENT, VTODO and VJOURNAL objects!
-
-To figure out all the meetings for this year, we can use the following syntax:
-
-```php
-use Sabre\VObject;
-
-$calendar = VObject\Reader::read($data);
-$calendar->expand(new DateTime('2012-01-01'), new DateTime('2012-12-31'));
-```
-
-What the expand method does, is look at its inner events, and expand the recurring
-rule. Our calendar now contains 12 events. The first will have its RRULE stripped,
-and every subsequent VEVENT has the correct meeting date and a `RECURRENCE-ID` set.
-
-This results in something like this:
-
-```
-BEGIN:VCALENDAR
- VERSION:2.0
- PRODID:-//Sabre//Sabre VObject 2.0//EN
- BEGIN:VEVENT
- UID:1102c450-e0d7-11e1-9b23-0800200c9a66
- DTSTART:20120109T140000Z
- END:VEVENT
- BEGIN:VEVENT
- UID:1102c450-e0d7-11e1-9b23-0800200c9a66
- RECURRENCE-ID:20120213T140000Z
- DTSTART:20120213T140000Z
- END:VEVENT
- BEGIN:VEVENT
- UID:1102c450-e0d7-11e1-9b23-0800200c9a66
- RECURRENCE-ID:20120312T140000Z
- DTSTART:20120312T140000Z
- END:VEVENT
- ..etc..
-END:VCALENDAR
-```
-
-To show the list of dates, we would do this as such:
-
-```php
-foreach($calendar->VEVENT as $event) {
- echo $event->DTSTART->getDateTime()->format(\DateTime::ATOM);
-}
-```
-
-In a recurring event, single instances can also be overriden. VObject also takes these
-into consideration. The reason we needed to specify a start and end-date, is because
-some recurrence rules can be 'never ending'.
-
-You should make sure you pick a sane date-range. Because if you pick a 50 year
-time-range, for a daily recurring event; this would result in over 18K objects.
-
-Free-busy report generation
----------------------------
-
-Some calendaring software can make use of FREEBUSY reports to show when people are
-available.
-
-You can automatically generate these reports from calendars using the `FreeBusyGenerator`.
-
-Example based on our last event:
-
-```php
-// We're giving it the calendar object. It's also possible to specify multiple objects,
-// by setting them as an array.
-//
-// We must also specify a start and end date, because recurring events are expanded.
-$fbGenerator = new VObject\FreeBusyGenerator(
- new DateTime('2012-01-01'),
- new DateTime('2012-12-31'),
- $calendar
-);
-
-// Grabbing the report
-$freebusy = $fbGenerator->result();
-
-// The freebusy report is another VCALENDAR object, so we can serialize it as usual:
-echo $freebusy->serialize();
-```
-
-The output of this script will look like this:
-
-```
-BEGIN:VCALENDAR
-VERSION:2.0
-PRODID:-//Sabre//Sabre VObject 2.0//EN
-CALSCALE:GREGORIAN
-BEGIN:VFREEBUSY
-DTSTART;VALUE=DATE-TIME:20111231T230000Z
-DTEND;VALUE=DATE-TIME:20111231T230000Z
-DTSTAMP;VALUE=DATE-TIME:20120808T131628Z
-FREEBUSY;FBTYPE=BUSY:20120109T140000Z/20120109T140000Z
-FREEBUSY;FBTYPE=BUSY:20120213T140000Z/20120213T140000Z
-FREEBUSY;FBTYPE=BUSY:20120312T140000Z/20120312T140000Z
-FREEBUSY;FBTYPE=BUSY:20120409T140000Z/20120409T140000Z
-FREEBUSY;FBTYPE=BUSY:20120514T140000Z/20120514T140000Z
-FREEBUSY;FBTYPE=BUSY:20120611T140000Z/20120611T140000Z
-FREEBUSY;FBTYPE=BUSY:20120709T140000Z/20120709T140000Z
-FREEBUSY;FBTYPE=BUSY:20120813T140000Z/20120813T140000Z
-FREEBUSY;FBTYPE=BUSY:20120910T140000Z/20120910T140000Z
-FREEBUSY;FBTYPE=BUSY:20121008T140000Z/20121008T140000Z
-FREEBUSY;FBTYPE=BUSY:20121112T140000Z/20121112T140000Z
-FREEBUSY;FBTYPE=BUSY:20121210T140000Z/20121210T140000Z
-END:VFREEBUSY
-END:VCALENDAR
-```
-
-Support
--------
-
-Head over to the [SabreDAV mailing list](http://groups.google.com/group/sabredav-discuss) for any questions.
-
diff --git a/doc/usage_3.md b/doc/usage_3.md
deleted file mode 100644
index 37c365b..0000000
--- a/doc/usage_3.md
+++ /dev/null
@@ -1,658 +0,0 @@
-VObject 3 documentation
-=======================
-
-The VObject library allows you to easily parse and manipulate [iCalendar](https://tools.ietf.org/html/rfc5545)
-and [vCard](https://tools.ietf.org/html/rfc6350) objects using PHP.
-The goal of the VObject library is to create a very complete library, with an easy to use API.
-
-This project is a spin-off from [SabreDAV](http://sabre.io/), where it has
-been used for several years. The VObject library has 100% unittest coverage.
-
-VObject 3 is the new and improved version of the library.
-
-Notable new stuff:
-
-* New and improved parser.
-* Better support for vCard 2.1.
-* Support for RFC6868.
-* Serializing to jCard/jCal.
-* Lots of tiny API improvements that combined make everything much easier.
-
-Installation
-------------
-
-VObject requires PHP 5.3, and should be installed using composer.
-The general composer instructions can be found on the [composer website](http://getcomposer.org/doc/00-intro.md composer website).
-
-After that, just declare the VObject dependency as follows:
-
-```
-"require" : {
- "sabre/vobject" : "3.0.*"
-}
-```
-
-Then, run `composer.phar update` and you should be good.
-
-Usage
------
-
-A few notes about the examples:
-
-1. The assumption for every example, is that the VObject source has been
- included.
-2. It's also assumed that `use Sabre\VObject` has been called to import the
- VObject namespace.
-3. While sabre/vobject supports PHP 5.3, most of the examples in this document
- use syntax that has been introduced in PHP 5.4. PHP 5.4 introduces a new way
- to create arrays, which is a lot shorter and looks better. If you are
- running PHP 5.3, you may need to replace `[` and `]` with `array(` and `)`.
-
-### Creating vCards.
-
-To create a vCard, you can simply instantiate the vCard component, and pass
-the properties you need:
-
-```php
-<?php
-
-$vcard = new VObject\Component\VCard([
- 'FN' => 'Cowboy Henk',
- 'TEL' => '+1 555 34567 455',
- 'N' => ['Henk', 'Cowboy', '', 'Dr.', 'MD'],
-]);
-
-echo $vcard->serialize();
-```
-
-
-This will output:
-
-```
-BEGIN:VCARD
-VERSION:3.0
-PRODID:-//Sabre//Sabre VObject 3.0.0-alpha5//EN
-FN:Cowboy Henk
-TEL:+1 555 34567 455
-N:Henk;Cowboy;;Dr.;MD
-END:VCARD
-```
-
-
-### Adding properties
-
-Certain properties, such as `TEL`, `ADR` or `EMAIL` may appear more than once.
-To add any additional properties, use the `add()` method on the vCard.
-
-```php
-<?php
-
-$vcard->add('TEL', '+1 555 34567 456', ['type' => 'fax']);
-```
-
-The third argument of the add() method allows you to specify a list of
-parameters.
-
-### Manipulating properties
-
-The vCard also allows object-access to manipulate properties:
-
-```php
-<?php
-
-// Overwrites or sets a property:
-$vcard->FN = 'Doctor McNinja';
-
-// Removes a property
-unset($vcard->FN);
-
-// Checks for existence of a property:
-
-isset($vcard->FN);
-```
-
-### Working with parameters
-
-To get access to a parameter, you can simply use array-access:
-
-```php
-$type = $vcard->TEL['TYPE']:
-echo (string)$type;
-```
-
-Parameters can also appear multiple times. To get to their values, just loop
-through them:
-
-```php
-if ($param = $vcard->TEL['TYPE']) {
- foreach($param as $value) {
- echo $value, "\n";
- }
-}
-```
-
-To change parameters for properties, you can use array-access syntax:
-
-```php
-<?php
-
-$vcard->TEL['TYPE'] = ['WORK','FAX']:
-```
-
-Or when you're working with singular parameters:
-
-```php
-$vcard->TEL['PREF'] = 1;
-```
-
-It is also possible add a list of parameters while creating the property.
-
-```php
-$vcard->add(
- 'EMAIL',
- 'foo at example.org',
- [
- 'type' => ['home', 'work'],
- 'pref' => 1,
- ]
-);
-```
-
-### Parsing vCard or iCalendar
-
-To parse a vCard or iCalendar object, simply call:
-
-```php
-<?php
-
-// $data must be either a string, or a stream.
-$vcard = VObject\Reader::read($data);
-```
-
-When you're working with vCards generated by broken software (such as the
-latest Microsoft Outlook), you can pass a 'forgiving' option that will do an
-attempt to mend the broken data.
-
-```php
-<?php
-
-$vcard = VObject\Reader::read($data, VObject\Reader::OPTION_FORGIVING);
-```
-
-### Reading property values
-
-For properties that are stored as a string, you can simply call:
-
-```php
-<?php
-
-echo (string)$vcard->FN;
-```
-
-For properties that contain more than 1 part, such as `ADR`, `N` or `ORG` you
-can call `getParts()`.
-
-```php
-<?php
-
-print_r(
- $vcard->ORG->getParts();
-);
-```
-
-### Looping through properties.
-
-Properties such as `ADR`, `EMAIL` and `TEL` may appear more than once in a
-vCard. To loop through them, you can simply throw them in a `foreach()`
-statement:
-
-```php
-<?php
-
-foreach($vcard->TEL as $tel) {
- echo "Phone number: ", (string)$tel, "\n";
-}
-
-foreach($vcard->ADR as $adr) {
- print_r($adr->getParts());
-}
-```
-
-### vCard property grouping
-
-It's allowed in vCards to group multiple properties together with an arbitrary
-string.
-
-Apple clients use this feature to assign custom labels to things like phone
-numbers and email addresses. Below is an example:
-
-```
-BEGIN:VCARD
-VERSION:3.0
-groupname.TEL:+1 555 12342567
-groupname.X-ABLABEL:UK number
-END:VCARD
-```
-
-
-In our example, you can see that the TEL properties are prefixed. These are 'groups' and
-allow you to group multiple related properties together.
-
-In most situations these group names are ignored, so when you execute the following
-example, the `TEL` properties are still traversed.
-
-```php
-<?php
-
-foreach($vcard->TEL as $tel) {
- echo (string)$tel, "\n";
-}
-```
-
-But if you would like to target a specific group + property, this is possible too:
-
-```php
-<?php
-
-echo (string)$vcard->{'groupname.TEL'};
-```
-
-To expand that example a little bit; if you'd like to traverse through all phone
-numbers and display their custom labels, you'd do something like this:
-
-
-```php
-<?php
-
-foreach($vcard->TEL as $tel) {
-
- echo (string)$vcard->{$tel->group . '.X-ABLABEL'}, ": ";
- echo (string)$tel, "\n";
-
-}
-```
-
-### iCalendar
-
-iCalendar works much the same way as vCards, but has a couple of features
-that vCard does not.
-
-First, in vCard there's only 1 component (everything between `BEGIN:VCARD`
-and `END:VCARD`), but in iCalendar, there are nested components.
-
-A simple illustration, lets create an iCalendar that contains an event.
-
-```php
-<?php
-
-$vcalendar = new VObject\Component\VCalendar();
-
-$vcalendar->add('VEVENT', [
- 'SUMMARY' => 'Birthday party',
- 'DTSTART' => new \DateTime('2013-04-07'),
- 'RRULE' => 'FREQ=YEARLY',
-]);
-
-echo $vcalendar->serialize();
-```
-
-This will output the following:
-
-```
-BEGIN:VCALENDAR
-VERSION:2.0
-PRODID:-//Sabre//Sabre VObject 3.0.0-alpha5//EN
-CALSCALE:GREGORIAN
-BEGIN:VEVENT
-SUMMARY:Birthday party
-DTSTART;TZID=Europe/London;VALUE=DATE-TIME:20130407T000000
-RRULE:FREQ=YEARLY
-END:VEVENT
-END:VCALENDAR
-```
-
-
-The add() method will always return the instance of the property or
-sub-component it's creating. This makes for easy further manipulation.
-
-Here's another example that adds an attendee and an organizer:
-
-```php
-<?php
-
-$vcalendar = new VObject\Component\VCalendar();
-
-$vevent = $vcalendar->add('VEVENT', [
- 'SUMMARY' => 'Meeting',
- 'DTSTART' => new \DateTime('2013-04-07'),
-]);
-
-$vevent->add('ORGANIZER','mailto:organizer at example.org');
-$vevent->add('ATTENDEE','mailto:attendee1 at example.org');
-$vevent->add('ATTENDEE','mailto:attendee2 at example.org');
-```
-
-### Date and time handling
-
-Parsing Dates and Times from iCalendar and vCard can be difficult.
-Most of this is abstracted by the VObject library.
-
-Given an event, in a calendar, you can get a real PHP `DateTime` object using
-the following syntax:
-
-```php
-<?php
-
-$start = $vcalendar->VEVENT->DTSTART->getDateTime();
-echo $start->format(\DateTime::W3C);
-```
-
-To update the property with a new `DateTime` object, just use the following syntax:
-
-```php
-<?php
-
-$dateTime = new \DateTime('2012-08-07 23:53:00', new \DateTimeZone('Europe/Amsterdam'));
-$event->DTSTART = $dateTime;
-```
-
-### Expanding recurrence rules
-
-Recurrence rules allow events to recur, for example for a weekly meeting, or an anniversary.
-This is done with the `RRULE` property. The `RRULE` property allows for a LOT of different
-rules. VObject only implements the ones that actually appear in calendar software.
-
-To read more about `RRULE` and all the options, check out [RFC5545](https://tools.ietf.org/html/rfc5545#section-3.8.5).
-VObject supports the following options:
-
-1. `UNTIL` for an end date.
-2. `INTERVAL` for for example "every 2 days".
-3. `COUNT` to stop recurring after x items.
-4. `FREQ=DAILY` to recur every day, and `BYDAY` to limit it to certain days.
-5. `FREQ=WEEKLY` to recur every week, `BYDAY` to expand this to multiple weekdays in every week and `WKST` to specify on which day the week starts.
-6. `FREQ=MONTHLY` to recur every month, `BYMONTHDAY` to expand this to certain days in a month, `BYDAY` to expand it to certain weekdays occuring in a month, and `BYSETPOS` to limit the last two expansions.
-7. `FREQ=YEARLY` to recur every year, `BYMONTH` to expand that to certain months in a year, and `BYDAY` and `BYWEEKDAY` to expand the `BYMONTH` rule even further.
-
-VObject supports the `EXDATE` property for exclusions, but not yet the `RDATE` and `EXRULE`
-properties. If you're interested in this, please file a github issue, as this will put it
-on my radar.
-
-This is a bit of a complex subject to go in excruciating detail. The
-[RFC](https://tools.ietf.org/html/rfc5545#section-3.8.5) has a lot of examples though.
-
-The hard part is not to write the RRULE, it is to expand them. The most complex and
-hard-to-read code is hidden in this component. Dragons be here.
-
-So, if we have a meeting every 2nd monday of the month, this would be specified as such:
-
-```
-BEGIN:VCALENDAR
-VERSION:2.0
-PRODID:-//Sabre//Sabre VObject 2.0//EN
-BEGIN:VEVENT
-UID:1102c450-e0d7-11e1-9b23-0800200c9a66
-DTSTART:20120109T140000Z
-RRULE:FREQ=MONTHLY;BYDAY=MO;BYSETPOS=2
-END:VEVENT
-END:VCALENDAR
-```
-
-Note that I added in `UID` property. For simplicity I've kept it out of
-previous examples, but do note that a `UID` property is required for all
-`VEVENT`, `VTODO` and `VJOURNAL` objects!
-
-To figure out all the meetings for this year, we can use the following syntax:
-
-```php
-<?php
-
-$vcalendar = VObject\Reader::read($data);
-$vcalendar->expand(new DateTime('2012-01-01'), new DateTime('2012-12-31'));
-```
-
-What the expand method does, is look at its inner events, and expand the recurring
-rule. Our calendar now contains 12 events. The first will have its RRULE stripped,
-and every subsequent VEVENT has the correct meeting date and a `RECURRENCE-ID` set.
-
-This results in something like this:
-
-```
-BEGIN:VCALENDAR
- VERSION:2.0
- PRODID:-//Sabre//Sabre VObject 2.0//EN
- BEGIN:VEVENT
- UID:1102c450-e0d7-11e1-9b23-0800200c9a66
- DTSTART:20120109T140000Z
- END:VEVENT
- BEGIN:VEVENT
- UID:1102c450-e0d7-11e1-9b23-0800200c9a66
- RECURRENCE-ID:20120213T140000Z
- DTSTART:20120213T140000Z
- END:VEVENT
- BEGIN:VEVENT
- UID:1102c450-e0d7-11e1-9b23-0800200c9a66
- RECURRENCE-ID:20120312T140000Z
- DTSTART:20120312T140000Z
- END:VEVENT
- ..etc..
-END:VCALENDAR
-```
-
-Note that I added some extra spaces for convenience..
-
-To show the list of dates, we would do this as such:
-
-```php
-<?php
-
-foreach($vcalendar->VEVENT as $vevent) {
- echo $vevent->DTSTART->getDateTime()->format(\DateTime::ATOM);
-}
-```
-
-In a recurring event, single instances can also be overriden. VObject also takes these
-into consideration. The reason we needed to specify a start and end-date, is because
-some recurrence rules can be 'never ending'.
-
-You should make sure you pick a sane date-range. Because if you pick a 50 year
-time-range, for a daily recurring event; this would result in over 18K objects.
-
-### Free-busy report generation
-
-Some calendaring software can make use of FREEBUSY reports to show when people are
-available.
-
-You can automatically generate these reports from calendars using the `FreeBusyGenerator`.
-
-Example based on our last event:
-
-```php
-<?php
-
-// We're giving it the calendar object. It's also possible to specify multiple objects,
-// by setting them as an array.
-//
-// We must also specify a start and end date, because recurring events are expanded.
-$fbGenerator = new VObject\FreeBusyGenerator(
- new DateTime('2012-01-01'),
- new DateTime('2012-12-31'),
- $vcalendar
-);
-
-// Grabbing the report
-$freebusy = $fbGenerator->getResult();
-
-// The freebusy report is another VCALENDAR object, so we can serialize it as usual:
-echo $freebusy->serialize();
-```
-
-The output of this script will look like this:
-
-```
-BEGIN:VCALENDAR
-VERSION:2.0
-PRODID:-//Sabre//Sabre VObject 2.0//EN
-CALSCALE:GREGORIAN
-BEGIN:VFREEBUSY
-DTSTART;VALUE=DATE-TIME:20111231T230000Z
-DTEND;VALUE=DATE-TIME:20111231T230000Z
-DTSTAMP;VALUE=DATE-TIME:20120808T131628Z
-FREEBUSY;FBTYPE=BUSY:20120109T140000Z/20120109T140000Z
-FREEBUSY;FBTYPE=BUSY:20120213T140000Z/20120213T140000Z
-FREEBUSY;FBTYPE=BUSY:20120312T140000Z/20120312T140000Z
-FREEBUSY;FBTYPE=BUSY:20120409T140000Z/20120409T140000Z
-FREEBUSY;FBTYPE=BUSY:20120514T140000Z/20120514T140000Z
-FREEBUSY;FBTYPE=BUSY:20120611T140000Z/20120611T140000Z
-FREEBUSY;FBTYPE=BUSY:20120709T140000Z/20120709T140000Z
-FREEBUSY;FBTYPE=BUSY:20120813T140000Z/20120813T140000Z
-FREEBUSY;FBTYPE=BUSY:20120910T140000Z/20120910T140000Z
-FREEBUSY;FBTYPE=BUSY:20121008T140000Z/20121008T140000Z
-FREEBUSY;FBTYPE=BUSY:20121112T140000Z/20121112T140000Z
-FREEBUSY;FBTYPE=BUSY:20121210T140000Z/20121210T140000Z
-END:VFREEBUSY
-END:VCALENDAR
-```
-
-### Converting to jCard
-
-To create a json-version of your iCalendar or vCard, simply call
-`jsonSerialize` on your component:
-
-```php
-<?php
-
-echo json_encode($vcard->jsonSerialize());
-```
-
-The json formats are based on these RFCs:
-
-* http://tools.ietf.org/html/rfc7095
-* http://tools.ietf.org/html/draft-ietf-jcardcal-jcal-08
-
-Because these are still in draft, so is the jsonSerialize implementation. The
-output format may therefore break between versions to comply with the latest
-version of the spec.
-
-### Parsing jCard and jCal.
-
-To parse a jCard or jCal object, use the following snippet:
-
-```php
-<?php
-
-$input = 'jcard.json';
-$jCard = VObject\Reader::readJson(fopen('jcard.json', 'r'));
-
-?>
-```
-
-You can pass either a json string, a readable stream, or an array if you
-already called json_decode on the input.
-
-This feature was added in sabre/vobject 3.1.
-
-### Splitting export files
-
-Generally when software makes backups of calendars or contacts, they will
-put all the objects in a single file. In the case of vCards, this is often
-a stream of VCARD objects, in the case of iCalendar, this tends to be a
-single VCALENDAR objects, with many components.
-
-Protocols such as Card- and CalDAV expect only 1 object per resource. The
-vobject library provides 2 classes to split these backup files up into many.
-
-To do this, use the splitter objects:
-
-```php
-<?php
-
-// You can either pass a readable stream, or a string.
-$h = fopen('backupfile.vcf', 'r');
-$splitter = new VObject\Splitter\VCard($h);
-
-while($vcard = $splitter->next()) {
-
- // $vCard is a single vCard object. You can just call serialize() on it
- // if you were looking for the string version.
-
-}
-```
-
-Next to the VCard splitter, there's also an ICalendar splitter. The latter
-creates a `VCALENDAR` object per `VEVENT`, `VTODO` or `VJOURNAL`, and ensures
-that the `VTIMEZONE` information is kept intact, and any `VEVENT` objects that
-belong together (because they are expections for an `RRULE` and thus have the
-same `UID`) will be kept together, exactly like CalDAV expects.
-
-### Converting between different vCard versions.
-
-Since sabre/vobject 3.1, there's also a feature to convert between various
-vCard versions. Currently it's possible to convert from vCard 2.1, 3.0 and
-4.0 and to 3.0 and 4.0. It's not yet possible to convert to vCard 2.1.
-
-To do this, simply call the convert() method on the vCard object.
-
-```php
-<?php
-
-$input = <<<VCARD
-BEGIN:VCARD
-VERSION:2.1
-FN;CHARSET=UTF-8:Foo
-TEL;PREF;HOME:+1 555 555 555
-END:VCARD
-VCARD;
-
-$vCard = VObject\Reader::read($input);
-$vCard->convert(VObject\Document::VCARD40);
-
-echo $vcard->serialize();
-
-// This will output:
-/*
-BEGIN:VCARD
-VERSION:4.0
-FN:Foo
-TEL;PREF=1;TYPE=HOME:+1 555 555 555
-END:VCARD
-*/
-?>
-```
-
-Note that not everything can cleanly convert between versions, and it's
-probable that there's a few properties that could be converted between
-versions, but isn't yet. If you find something, open a feature request ticket
-on Github.
-
-Full API documentation
-----------------------
-
-Full API documentation can be found on github:
-
-https://github.com/fruux/sabre-vobject/wiki/ApiIndex
-
-Reading the source may also be helpful instead :)
-
-CLI tool
---------
-
-Since vObject 3.1, a new cli tool is shipped in the bin/ directory.
-
-This tool has the following features:
-
-* A `validate` command.
-* A `repair` command to repair objects that are slightly broken.
-* A `color` command, to show an iCalendar object or vCard on the console with
- ansi-colors, which may help debugging.
-* A `convert` command, allowing you to convert between iCalendar 2.0, vCard 2.1,
- vCard 3.0, vCard 4.0, jCard and jCal.
-
-Just run it using `bin/vobject`. Composer will automatically also put a
-symlink in `vendor/bin` as well, or a directory of your choosing if you set
-the `bin-dir` setting in your composer.json.
-
-Support
--------
-
-Head over to the [SabreDAV mailing list](http://groups.google.com/group/sabredav-discuss) for any questions.
-
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-owncloud/php-sabre-vobject.git
More information about the Pkg-owncloud-commits
mailing list