add wrapper functions and doku
[tine20] / README.md
1 TimeZoneConverter - PHP Timezone Converter
2 ==========================================
3
4 Library to convert PHP timezones from and into external representations like VTIMEZONE.
5
6 Supported Timezone Representations
7 ----------------------------------
8
9 The following representations are supported.
10
11 * [VTtimeZone](http://tools.ietf.org/html/rfc5545#section-3.6.5) -- ICAL VTIMEZONE Components (RFC 5545)
12
13 VTimeZone
14 ---------
15
16 ### Convert VTIMEZONE to DateTimeZone
17
18      (DateTimeZone) TimeZoneConvert::fromVTimeZone(string $VTimeZone [, string $prodId = "" [, mixed $expectedTimeZone = NULL]]); 
19
20 In the best case, the VTIMEZONE contains a well known timezone identifier
21 string the library can detect.  In this case $prodId and $expectedTimeZone
22 are not evaluated. If not, things become complicated.
23
24 A VTIMEZONE describes the rules which apply for the given timezone.
25 Unfortunally this rule is of no help in PHP timezone computations are
26 based on a DateTimeZone object which could represent one of the 
27 approximatly 400 build in timezones indentified by a timezone id which
28 is the timezone name of the ohlson timezone database.
29
30 As multiple timezones follow the same rules, it is not possible to compute
31 the described timezone precisely. For instance the rules for Europe/Berlin
32 are exactly the same as for Europe/Paris. Therefore its possible to pass
33 the optional $expectedTimeZone parameter to pick the appropriate timezone.
34
35 Some clients just send horrible VTIMEZONE components which don't have a
36 known timezone identifier and also don't have a correct definition.  For
37 these cases the library maintains a [ChamberOfHorrors](TimeZoneConvert/blob/master/lib/TimeZoneConvert/VTimeZone/ChamberOfHorrors.php)
38 with a hash of $prodId and $vTimeZone.
39
40
41 ### Convert DateTimeZone to VTIMEZONE
42
43      (string) TimeZoneConvert::toVTimeZone(mixed $timezone [, DateTime $from = NULL [, DateTime $until]])
44
45 Arround the 1990 most timezones of the industrial nations became defined
46 by a recurring rule and where not tuched since that.  If the VTIMEZONE 
47 component is requested for a period the timezone could not be described
48 by a single recurring rule, the library will describe it by its transition
49 dates.
50
51 If the $from parameter is ommited the definition in computed from 
52 DateTime('now'). If $until is ommited the definition is computed for the
53 period PHP maintains informations for.
54