repo_zf1/documentation/manual/fr/module_specs/Zend_Date-Creation.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.date.creation">
    <title>Créer des dates</title>

    <para>
        <classname>Zend_Date</classname> permet de créer des instances d'elle même de
        plusieurs manières différentes. Nous allons voir ceci.
    </para>

    <sect2 id="zend.date.creation.actual">
        <title>Créer la date actuelle</title>

        <para>
            La manière la plus simple de créer la date actuelle est d'utiliser le
            constructeur <code>new Zend_Date()</code> ou encore la méthode statique
            <methodname>Zend_Date::now()</methodname>. Toutes les deux retournent une instance de
            <classname>Zend_Date</classname> avec la date actuelle. Elle est représentée par une
            date calendaire et un temps pour le fuseau horaire actuel du serveur.
        </para>

        <example id="zend.date.creation.actual.example-1">
            <title>Créer une date par instance</title>

            <para>
                Il n'y a pas de paramètres à passer au constructeur pour récupérer un objet
                <classname>Zend_Date</classname>. Certains paramètres sont cependant disponibles et
                nous y reviendrons.
            </para>

            <programlisting language="php"><![CDATA[
$date = new Zend_Date();
]]></programlisting>
        </example>

        <example id="zend.date.creation.actual.example-2">
            <title>Créer une date par méthode statique</title>

            <para>
                La méthode statique <methodname>now()</methodname> a exactement le même effet qu'un
                passage par le constructeur. Cependant la méthode statique, elle, ne peut pas
                prendre de paramètres additionnels.
            </para>

            <programlisting language="php"><![CDATA[
$date = Zend_Date::now();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.date.creation.database">
        <title>Créer une date depuis une base de données</title>

        <para>
            Les bases de données sont souvent utilisées pour stocker des informations de
            dates. Mais elles ont toutes une implémentation et une représentation qui leur est
            propre. MSSQL par exemple manipule les dates de manières significativement différente
            de MySQL, par exemple. Heureusement, <classname>Zend_Date</classname> aide à simplifier
            le processus de création d'une date depuis une base de données.
        </para>

        <para>
            Il est possible de demander au serveur de base de données de formater la date
            dans un certain format. Mais ceci reste en général assez lourd, et doit être pensé à
            chaque fois.
        </para>

        <para>
            Nous avons donc des méthodes très pratiques et rapides dans
            <classname>Zend_Date</classname>, pour récupérer les dates depuis une base de
            données.
        </para>

        <example id="zend.date.creation.database.example-1">
            <title>Création d'une date depuis une base de données</title>

            <para>
                Toutes les bases de données doivent répondre extrêmement rapidement à leurs
                requêtes. Pour stocker une date de manière optimale dans une base, il faut utiliser
                un timestamp. En interne, tous les SGBDs représentent les dates sous forme de
                timestamp (non Unix). Ainsi, leur demander un timestamp sera toujours plus
                performant que de leur demander une date dans un format précis.
            </para>

            <programlisting language="php"><![CDATA[
// SELECT UNIX_TIMESTAMP(my_datetime_column) FROM my_table
$date = new Zend_Date($unixtimestamp, Zend_Date::TIMESTAMP);
]]></programlisting>

        </example>

        <example id="zend.date.creation.database.example-2">
            <title>Création d'une date depuis une base de données dans un format</title>

            <para>
                La sortie de chaque base de données est différente même si elles se
                ressemblent. Cependant elles ont toutes des formats compatibles <constant>ISO</constant>.
                La manière la plus simple de créer une date depuis une base de données est
                d'utiliser <classname>Zend_Date::ISO_8601</classname>. Les SGBDs connus pour être
                conformes pour <classname>Zend_Date::ISO_8601</classname> sont MySQL, MSSQL par
                exemple, mais ils sont tous capables de retourner une représentation
                <constant>ISO8601</constant> d'une donnée date. <constant>ISO8601</constant> possède l'avantage
                d'être lisible et compréhensible par un humain. Son inconvénient est qu'il est
                légèrement plus lourd à traiter qu'un simple timestamp UNIX. En revanche ceux-ci ne
                supportent pas les dates inférieures au 1er Janvier 1970.
            </para>

            <programlisting language="php"><![CDATA[
// SELECT datecolumn FROM my_table
$date = new Zend_Date($datecolumn, Zend_Date::ISO_8601);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.date.creation.array">
        <title>Créer des dates depuis un tableau</title>

        <para>
            Créer une date depuis un tableau est fréquent et pratique. Les clés du tableau
            sont&#160;:
        </para>

        <para>
            <itemizedlist mark="opencircle">
                <listitem>
                        <para><emphasis>day</emphasis>&#160;: jour de la date, un
                        nombre
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>month</emphasis>&#160;: mois de la date, un
                        nombre
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>year</emphasis>&#160;: année complète de la
                        date
                    </para>
                </listitem>

                <listitem>
                    <para><emphasis>hour</emphasis>&#160;: heures de la date</para>
                </listitem>

                <listitem>
                    <para><emphasis>minute</emphasis>&#160;: minutes de la date</para>
                </listitem>

                <listitem>
                    <para><emphasis>second</emphasis>&#160;: secondes de la date</para>
                </listitem>
            </itemizedlist>
        </para>

        <example id="zend.date.creation.array.example">
            <title>Créer une date depuis un tableau</title>

            <para>
                En temps normal on utilisera un tableau avec toutes ses clés. Si une clé est
                absente, la valeur qu'elle représente sera mise à la valeur zéro par défaut. Par
                exemple une tableau ne comportant pas la clé "<code>hour</code>", donnera naissance
                à une date ayant une partie heures à la valeur "<emphasis>0</emphasis>".
            </para>

            <programlisting language="php"><![CDATA[
$datearray = array('year' => 2006,
                   'month' => 4,
                   'day' => 18,
                   'hour' => 12,
                   'minute' => 3,
                   'second' => 10);
$date = new Zend_Date($datearray);
]]></programlisting>

            <programlisting language="php"><![CDATA[
$datearray = array('year' => 2006, 'month' => 4, 'day' => 18);
$date = new Zend_Date($datearray);
]]></programlisting>
        </example>
    </sect2>
</sect1>