Skip to content
Newer
Older
100644 125 lines (87 sloc) 3.29 KB
845ae02 dev version
heartsentwined authored Sep 5, 2012
1 # Heartsentwined\DateTimeParser
2
c3d25af updated readme
heartsentwined authored Sep 6, 2012
3 [![Build Status](https://secure.travis-ci.org/heartsentwined/date-time-parser.png)](http://travis-ci.org/heartsentwined/date-time-parser)
845ae02 dev version
heartsentwined authored Sep 5, 2012
4
5 Parse date and time according to the subset of ISO 8601 date/time format used in Vcard [ISO 6350].
6
7 # Installation
8
9 [Composer](http://getcomposer.org/):
10
11 ```json
12 {
13 "require": {
32f1343 updated readme on installation instructions
heartsentwined authored Sep 6, 2012
14 "heartsentwined/date-time-parser": "1.*"
845ae02 dev version
heartsentwined authored Sep 5, 2012
15 }
16 }
17 ```
18
19 # Usage
20
836d125 updated readme; release 1.0.0
heartsentwined authored Sep 5, 2012
21 ## Parse an ISO-8601 date/time
22
23 ```php
24 use Heartsentwined\DateTimeParser\Parser;
25
26 $datetime = Parser::parseDateTime('19961022T140000+0800');
27 // $datetime['year'] = '1996';
28 // $datetime['month'] = '10';
29 // $datetime['day'] = '22';
30 // $datetime['hour'] = '14';
31 // $datetime['minute'] = '00';
32 // $datetime['second'] = '00';
33 // $datetime['timezone'] = '+0800';
34
35 $datetime = Parser::parseDateTime('---22T14');
36 // $datetime['year'] = null;
37 // $datetime['month'] = null;
38 // $datetime['day'] = '22';
39 // $datetime['hour'] = '14';
40 // $datetime['minute'] = null;
41 // $datetime['second'] = null;
42 // $datetime['timezone'] = null;
43 ```
44
45 Full function signature:
46
47 ```php
48 public static function parseDateTime($datetime)
49 ```
50
51 It accepts an ISO-8601 date-and-or-time string and returns an array of datetime units. It will throw an `InvalidArgumentException` if the input is not a valid date/time expression, or if the date/time specified is invalid.
52
53 Missing date/time units will be filled with `null`.
54
55 Standalone time expressions must be prefixed with `T`.
56
57 To parse an ISO-8601 date expression, use:
58
59 ```php
60 public static function parseDate($date)
61 ```
62
63 To parse an ISO-8601 time expression, use:
64
65 ```php
66 public static function parseTime($time)
67 ```
68
69 The return array for these two functions are same as `Parser::parseDateTime()`.
70
71 ## Create an ISO-8601 date/time
72
73 ```php
74 use Heartsentwined\DateTimeParser\Parser;
75
76 $expr = Parser::createDateTime('1996', '10', '22', '14', '00', '00', '+0800');
77 // $expr = '19961022T140000+0800';
78
79 $expr = Parser::createDateTime(null, null, '22', '14', null, null, null);
80 // $expr = '---22T14';
81 ```
82
83 These are simply reverses of the `parse-()` functions.
84
85 Full function signatures:
86
87 ```php
88 public static function createDateTime(
89 $year = null, $month = null, $day = null,
90 $hour = null, $minute = null, $second = null, $timezone = null)
91 ```
92
93 ```php
94 public static function createDate($year = null, $month = null, $day = null)
95 ```
96
97 ```php
98 public static function createTime($hour = null, $minute = null, $second = null, $timezone = null)
99 ```
100
101 Valid ranges:
102
103 - Year: (unlimited)
104 - Month: 01-12
105 - Day: 01-31
106 - Hour: 00-23
107 - Minute: 00-59
108 - Second: 00-59
109
110 Note that `0`-prefixed numbers are different from `0`-prefixed strings. For example, if you mean August, write `8` or `'08'`, not `08`.
111
112 ## Create a timestamp from a complete or partial date/time
113
114 ```php
115 public static function createTimestamp(
116 $year = null, $month = null, $day = null,
117 $hour = null, $minute = null, $second = null, $timezone = null)
118 ```
119
120 Accepted arguments are same as the `create-()` series.
121
122 `Parser::createTimestamp()` will create a timestamp if at least `year`, `month`, `day` are given (and valid). It will assume `'00'` for `hour`, `minute` and `second` if not given; and script timezone if `timezone` is not given.
123
124 Return `null` if failed to create a timestamp.
Something went wrong with that request. Please try again.