|
|
@@ -1,30 +1,32 @@
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
-<!-- EN-Revision: 15103 -->
|
|
|
+<!-- EN-Revision: 17344 -->
|
|
|
<!-- Reviewed: no -->
|
|
|
<sect1 id="zend.date.overview">
|
|
|
|
|
|
<title>Zend_Date API Overview</title>
|
|
|
|
|
|
- <para>
|
|
|
- Mientras la API <classname>Zend_Date</classname> permanece simple y unitaria, el diseo permanece flexible y poderoso
|
|
|
- a travs de las permiutaciones de operaciones y operandos.
|
|
|
- </para>
|
|
|
+ <para> Mientras la <acronym>API</acronym> <classname>Zend_Date</classname> permanece simple y unitaria, el diseo permanece flexible y poderoso a
|
|
|
+ travs de las permiutaciones de operaciones y operandos. </para>
|
|
|
|
|
|
<sect2 id="zend.date.options">
|
|
|
|
|
|
<title>Opciones Zend_Date</title>
|
|
|
|
|
|
+
|
|
|
<sect3 id="zend.date.options.formattype">
|
|
|
|
|
|
- <title>seleccionando el tipo de formato de la fecha</title>
|
|
|
+ <title>Selecting the Date Format Type</title>
|
|
|
|
|
|
<para>
|
|
|
- Several methods use date format strings, in a way similar to PHP's <methodname>date()</methodname>.
|
|
|
- If you are more comfortable with PHP's date format specifier than with ISO format specifiers,
|
|
|
- then you can use <classname>Zend_Date::setOptions(array('format_type' => 'php'))</classname>.
|
|
|
- Afterward, use PHP's date format specifiers for all functions which accept a <methodname>$format</methodname> parameter.
|
|
|
- Use <classname>Zend_Date::setOptions(array('format_type' => 'iso'))</classname> to switch back to the default mode of
|
|
|
- supporting only ISO date format tokens. For a list of supported format codes, see
|
|
|
+ Several methods use date format strings, in a way similar to <acronym>PHP</acronym>'s
|
|
|
+ <methodname>date()</methodname>. If you are more comfortable with <acronym>PHP</acronym>'s date format
|
|
|
+ specifier than with <acronym>ISO</acronym> format specifiers, then you can use
|
|
|
+ <methodname>Zend_Date::setOptions(array('format_type' => 'php'))</methodname>.
|
|
|
+ Afterward, use <acronym>PHP</acronym>'s date format specifiers for all functions which accept a
|
|
|
+ <varname>$format</varname> parameter. Use
|
|
|
+ <methodname>Zend_Date::setOptions(array('format_type' => 'iso'))</methodname> to
|
|
|
+ switch back to the default mode of supporting only <acronym>ISO</acronym> date format tokens. For a
|
|
|
+ list of supported format codes, see
|
|
|
<xref linkend="zend.date.constants.phpformats" />
|
|
|
</para>
|
|
|
|
|
|
@@ -35,29 +37,34 @@
|
|
|
<title>DST and Date Math</title>
|
|
|
|
|
|
<para>
|
|
|
- When dates are manipulated, sometimes they cross over a DST change, normally resulting in the date
|
|
|
- losing or gaining an hour. For exmaple, when adding months to a date before a DST change, if the
|
|
|
- resulting date is after the DST change, then the resulting date will appear to lose or gain an hour,
|
|
|
- resulting in the time value of the date changing. For boundary dates, such as midnight of the first
|
|
|
- or last day of a month, adding enough months to cross a date boundary results in the date losing
|
|
|
- an hour and becoming the last hour of the preceding month, giving the appearance of an "off by 1"
|
|
|
- error. To avoid this situation, the DST change ignored by using the <methodname>fix_dst</methodname> option.
|
|
|
- When crossing the Summer/Winter DST boundary, normally an hour is substracted or added depending
|
|
|
- on the date. For example, date math crossing the Spring DST leads to a date having a day value
|
|
|
- one less than expected, if the time part of the date was originally 00:00:00. Since Zend_Date
|
|
|
- is based on timestamps, and not calendar dates with a time component, the timestamp loses an hour,
|
|
|
- resulting in the date having a calendar day value one less than expected.
|
|
|
- To prevent such problems use the option <methodname>fix_dst</methodname>, which defaults to true, causing DST
|
|
|
- to have no effect on date "math" (<methodname>addMOnth(), subMonth()</methodname>). Use
|
|
|
- <classname>Zend_Date::setOptions(array('fix_dst' => false))</classname> to enable the subtraction or addition
|
|
|
- of the DST adjustment when performing date "math".
|
|
|
+ When dates are manipulated, sometimes they cross over a <acronym>DST</acronym> change, normally
|
|
|
+ resulting in the date losing or gaining an hour. For exmaple, when adding months to
|
|
|
+ a date before a <acronym>DST</acronym> change, if the resulting date is after the <acronym>DST</acronym> change, then the
|
|
|
+ resulting date will appear to lose or gain an hour, resulting in the time value of
|
|
|
+ the date changing. For boundary dates, such as midnight of the first or last day of
|
|
|
+ a month, adding enough months to cross a date boundary results in the date losing an
|
|
|
+ hour and becoming the last hour of the preceding month, giving the appearance of an
|
|
|
+ "off by 1" error. To avoid this situation, the <acronym>DST</acronym> change ignored by using the
|
|
|
+ <code>fix_dst</code> option. When crossing the Summer/Winter <acronym>DST</acronym> boundary, normally
|
|
|
+ an hour is substracted or added depending on the date. For example, date math
|
|
|
+ crossing the Spring <acronym>DST</acronym> leads to a date having a day value one less than expected,
|
|
|
+ if the time part of the date was originally 00:00:00. Since <classname>Zend_Date</classname> is based on
|
|
|
+ timestamps, and not calendar dates with a time component, the timestamp loses an
|
|
|
+ hour, resulting in the date having a calendar day value one less than expected. To
|
|
|
+ prevent such problems use the option <code>fix_dst</code>, which defaults to <constant>TRUE</constant>,
|
|
|
+ causing <acronym>DST</acronym> to have no effect on date "math" (<methodname>addMonth()</methodname>,
|
|
|
+ <methodname>subMonth()</methodname>). Use
|
|
|
+ <methodname>Zend_Date::setOptions(array('fix_dst' => false))</methodname> to
|
|
|
+ enable the subtraction or addition of the <acronym>DST</acronym> adjustment when performing date
|
|
|
+ "math".
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- <emphasis>If your actual timezone within the instance of <classname>Zend_Date</classname>
|
|
|
- is set to UTC or GMT the option <methodname>'fix_dst'</methodname> will not be used</emphasis> because
|
|
|
- these two timezones do not work with DST. When you change the timezone for this instance
|
|
|
- again to a timezone which is not UTC or GMT the previous set 'fix_dst' option will be used
|
|
|
+ <emphasis>If your actual timezone within the instance of
|
|
|
+ <classname>Zend_Date</classname> is set to <acronym>UTC</acronym> or <acronym>GMT</acronym> the option
|
|
|
+ <code>'fix_dst'</code> will not be used</emphasis> because these two timezones do
|
|
|
+ not work with <acronym>DST</acronym>. When you change the timezone for this instance again to a
|
|
|
+ timezone which is not <acronym>UTC</acronym> or <acronym>GMT</acronym> the previous set 'fix_dst' option will be used
|
|
|
again for date "math".
|
|
|
</para>
|
|
|
</sect3>
|
|
|
@@ -67,19 +74,22 @@
|
|
|
<title>Month Calculations</title>
|
|
|
|
|
|
<para>
|
|
|
- When adding or substracting months from an existing date, the resulting value for the day of
|
|
|
- the month might be unexpected, if the original date fell on a day close to the end of the month.
|
|
|
- For example, when adding one month to January 31st, people familiar with SQL will expect February
|
|
|
- 28th as the result. On the other side, people familiar with Excel and OpenOffice will expect
|
|
|
- March 3rd as the result. The problem only occurs, if the resulting month does not have the day,
|
|
|
- which is set in the original date. For ZF developers, the desired behavior is selectable using
|
|
|
- the <methodname>extend_month</methodname> option to choose either the SQL behaviour, if set to false,
|
|
|
- or the spreadsheet behaviour when set to true. The default behaviour for <methodname>extend_month</methodname>
|
|
|
- is false, providing behavior compatible to SQL. By default, <classname>Zend_Date</classname> computes month
|
|
|
- calculations by truncating dates to the end of the month (if necessary), without wrapping into the
|
|
|
- next month when the original date designates a day of the month exceeding the number of days in
|
|
|
- the resulting month. Use <classname>Zend_Date::setOptions(array('extend_month' => true));</classname>
|
|
|
- to make month calculations work like popular spreadsheet programs.
|
|
|
+ When adding or substracting months from an existing date, the resulting value for
|
|
|
+ the day of the month might be unexpected, if the original date fell on a day close
|
|
|
+ to the end of the month. For example, when adding one month to January 31st, people
|
|
|
+ familiar with <acronym>SQL</acronym> will expect February 28th as the result. On the other side, people
|
|
|
+ familiar with Excel and OpenOffice will expect March 3rd as the result. The problem
|
|
|
+ only occurs, if the resulting month does not have the day, which is set in the
|
|
|
+ original date. For Zend Framework developers, the desired behavior is selectable
|
|
|
+ using the <code>extend_month</code> option to choose either the <acronym>SQL</acronym> behaviour, if
|
|
|
+ set to <constant>FALSE</constant>, or the spreadsheet behaviour when set to <constant>TRUE</constant>. The default behaviour
|
|
|
+ for <code>extend_month</code> is <constant>FALSE</constant>, providing behavior compatible to <acronym>SQL</acronym>. By
|
|
|
+ default, <classname>Zend_Date</classname> computes month calculations by truncating
|
|
|
+ dates to the end of the month (if necessary), without wrapping into the next month
|
|
|
+ when the original date designates a day of the month exceeding the number of days in
|
|
|
+ the resulting month. Use
|
|
|
+ <classname>Zend_Date::setOptions(array('extend_month' => true));</classname> to make
|
|
|
+ month calculations work like popular spreadsheet programs.
|
|
|
</para>
|
|
|
|
|
|
</sect3>
|
|
|
@@ -89,12 +99,13 @@
|
|
|
<title>Speed up Date Localization and Normalization with Zend_Cache</title>
|
|
|
|
|
|
<para>
|
|
|
- You can speed up <classname>Zend_Date</classname> by using an <classname>Zend_Cache</classname> adapter.
|
|
|
- This speeds up all methods of <classname>Zend_Date</classname> when you are using localized data.
|
|
|
- For example all methods which accept <classname>Zend_Date::DATE</classname> and
|
|
|
- <classname>Zend_Date::TIME</classname> constants would benefit from this. To set an <classname>Zend_Cache</classname>
|
|
|
- adapter to <classname>Zend_Date</classname> just use
|
|
|
- <classname>Zend_Date::setOptions(array('cache' => $adapter));</classname>.
|
|
|
+ You can speed up <classname>Zend_Date</classname> by using an
|
|
|
+ <classname>Zend_Cache</classname> adapter. This speeds up all methods of
|
|
|
+ <classname>Zend_Date</classname> when you are using localized data. For example all
|
|
|
+ methods which accept <constant>Zend_Date::DATE</constant> and
|
|
|
+ <constant>Zend_Date::TIME</constant> constants would benefit from this. To set an
|
|
|
+ <classname>Zend_Cache</classname> adapter to <classname>Zend_Date</classname> just
|
|
|
+ use <classname>Zend_Date::setOptions(array('cache' => $adapter));</classname>.
|
|
|
</para>
|
|
|
|
|
|
</sect3>
|
|
|
@@ -108,7 +119,7 @@
|
|
|
is able to handle such problems with the help of <classname>Zend_TimeSync</classname>. You can set a
|
|
|
timeserver with <classname>Zend_Date::setOptions(array('timesync' => $timeserver));</classname> which
|
|
|
will set the offset between the own actual timestamp and the real actual timestamp for all
|
|
|
- instances of Zend_Date. Using this option does not change the timestamp of existing instances.
|
|
|
+ instances of <classname>Zend_Date</classname>. Using this option does not change the timestamp of existing instances.
|
|
|
So best usage is to set it within the bootstrap file.
|
|
|
</para>
|
|
|
|
|
|
@@ -121,40 +132,43 @@
|
|
|
<title>Working with Date Values</title>
|
|
|
|
|
|
<para>
|
|
|
- Once input has been normalized via the creation of a <classname>Zend_Date</classname> object, it will have an
|
|
|
- associated timezone, but an internal representation using standard
|
|
|
- <ulink url="http://en.wikipedia.org/wiki/Unix_Time">UNIX timestamps</ulink>
|
|
|
- . In order for a date to be rendered in a localized manner, a timezone must be known first. The default
|
|
|
- timezone is always GMT/UTC. To examine an object's timezone use <methodname>getTimeZone())</methodname>. To change an
|
|
|
- object's timezone, use <methodname>setTimeZone())</methodname>. All manipulations of these objects are assumed to be
|
|
|
+ Once input has been normalized via the creation of a <classname>Zend_Date</classname>
|
|
|
+ object, it will have an associated timezone, but an internal representation using
|
|
|
+ standard <ulink url="http://en.wikipedia.org/wiki/Unix_Time">UNIX timestamps</ulink>.
|
|
|
+ In order for a date to be rendered in a localized manner, a timezone must be known
|
|
|
+ first. The default timezone is always <acronym>GMT</acronym>/UTC. To examine an object's timezone use
|
|
|
+ <methodname>getTimeZone()</methodname>. To change an object's timezone, use
|
|
|
+ <methodname>setTimeZone()</methodname>. All manipulations of these objects are assumed to be
|
|
|
relative to this timezone.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Beware of mixing and matching operations with date parts between date objects for different timezones, which
|
|
|
- generally produce undesireable results, unless the manipulations are only related to the timestamp.
|
|
|
- Operating on <classname>Zend_Date</classname> objects having different timezones generally works, except as just
|
|
|
- noted, since dates are normalized to UNIX timestamps on instantiation of <classname>Zend_Date</classname>.
|
|
|
+ Beware of mixing and matching operations with date parts between date objects for
|
|
|
+ different timezones, which generally produce undesireable results, unless the
|
|
|
+ manipulations are only related to the timestamp. Operating on
|
|
|
+ <classname>Zend_Date</classname> objects having different timezones generally works,
|
|
|
+ except as just noted, since dates are normalized to UNIX timestamps on instantiation of
|
|
|
+ <classname>Zend_Date</classname>.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Most methods expect a constant selecting the desired <methodname>$part</methodname> of a date, such as
|
|
|
- <classname>Zend_Date::HOUR</classname>. These constants are valid for all of the functions below. A list of all
|
|
|
- available constants is provided in
|
|
|
- <xref linkend="zend.date.constants.list" />
|
|
|
- . If no <methodname>$part</methodname> is specified, then <classname>Zend_Date::TIMESTAMP</classname> is assumed. Alternatively, a
|
|
|
- user-specified format may be used for <methodname>$part</methodname>, using the same underlying mechanism and format
|
|
|
- codes as
|
|
|
- <link linkend="zend.locale.date.normalize"><classname>Zend_Locale_Format::getDate()</classname>
|
|
|
- </link>
|
|
|
- . If a date object is constructed using an obviously invalid date (e.g. a month number greater than 12),
|
|
|
- then <classname>Zend_Date</classname> will throw an exception, unless no specific date format has been selected -i.e.
|
|
|
- <methodname>$part</methodname> is either <constant>NULL</constant> or <classname>Zend_Date::DATES</classname> (a "loose" format).
|
|
|
+ Most methods expect a constant selecting the desired <varname>$part</varname> of a date,
|
|
|
+ such as <constant>Zend_Date::HOUR</constant>. These constants are valid for all of the
|
|
|
+ functions below. A list of all available constants is provided in
|
|
|
+ <xref linkend="zend.date.constants.list" />. If no <varname>$part</varname> is
|
|
|
+ specified, then <constant>Zend_Date::TIMESTAMP</constant> is assumed. Alternatively, a
|
|
|
+ user-specified format may be used for <varname>$part</varname>, using the same
|
|
|
+ underlying mechanism and format codes as <link
|
|
|
+ linkend="zend.locale.date.normalize"><methodname>Zend_Locale_Format::getDate()</methodname></link>.
|
|
|
+ If a date object is constructed using an obviously invalid date (e.g. a month number
|
|
|
+ greater than 12), then <classname>Zend_Date</classname> will throw an exception, unless
|
|
|
+ no specific date format has been selected -i.e. <varname>$part</varname> is either
|
|
|
+ <constant>NULL</constant> or <constant>Zend_Date::DATES</constant> (a "loose" format).
|
|
|
</para>
|
|
|
|
|
|
<example id="zend.date.values.example-1">
|
|
|
<title>User-Specified Input Date Format</title>
|
|
|
- <programlisting language="php"><
benjamin-gonzales