documentation/manual/en/module_specs/Zend_Locale-DatesTimes.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.locale.date.datesandtimes">
   4     <title>Working with Dates and Times</title>
   5
   6     <para>
   7         <classname>Zend_Locale_Format</classname> provides several methods for working with dates
   8         and times to help convert and normalize between different formats for different locales. Use
   9         <classname>Zend_Date</classname> for manipulating dates, and working with date strings that
  10         already conform to <link linkend="zend.date.constants">one of the many internationally
  11             recognized standard formats, or one of the localized date formats supported by
  12             <classname>Zend_Date</classname></link>. Using an existing, pre-defined format offers
  13         advantages, including the use of well-tested code, and the assurance of some degree of
  14         portability and interoperability (depending on the standard used). The examples below do not
  15         follow these recommendations, since using non-standard date formats would needlessly
  16         increase the difficulty of understanding these examples.
  17     </para>
  18
  19     <sect2 id="zend.locale.date.normalize">
  20         <title>Normalizing Dates and Times</title>
  21
  22         <para>
  23             The <methodname>getDate()</methodname> method parses strings containing dates in
  24             localized formats. The results are returned in a structured array, with well-defined
  25             keys for each part of the date. In addition, the array will contain a key 'date_format'
  26             showing the format string used to parse the input date string. Since a localized date
  27             string may not contain all parts of a date/time, the key-value pairs are optional. for
  28             example, if only the year, month, and day is given, then all time values are suppressed
  29             from the returned array, and vice-versa if only hour, minute, and second were given as
  30             input. If no date or time can be found within the given input, an exception will be
  31             thrown.
  32         </para>
  33
  34         <para>
  35             If <methodname>setOption(array('fix_date' => true))</methodname> is set the
  36             <methodname>getDate()</methodname> method adds a key 'fixed' with a whole number value
  37             indicating if the input date string required "fixing" by rearranging the day, month, or
  38             year in the input to fit the format used.
  39         </para>
  40
  41         <table id="zend.locale.date.normalize.table-1">
  42             <title>Key values for getDate() with option 'fix_date'</title>
  43
  44             <tgroup cols='2'>
  45                 <thead>
  46                     <row>
  47                         <entry>value</entry>
  48                         <entry>meaning</entry>
  49                     </row>
  50                 </thead>
  51
  52                 <tbody>
  53                     <row>
  54                         <entry>0</entry>
  55                         <entry>nothing to fix</entry>
  56                     </row>
  57
  58                     <row>
  59                         <entry>1</entry>
  60                         <entry>fixed false month</entry>
  61                     </row>
  62
  63                     <row>
  64                         <entry>2</entry>
  65                         <entry>swapped day and year</entry>
  66                     </row>
  67
  68                     <row>
  69                         <entry>3</entry>
  70                         <entry>swapped month and year</entry>
  71                     </row>
  72
  73                     <row>
  74                         <entry>4</entry>
  75                         <entry>swapped month and day</entry>
  76                     </row>
  77                 </tbody>
  78             </tgroup>
  79         </table>
  80
  81         <para>
  82             For those needing to specify explicitly the format of the date string, the following
  83             format token specifiers are supported. If an invalid format specifier is used, such as
  84             the <acronym>PHP</acronym> 'i' specifier when in <acronym>ISO</acronym> format mode,
  85             then an error will be thrown by the methods in <classname>Zend_Locale_Format</classname>
  86             that support user-defined formats.
  87         </para>
  88
  89         <para>
  90             These specifiers (below) are a small subset of the full "ISO" set supported by
  91             <classname>Zend_Date</classname>'s <methodname>toString()</methodname>. If you need to
  92             use <acronym>PHP</acronym> <methodname>date()</methodname> compatible format specifiers,
  93             then first call <methodname>setOptions(array('format_type' => 'php'))</methodname>. And
  94             if you want to convert only one special format string from <acronym>PHP</acronym>
  95             <methodname>date()</methodname> compatible format to "ISO" format use
  96             <methodname>convertPhpToIsoFormat()</methodname>. Currently, the only practical
  97             difference relates to the specifier for minutes ('m' using the <acronym>ISO</acronym>
  98             default, and 'i' using the <acronym>PHP</acronym> date format).
  99         </para>
 100
 101         <table id="zend.locale.date.normalize.table-2">
 102             <title>Return values</title>
 103
 104             <tgroup cols='5'>
 105                 <thead>
 106                     <row>
 107                         <entry>getDate() format character</entry>
 108                         <entry>Array key</entry>
 109                         <entry>Returned value</entry>
 110                         <entry>Minimum</entry>
 111                         <entry>Maximum</entry>
 112                     </row>
 113                 </thead>
 114
 115                 <tbody>
 116                     <row>
 117                         <entry>d</entry>
 118                         <entry>day</entry>
 119                         <entry>integer</entry>
 120                         <entry>1</entry>
 121                         <entry>31</entry>
 122                     </row>
 123
 124                     <row>
 125                         <entry>M</entry>
 126                         <entry>month</entry>
 127                         <entry>integer</entry>
 128                         <entry>1</entry>
 129                         <entry>12</entry>
 130                     </row>
 131
 132                     <row>
 133                         <entry>y</entry>
 134                         <entry>year</entry>
 135                         <entry>integer</entry>
 136                         <entry>no limit</entry>
 137                         <entry>PHP integer's maximum</entry>
 138                     </row>
 139
 140                     <row>
 141                         <entry>h</entry>
 142                         <entry>hour</entry>
 143                         <entry>integer</entry>
 144                         <entry>0</entry>
 145                         <entry>PHP integer's maximum</entry>
 146                     </row>
 147
 148                     <row>
 149                         <entry>m</entry>
 150                         <entry>minute</entry>
 151                         <entry>integer</entry>
 152                         <entry>0</entry>
 153                         <entry>PHP integer's maximum</entry>
 154                     </row>
 155
 156                     <row>
 157                         <entry>s</entry>
 158                         <entry>second</entry>
 159                         <entry>integer</entry>
 160                         <entry>0</entry>
 161                         <entry>PHP integer's maximum</entry>
 162                     </row>
 163                 </tbody>
 164             </tgroup>
 165         </table>
 166
 167         <example id="zend.locale.date.normalize.example-1">
 168             <title>Normalizing a date</title>
 169
 170             <programlisting language="php"><![CDATA[
 171 $dateString = Zend_Locale_Format::getDate('13.04.2006',
 172                                           array('date_format' =>
 173                                                     'dd.MM.yyyy')
 174                                          );
 175
 176 // creates a Zend_Date object for this date
 177 $dateObject = Zend_Date('13.04.2006',
 178                          array('date_format' => 'dd.MM.yyyy'));
 179
 180 print_r($dateString); // outputs:
 181
 182 Array
 183 (
 184     [format] => dd.MM.yyyy
 185     [day] => 13
 186     [month] => 4
 187     [year] => 2006
 188 )
 189
 190 // alternatively, some types of problems with input data can be
 191 // automatically corrected
 192 $date = Zend_Locale_Format::getDate('04.13.2006',
 193                                     array('date_format' => 'dd.MM.yyyy',
 194                                           'fix_date' => true)
 195                                    );
 196
 197 print_r($date); // outputs:
 198
 199 Array
 200 (
 201     [format] => dd.MM.yyyy
 202     [day] => 13
 203     [month] => 4
 204     [year] => 2006
 205     [fixed] => 4
 206 )
 207 ]]></programlisting>
 208         </example>
 209
 210         <para>
 211             Since <methodname>getDate()</methodname> is "locale-aware", specifying the
 212             <varname>$locale</varname> is sufficient for date strings adhering to that locale's
 213             format. The option '<code>fix_date</code>' uses simple tests to determine if the day or
 214             month is not valid, and then applies heuristics to try and correct any detected
 215             problems. Note the use of '<constant>Zend_Locale_Format::STANDARD</constant>' as the
 216             value for '<code>date_format</code>' to prevent the use of a class-wide default date
 217             format set using <methodname>setOptions()</methodname>. This forces getDate to use the
 218             default date format for <varname>$locale</varname>.
 219         </para>
 220
 221         <example id="zend.locale.date.normalize.example-2">
 222             <title>Normalizing a date by locale</title>
 223
 224             <programlisting language="php"><![CDATA[
 225 $locale = new Zend_Locale('de_AT');
 226 $date = Zend_Locale_Format::getDate('13.04.2006',
 227                                     array('date_format' =>
 228                                               Zend_Locale_Format::STANDARD,
 229                                           'locale' => $locale)
 230                                    );
 231
 232 print_r ($date);
 233 ]]></programlisting>
 234         </example>
 235
 236         <para>
 237             A complete date and time is returned when the input contains both a date and time in the
 238             expected format.
 239         </para>
 240
 241         <example id="zend.locale.date.normalize.example-3">
 242             <title>Normalizing a date with time</title>
 243
 244             <programlisting language="php"><![CDATA[
 245 $locale = new Zend_Locale('de_AT');
 246 $date = Zend_Locale_Format::getDate('13.04.2005 22:14:55',
 247                                     array('date_format' =>
 248                                                 Zend_Locale_Format::STANDARD,
 249                                           'locale' => $locale)
 250                                     );
 251
 252 print_r ($date);
 253 ]]></programlisting>
 254         </example>
 255
 256         <para>
 257             If a specific format is desired, specify the <varname>$format</varname> argument,
 258             without giving a <varname>$locale</varname>. Only single-letter codes
 259             (H, m, s, y, M, d), and MMMM and EEEE are supported in the <varname>$format</varname>.
 260         </para>
 261
 262         <example id="zend.locale.date.normalize.example-4">
 263             <title>Normalizing a userdefined date</title>
 264
 265             <programlisting language="php"><![CDATA[
 266 $date = Zend_Locale_Format::getDate('13200504T551422',
 267                                     array('date_format' =>
 268                                               'ddyyyyMM ssmmHH')
 269                                    );
 270
 271 print_r ($date);
 272 ]]></programlisting>
 273         </example>
 274
 275         <para>
 276             The format can include the following signs :
 277         </para>
 278
 279         <table id="zend.locale.date.normalize.table-3">
 280             <title>Format definition</title>
 281
 282             <tgroup cols='2'>
 283                 <thead>
 284                     <row>
 285                         <entry>Format Letter</entry>
 286                         <entry>Description</entry>
 287                     </row>
 288                 </thead>
 289
 290                 <tbody>
 291                     <row>
 292                         <entry>d or dd</entry>
 293                         <entry>1 or 2 digit day</entry>
 294                     </row>
 295
 296                     <row>
 297                         <entry>M or MM</entry>
 298                         <entry>1 or 2 digit month</entry>
 299                     </row>
 300
 301                     <row>
 302                         <entry>y or yy</entry>
 303                         <entry>1 or 2 digit year</entry>
 304                     </row>
 305
 306                     <row>
 307                         <entry>yyyy</entry>
 308                         <entry>4 digit year</entry>
 309                     </row>
 310
 311                     <row>
 312                         <entry>h</entry>
 313                         <entry>1 or 2 digit hour</entry>
 314                     </row>
 315
 316                     <row>
 317                         <entry>m</entry>
 318                         <entry>1 or 2 digit minute</entry>
 319                     </row>
 320
 321                     <row>
 322                         <entry>s</entry>
 323                         <entry>1 or 2 digit second</entry>
 324                     </row>
 325                 </tbody>
 326             </tgroup>
 327         </table>
 328
 329         <para>
 330             Examples for proper formats are
 331         </para>
 332
 333         <table id="zend.locale.date.normalize.table-4">
 334             <title>Example formats</title>
 335
 336             <tgroup cols='3'>
 337                 <thead>
 338                     <row>
 339                         <entry>Formats</entry>
 340                         <entry>Input</entry>
 341                         <entry>Output</entry>
 342                     </row>
 343                 </thead>
 344
 345                 <tbody>
 346                     <row>
 347                         <entry>dd.MM.yy</entry>
 348                         <entry>1.4.6</entry>
 349                         <entry>['day'] => 1, ['month'] => 4, ['year'] => 6</entry>
 350                     </row>
 351
 352                     <row>
 353                         <entry>dd.MM.yy</entry>
 354                         <entry>01.04.2006</entry>
 355                         <entry>['day'] => 1, ['month'] => 4, ['year'] => 2006</entry>
 356                     </row>
 357
 358                     <row>
 359                         <entry>yyyyMMdd</entry>
 360                         <entry>1.4.6</entry>
 361                         <entry>['day'] => 6, ['month'] => 4, ['year'] => 1</entry>
 362                     </row>
 363                 </tbody>
 364             </tgroup>
 365         </table>
 366
 367         <note>
 368             <title>Database date format</title>
 369
 370             <para>
 371                 To parse a database date value (f.e. MySql or MsSql), use
 372                 <classname>Zend_Date</classname>'s ISO_8601 format instead of getDate().
 373             </para>
 374         </note>
 375
 376         <para>
 377             The option '<code>fix_date</code>' uses simple tests to determine if the day or month is
 378             not valid, and then applies heuristics to try and correct any detected problems.
 379             <methodname>getDate()</methodname> automatically detects and corrects some kinds of
 380             problems with input, such as misplacing the year:
 381         </para>
 382
 383         <example id="zend.locale.date.normalize.example-5">
 384             <title>Automatic correction of input dates</title>
 385
 386             <programlisting language="php"><![CDATA[
 387 $date = Zend_Locale_Format::getDate('41.10.20',
 388                                     array('date_format' => 'ddMMyy',
 389                                           'fix_date' => true)
 390                                    );
 391
 392 // instead of 41 for the day, the 41 will be returned as year value
 393 print_r ($date);
 394 ]]></programlisting>
 395         </example>
 396     </sect2>
 397
 398     <sect2 id="zend.locale.date.test">
 399         <title>Testing Dates</title>
 400
 401         <para>
 402             Use <methodname>checkDateFormat($inputString, array('date_format' => $format,
 403                 $locale))</methodname> to check if a given string contains all expected date parts.
 404             The <methodname>checkDateFormat()</methodname> method uses
 405             <methodname>getDate()</methodname>, but without the option <code>'fixdate'</code> to
 406             avoid returning <constant>TRUE</constant> when the input fails to conform to the date
 407             format. If errors are detected in the input, such as swapped values for months and days,
 408             the option <code>'fixdate'</code> method will apply heuristics to "correct" dates before
 409             determining their validity.
 410         </para>
 411
 412         <example id="zend.locale.date.test.example-1">
 413             <title>Date testing</title>
 414
 415             <programlisting language="php"><![CDATA[
 416 $locale = new Zend_Locale('de_AT');
 417 // using the default date format for 'de_AT', is this a valid date?
 418 if (Zend_Locale_Format::checkDateFormat('13.Apr.2006',
 419                                         array('date_format' =>
 420                                                   Zend_Locale_Format::STANDARD,
 421                                               $locale)
 422                                        ) {
 423     print "date";
 424 } else {
 425     print "not a date";
 426 }
 427 ]]></programlisting>
 428         </example>
 429     </sect2>
 430
 431     <sect2 id="zend.locale.time.normalizing">
 432         <title>Normalizing a Time</title>
 433
 434         <para>
 435             Normally, a time will be returned with a date, if the input contains both. If the proper
 436             format is not known, but the locale relevant to the user input is known, then
 437             <methodname>getTime()</methodname> should be used, because it uses the default time
 438             format for the selected locale.
 439         </para>
 440
 441         <example id="zend.locale.time.normalizing.example-1">
 442             <title>Normalize an unknown time</title>
 443
 444             <programlisting language="php"><![CDATA[
 445 $locale = new Zend_Locale('de_AT');
 446 if (Zend_Locale_Format::getTime('13:44:42',
 447                                 array('date_format' =>
 448                                           Zend_Locale_Format::STANDARD,
 449                                       'locale' => $locale)) {
 450     print "time";
 451 } else {
 452     print "not a time";
 453 }
 454 ]]></programlisting>
 455         </example>
 456     </sect2>
 457
 458     <sect2 id="zend.locale.time.test">
 459         <title>Testing Times</title>
 460
 461         <para>
 462             Use <methodname>checkDateFormat()</methodname> to check if a given string contains a
 463             proper time. The usage is exact the same as with checking Dates, only
 464             <code>date_format</code> should contain the parts which you expect to have.
 465         </para>
 466
 467         <example id="zend.locale.time.test.example-1">
 468             <title>Testing a time</title>
 469
 470             <programlisting language="php"><![CDATA[
 471 $locale = new Zend_Locale('de_AT');
 472 if (Zend_Locale_Format::checkDateFormat('13:44:42',
 473                                         array('date_format' => 'HH:mm:ss',
 474                                               'locale' => $locale)) {
 475     print "time";
 476 } else {
 477     print "not a time";
 478 }
 479 ]]></programlisting>
 480         </example>
 481     </sect2>
 482 </sect1>
 483 <!--
 484 vim:se ts=4 sw=4 et:
 485 -->