1 | INFORMATION FOR DEVELOPERS |
---|
2 | |
---|
3 | Once the Date API is installed, all functions in the API are available to be used |
---|
4 | anywhere by any module. If the Date Timezone module is installed, the system site |
---|
5 | timezone selector and the user timezone selectors are overwritten to allow the |
---|
6 | selection of timezone names instead of offsets. Proper timezone conversion |
---|
7 | requires knowledge of those timezone names, something that is not currently |
---|
8 | available in Drupal core, and the change in selectors makes it possible to track it. |
---|
9 | |
---|
10 | In most cases, you should enable the Date Timezone module any time you use the |
---|
11 | Date API to be able to set the site and user timezone names. It is not enabled by |
---|
12 | default in case another module is setting timezone names in the database. |
---|
13 | |
---|
14 | The API uses the PHP 5.2 date functions to create and manipulate dates, and |
---|
15 | contains an option module that will emulate those functions in earlier versions |
---|
16 | of PHP. |
---|
17 | |
---|
18 | If you are using PHP 4 or PHP 5.0 or 5.1, native date handling won't work right. |
---|
19 | Install the Date_PHP4 module to enable wrapper functions so this code will work |
---|
20 | in old PHP versions. |
---|
21 | |
---|
22 | Example, the following will create a date for the local value in one |
---|
23 | timezone, adjust it to a different timezone, then return the offset in seconds |
---|
24 | in the new timezone for the input date; The offset will be adjusted for both |
---|
25 | the timezone difference and daylight savings time, if necessary: |
---|
26 | |
---|
27 | $date = date_create('2007-03-11 02:00:00', timezone_open('America/Chicago')); |
---|
28 | $chicago_time = date_format($date, 'Y-m-d H:i'); |
---|
29 | |
---|
30 | print 'At '. $chicago_time .' in Chicago, the timezone offset in seconds |
---|
31 | was '. date_offset_get($date); |
---|
32 | |
---|
33 | date_timezone_set($date, timezone_open('Europe/Berlin'); |
---|
34 | $berlin_time = date_format($date, 'Y-m-d H:i'); |
---|
35 | |
---|
36 | print 'It was '. $berlin_time .' in Berlin when it |
---|
37 | was '. $chicago_time .' in Chicago.'; |
---|
38 | print 'At that time in Berlin, the timezone offset in seconds was |
---|
39 | '. date_offset_get($date); |
---|
40 | |
---|
41 | A helper function is available, date_make_date($string, $timezone, $type), |
---|
42 | where $string is a unixtimestamp, an ISO date, or a string like YYYY-MM-DD HH:MM:SS, |
---|
43 | $timezone is the name of the timezone this date is in, and $type is the type |
---|
44 | of date it is (DATE_UNIX, DATE_ISO, or DATE_DATETIME). It create and return |
---|
45 | a date object set to the right date and timezone. |
---|
46 | |
---|
47 | Simpletest tests for these functions are included in the package. |
---|
48 | |
---|
49 | Available functions include the following (more documentation is provided in |
---|
50 | the files): |
---|
51 | |
---|
52 | ============================================================================ |
---|
53 | Date PHP4 Module |
---|
54 | ============================================================================ |
---|
55 | PHP 4 substitutions for the PHP 5 date functions are supplied. Use the PHP 5 |
---|
56 | functions in your code as they would normally be used and the PHP 4 |
---|
57 | alternatives will be automatically be substituted in when needed. |
---|
58 | |
---|
59 | You cannot do everything with these functions that can be done in PHP 5, but |
---|
60 | you can create dates, find timezone offsets, and format the results. |
---|
61 | Timezone handling uses native PHP 5 functions when available and degrades |
---|
62 | automatically for PHP 4 to use substitutions like those |
---|
63 | provided in previous versions of the Date and Event modules. |
---|
64 | |
---|
65 | Read the doxygen documentation in this module for more information |
---|
66 | about using the functions in ways that will work in PHP 4. |
---|
67 | |
---|
68 | Simpletest tests for the PHP 4 equivalent functions are included in the package. |
---|
69 | |
---|
70 | The following functions are emulated in PHP4: |
---|
71 | date_create() |
---|
72 | date_date_set() |
---|
73 | date_format() |
---|
74 | date_offset_get() |
---|
75 | date_timezone_set() |
---|
76 | timezone_abbreviations_list() |
---|
77 | timezone_identifiers_list() |
---|
78 | timezone_offset_get() |
---|
79 | timezone_open() |
---|
80 | |
---|
81 | ============================================================================ |
---|
82 | Preconfigured arrays |
---|
83 | ============================================================================ |
---|
84 | Both translated and untranslated values are available. The date_week_days_ordered() |
---|
85 | function will shift an array of week day names so it starts with the site's |
---|
86 | first day of the week, otherwise the weekday names start with Sunday as the first |
---|
87 | value, the expected order for many php and sql functions. |
---|
88 | |
---|
89 | date_month_names(); |
---|
90 | date_month_names_abbr(); |
---|
91 | date_month_names_untranslated(); |
---|
92 | date_week_days(); |
---|
93 | date_week_days_abbr(); |
---|
94 | date_week_days_untranslated(); |
---|
95 | date_week_days_ordered(); |
---|
96 | date_years(); |
---|
97 | date_hours(); |
---|
98 | date_minutes(); |
---|
99 | date_seconds(); |
---|
100 | date_timezone_names(); |
---|
101 | date_ampm(); |
---|
102 | |
---|
103 | ============================================================================ |
---|
104 | Miscellaneous date manipulation functions |
---|
105 | ============================================================================ |
---|
106 | Pre-defined constants and functions that will handle pre-1970 and post-2038 |
---|
107 | dates in both PHP 4 and PHP 5, in any OS. Dates can be converted from one |
---|
108 | type to another and date parts can be extracted from any date type. |
---|
109 | |
---|
110 | DATE_DATETIME |
---|
111 | DATE_ISO |
---|
112 | DATE_UNIX |
---|
113 | DATE_ARRAY |
---|
114 | DATE_OBJECT |
---|
115 | DATE_ICAL |
---|
116 | |
---|
117 | date_convert() |
---|
118 | date_is_valid(); |
---|
119 | date_part_is_valid(); |
---|
120 | date_part_extract(); |
---|
121 | |
---|
122 | ============================================================================ |
---|
123 | Date calculation and navigation |
---|
124 | ============================================================================ |
---|
125 | date_difference() will find the time difference between any two days, measured |
---|
126 | in seconds, minutes, hours, days, months, weeks, or years. |
---|
127 | |
---|
128 | date_days_in_month(); |
---|
129 | date_days_in_year(); |
---|
130 | date_weeks_in_year(); |
---|
131 | date_last_day_of_month(); |
---|
132 | date_day_of_week(); |
---|
133 | date_day_of_week_name(); |
---|
134 | date_difference(); |
---|
135 | |
---|
136 | ============================================================================ |
---|
137 | Date regex and format helpers |
---|
138 | ============================================================================ |
---|
139 | Pre-defined constants, an array of date format strings and their |
---|
140 | equivalent regex strings. |
---|
141 | |
---|
142 | DATE_REGEX_LOOSE is a very loose regex that will pull date parts out |
---|
143 | of an ISO date with or without separators, using either 'T' or a space |
---|
144 | to separate date and time, and with or without time. |
---|
145 | |
---|
146 | date_format_date() is similar to format_date(), except it takes a |
---|
147 | date object instead of a timestamp as the first parameter. |
---|
148 | |
---|
149 | DATE_FORMAT_ISO |
---|
150 | DATE_FORMAT_DATETIME |
---|
151 | DATE_FORMAT_UNIX |
---|
152 | DATE_FORMAT_ICAL |
---|
153 | |
---|
154 | DATE_REGEX_ISO |
---|
155 | DATE_REGEX_DATETIME |
---|
156 | DATE_REGEX_LOOSE |
---|
157 | |
---|
158 | date_format_date(); |
---|
159 | date_t() |
---|
160 | date_short_formats(); |
---|
161 | date_medium_formats(); |
---|
162 | date_long_formats(); |
---|
163 | date_format_patterns(); |
---|
164 | |
---|
165 | ============================================================================ |
---|
166 | Standardized ical parser and creator |
---|
167 | ============================================================================ |
---|
168 | The iCal parser is found in date_api_ical.inc, which is not included by default. |
---|
169 | Include that file if you want to use these functions: |
---|
170 | |
---|
171 | Complete rewrite of ical imports to parse vevents, vlocations, valarms, |
---|
172 | and all kinds of timezone options and repeat rules for ical imports. |
---|
173 | The function now sticks to parsing the ical into an array that can be used |
---|
174 | in various ways. It no longer trys to convert timezones while parsing, |
---|
175 | instead a date_ical_date_format() function is provided that can be used to |
---|
176 | convert from the ical timezone to whatever timezone is desired in the |
---|
177 | results. Repeat rules are parsed into an array which other modules can |
---|
178 | manipulate however they like to create additional events from the results. |
---|
179 | |
---|
180 | date_ical_export(); |
---|
181 | date_ical_import(); |
---|
182 | date_ical_date_format(); |
---|
183 | |
---|
184 | ============================================================================ |
---|
185 | Helpers for portable date SQL |
---|
186 | ============================================================================ |
---|
187 | The SQL functions are found in date_api_sql.inc, which is not included by default. |
---|
188 | Include that file if you want to use these functions: |
---|
189 | |
---|
190 | date_sql(); |
---|
191 | date_server_zone_adj(); |
---|
192 | date_sql_concat(); |
---|
193 | date_sql_pad(); |
---|
194 | |
---|
195 | ============================================================================ |
---|
196 | Date forms and validators |
---|
197 | ============================================================================ |
---|
198 | Reusable, configurable, self-validating FAPI date elements are found in |
---|
199 | date_api_elements.inc, which is not included by default. Include it |
---|
200 | if you want to use these elements. To use them, create a form element |
---|
201 | and set the '#type' to one of the following: |
---|
202 | |
---|
203 | date_select |
---|
204 | The date_select element will create a collection of form elements, with a |
---|
205 | separate select or textfield for each date part. The whole collection will |
---|
206 | get re-formatted back into a date value of the requested type during validation. |
---|
207 | |
---|
208 | date_text |
---|
209 | The date_text element will create a textfield that can contain a whole |
---|
210 | date or any part of a date as text. The user input value will be re-formatted |
---|
211 | back into a date value of the requested type during validation. |
---|
212 | |
---|
213 | date_timezone |
---|
214 | The date_timezone element will create a drop-down selector to pick a |
---|
215 | timezone name. |
---|
216 | |
---|
217 | The custom date elements require a few other pieces of information to work |
---|
218 | correctly, like #date_format and #date_type. See the internal documentation |
---|
219 | for more information. |
---|
220 | |
---|
221 | ============================================================================ |
---|
222 | Date Popup Module |
---|
223 | ============================================================================ |
---|
224 | |
---|
225 | A new module is included in the package that will enable a popup jQuery |
---|
226 | calendar date picker and timepicker in date and time fields. |
---|
227 | |
---|
228 | It is implemented as a custom form element, so set '#type' to 'date_popup' |
---|
229 | to use this element. See the internal documentation for more information. |
---|
230 | |
---|
231 | ============================================================================ |
---|
232 | Date Repeat API |
---|
233 | ============================================================================ |
---|
234 | |
---|
235 | An API for repeating dates is available if installed. It can be used by |
---|
236 | other modules to create a form element that will allow users to select |
---|
237 | repeat rules and store those selections in an iCal RRULE string, and a |
---|
238 | calculation function that will parse the RRULE and return an array of dates |
---|
239 | that match those rules. The API is implemented in the Date module as a |
---|
240 | new date widget if the Date Repeat API is installed. |
---|
241 | |
---|
242 | ============================================================================ |
---|
243 | Install file for dependent modules |
---|
244 | ============================================================================ |
---|
245 | |
---|
246 | The following code is an example of what should go in the .install file for |
---|
247 | any module that uses the new Date API. This is needed to be sure the system |
---|
248 | is not using an earlier version of the API that didn't include all these new |
---|
249 | features. Testing for version '5.2' will pick up any version on or after the |
---|
250 | change to the new API. |
---|
251 | |
---|
252 | /** |
---|
253 | * Implementation of hook_requirements(). |
---|
254 | */ |
---|
255 | function calendar_requirements($phase) { |
---|
256 | $requirements = array(); |
---|
257 | $t = get_t(); |
---|
258 | |
---|
259 | // This is the minimum required version for the Date API so that it will |
---|
260 | work with this module. |
---|
261 | $required_version = 5.2; |
---|
262 | |
---|
263 | // Make sure the matching version of date_api is installed. |
---|
264 | // Use info instead of an error at install time since the problem may |
---|
265 | // just be that they were installed in the wrong order. |
---|
266 | switch ($phase) { |
---|
267 | case 'runtime': |
---|
268 | if (variable_get('date_api_version', 0) < $required_version) { |
---|
269 | $requirements['calendar_api_version'] = array( |
---|
270 | 'title' => $t('Calendar requirements'), |
---|
271 | 'value' => $t('The Calendar module requires a more current version |
---|
272 | of the Date API. Please check for a newer version.'), |
---|
273 | 'severity' => REQUIREMENT_ERROR, |
---|
274 | ); |
---|
275 | } |
---|
276 | break; |
---|
277 | case 'install': |
---|
278 | if (variable_get('date_api_version', 0) < $required_version) { |
---|
279 | $requirements['calendar_api_version'] = array( |
---|
280 | 'title' => $t('Calendar requirements'), |
---|
281 | 'value' => $t('The Calendar module requires the latest version |
---|
282 | of the Date API, be sure you are installing the latest versions |
---|
283 | of both modules.'), |
---|
284 | 'severity' => REQUIREMENT_INFO, |
---|
285 | ); |
---|
286 | } |
---|
287 | break; |
---|
288 | } |
---|
289 | return $requirements; |
---|
290 | } |
---|
291 | |
---|
292 | /** |
---|
293 | * Implementation of hook_install(). |
---|
294 | */ |
---|
295 | function calendar_install() { |
---|
296 | // Make sure this module loads after date_api. |
---|
297 | db_query("UPDATE {system} SET weight = 1 WHERE name = 'calendar'"); |
---|
298 | } |
---|
299 | |
---|
300 | /** |
---|
301 | * Implementation of hook_update(). |
---|
302 | */ |
---|
303 | function calendar_update_5000() { |
---|
304 | $ret = array(); |
---|
305 | $ret[] = update_sql("UPDATE {system} SET weight = 1 WHERE name = 'calendar'"); |
---|
306 | return $ret; |
---|
307 | } |
---|