The online documentation is produced by a web publishing technology created by us to read the documents origins in OpenOffice Writer (ODT) and Microsoft Word (docx) formats and produces native web and PDF versions. In this way we maintain Louder project documentation update and in sync on each of its formats.
El componente Date esta diseñado para extender el lenguaje PHP agregando un tipo de dato para el manejo de fechas de forma orientada a objetos que permita las operaciones entre estas, obtener fragmentos e información de las propiedades del tiempo teniendo en cuenta la configuración de localización requerida por la aplicación.
Porque debe usar este componente
Con Date se pueden efectuar operaciones usando fechas y fragmentos de fechas en cualquier rango de tiempo independientemente de la plataforma utilizada. El uso de las funciones de PHP gmmktime(), mktime(), date(), strftime() y otras tienen restricciones de plataforma y conflictos cuando las fechas están fuera de rango Fri, 13 Dec 1901 20:45:54 GMT a Tue, 19 Jan 2038 03:14:07 GMT.
Las restricciones se deben a que gran parte de las operaciones entre fechas y horas se realizan usando marcas de tiempo que consisten en el número de segundos transcurridos antes ó después del 1 de Enero de 1970, cuando este número es muy grande el tipo de dato float de PHP resulta insuficiente para almacenarlo.
La referencia del manual de PHP dice "The size of a float is platform-dependent, although a maximum of ~1.8e308 with a precision of roughly 14 decimal digits is a common value (that's 64 bit IEEE format).".
Cuando los números de marcas de tiempo a almacenar son muy grandes es posible utilizar extensiones de PHP que soportan precisión arbitraria como lo son bcmath ó gmp.
El componente también soporta los ajustes horarios de acuerdo al timezone de la aplicación y establece las correcciones necesarias para el calendario gregoriano. Igualmente si se trabaja en un entorno localizado Date obtiene los nombres de días y meses de acuerdo al establecido.
Timestamps ilimitados
El componente Date realiza gran parte de sus operaciones basado en las marcas internas de tiempo Unix que se generan apartir de la fecha del objeto y condiciones de zona horaria entre otros. Cuando las aplicaciones requieren soportar operaciones con fechas fuera del rango de Fri, 13 Dec 1901 20:45:54 GMT a Tue, 19 Jan 2038 03:14:07 GMT es necesario que el componente Date realice sus operaciones utilizando matemática de alta precisión mediante el empleo de la extensión de PHP bcmath.
La extensión bcmath proporciona una calculadora binaria que soporta números de precisión arbitraria representandolos como cadenas de caracteres. Cuando la extensión esta disponible se puede activar la integración con el componente Date ejecutando el método del subcomponente de operaciones matemáticas localizadas LocaleMath llamado enableBcMath.
De esta forma se puede usar fechas en cualquier rango y efectuar operaciones sobre ellas con tranquilidad.
Establecer el Timezone
Para un correcto funcionamiento de este componente es necesario establecer la zona horaria donde está ubicada la aplicación y de donde tomará la información para realizar los ajustes adecuados a las fechas y horas.
Kumbia Enterprise Framework permite configurar el timezone en el archivo config/config.ini en la sección [kumbia] usando un CLDR Timezone Identifier que es aceptado por la función date_default_timezone_set() de PHP. Para mayor consistencia de las aplicaciones desarrolladas en el framework se debe usar el método estático Core::setTimeZone(string $cldrIdentifier). Cuando se establece un timezone invalido se genera una excepción.
Ejemplo: Cambiar el timezone activo de forma programacional
// Para establecer el timezone para Bogotá Colombia:
Core::setTimezone("America/Bogota");
// Para establecer el timezone para Londres Inglaterra:
Core::setTimezone("Europe/London");
Para una lista completa de las zonas horarias soportadas visite: http://unicode.org/cldr/data/diff/supplemental/territory_containment_un_m_49.html.
Obtener partes ó fragmentos de fechas
Es posible crear un objeto de fecha instanciando directamente la clase Date, el parámetro que recibe el constructor es una fecha en formato YYYY-MM-DD. Si no se establece este se utiliza la fecha actual. Si el constructor recibe una fecha invalida se genera una excepción DateException.
Ejemplo: Obtener fragmentos de fechas
//Crear Fecha
$fecha = new Date("1986-02-17");
//Obtener el Número del Mes
$fecha->getMonth(); // Devuelve 2
//Obtener el Año
$fecha->getYear(); // Devuelve 1986
//Obtener el Año en formato corto
$fecha->getShortYear(); // Devuelve 86
//Obtener el Número del Día
$fecha->getDay(); // Devuelve 17
//Obtener el timestamp (marca de tiempo UNIX)
$fecha->getTimestamp(); // Devuelve 509000400
//Obtener el nombre del mes abreviado según la localización actual
$fecha->getAbrevMonthName(); // Devuelve Feb
//Obtener el nombre del mes según la localización actual
$fecha->getMonthName(); // Devuelve Febrero
//Obtener el nombre del día según la localización actual
$fecha->getDayOfWeek(); //Devuelve Lunes
//Obtener el nombre del día según la localización actual en forma abreviada
$fecha->getAbrevDayOfWeek(); //Devuelve Lun
//Obtener el número del dia de la semana (Domingo=0 hasta Sábado=7)
$fecha->getDayNumberOfWeek(); // Devuelve 1
//Obtener la fecha interna en el formato YYYY-MM-DD
$fecha->getDate(); // Devuelve 1986-02-17
(string) $fecha; // Devuelve 1986-02-17
//Obtener la fecha de acuerdo a un formato establecido
$fecha->getUsingFormat("yy.dd.mm"); // Devuelve 86.17.02
//Obtener la fecha de acuerdo al formato de fecha en config.ini
$fecha->getUsingDefaultFormat();
//Obtener el periodo de la fecha (YYYYMM)
$fecha->getPeriod(); // Devuelve 198602
//Obtener la fecha en formato ISO-8601
$fecha->getISO8601Date(); // Devuelve 1986-02-17T00:00:00-05:00
//Obtener la fecha en formato RFC-2822
$fecha->getRFC2822Date(); // Devuelve Mon, 17 Feb 1986 00:00:00 -0500
Posición en el Tiempo
Un objeto Date también puede proporcionar información sobre su posición en el tiempo, las funciones que reciben otras fechas aceptan strings en el formato YYYY-MM-DD ó otros objetos de fechas:
Ejemplos: Uso de métodos de posición del tiempo con Date
//Indica si la fecha corresponde a la actual
$fecha->isToday();
//Indica si la fecha corresponde a la fecha de mañana
$fecha->isTomorrow();
//Indica si la fecha corresponde a la fecha de ayer
$fecha->isYesterday();
//Indica si la fecha se encuentra en el mes actual
$fecha->isThisMonth();
//Indica si la fecha se encuentra en el año actual
$fecha->isThisYear();
//Indica si el año de la fecha es bisiesto
$fecha->isLeapYear();
//Si la fecha está entre un rango
$fecha = new Date("1990-06-04");
$fecha->isBetween("1980-01-01", "2000-12-31") // Devuelve true
//Si la fecha NO está entre un rango
$fecha = new Date("1990-06-04");
$fecha->isNotBetween("1980-01-01", "2000-12-31") // Devuelve false
//Indica si está en el pasado
$fecha->isPast();
//Indica si está en el futuro
$fecha->isFuture();
//Indica si una fecha es menor que la otra
Date::isEarlier("2001-02-30", "2003-04-21") // Devuelve true
//Indica si una fecha es mayor que la otra
Date::isLater("2001-02-30", "2003-04-21") // Devuelve false
//Indica si una fecha es igual a la otra
Date::isEquals("2001-02-30", "2003-04-21") // Devuelve false
// Compara dos fechas, si la primera es menor a la segunda devuelve -1, si son // iguales devuelve 0 y si la primera es mayor a la segunda devuelve 1
Date::compareDates("2009-01-20", "2009-02-14"); // Devuelve -1
Date::compareDates("2009-01-20", "2009-01-20"); // Devuelve 0
Date::compareDates("2009-03-05", "2009-02-14"); // Devuelve 1
Información de Fechas
El componente Date ofrece métodos para obtener la fecha y hora actual, así como fechas iniciales y finales de años y meses:
Ejemplo: Métodos para obtener información de fechas
// Obtiene el rango de fechas de la semana de Lunes a Domingo donde está
// ubicada la fecha
$fecha = new Date("2009-02-11");
print_r($fecha->getWeekRange()); //Array ([0] => 2009-02-09 [1] => 2009-02-15)
//Obtener la fecha actual en formato YYYY-MM-DD
Date::getCurrentDate();
//Obtener la hora actual en formato HH:MM:SS
Date::getCurrentTime();
//Obtener la fecha y hora actual en formato "YYYY-MM-DD HH:MM:SS"
Date::now();
//Obtener el primer dia del año actual
Date::getFirstDayOfYear();
//Obtener el primer dia del año 1999
Date::getFirstDayOfYear(1999); //Devuelve 1999-12-31
//Obtener el último dia habil del año 2006
echo Date::getLastNonWeekendDayOfYear(2006); //2006-12-29
//Obtener el primer dia del año 1980
Date::getFirstDayOfYear(1980); //Devuelve 1980-01-01
//Obtener el primer dia del mes de febrero del año 1980
Date::getFirstDayOfMonth(2, 1980); //Devuelve 1980-02-01
//Obtener el último dia del mes de febrero del año actual
Date::getLastDayOfMonth(2);
//Obtener el último dia del mes de febrero del año 2000
Date::getLastDayOfMonth(2, 2000); //Devuelve 2000-02-29
//Obtener el último dia habil del mes de julio del año 1983
echo Date::getLastNonWeekendDayOfMonth(7, 1997); //1983-07-29
Cambiar fragmentos de la fecha
Cada objeto de fecha almacena cada parte de la fecha y permite cambiar cada parte manteniendo la consistencia de la misma:
Ejemplo: Métodos para manipular fragmentos de fechas
$fecha = new Date("2008-11-30");
//Cambiar el mes a Marzo
$fecha->setMonth(3);
echo $fecha; //Devuelve 2008-03-30
//Cambiar el mes a Febrero (se ajusta el día automáticamente)
$fecha->setMonth(2);
echo $fecha; // Devuelve 2008-02-29
//Cambiar el año de un año bisiesto a uno no bisiesto
$fecha->setYear("2009");
echo $fecha; // Devuelve 2009-02-28
//Cambiar el dia de la fecha
$fecha->setDay(30);
echo $fecha; // Devuelve 2009-02-28
$fecha->setDay(12);
echo $fecha; // Devuelve 2009-02-12
//Cuando el mes es mayor a 12 ajusta al año ó años siguientes
$fecha = new Date("2008-01-01");
$fecha->setMonth(13);
echo $fecha; //2009-01-01
$fecha = new Date("2009-01-30");
$fecha->setMonth(14);
echo $fecha; //2009-02-28
$fecha = new Date("2008-01-30");
$fecha->setMonth(-2);
echo $fecha; //2007-11-30
$fecha = new Date("2008-02-29");
$fecha->setMonth(-14);
echo $fecha; //2007-11-30
Operaciones con fechas
Las operaciones con fechas se dividen en las que modifican la fecha interna del objeto y las que devuelven nuevos valores:
Ejemplo: Realizar operaciones con fechas
//Agregar meses a la fecha
$fecha = new Date("2008-08-10");
$fecha->addMonths(2);
echo $fecha; //2008-10-10
//Quitar meses a la fecha
$fecha = new Date("2008-01-10");
$fecha->diffMonths(3);
echo $fecha; //2008-10-10
//Agregar dias
$fecha = new Date("2008-02-29");
$fecha->addDays(5);
echo $fecha; //2008-03-05
//Quitar dias
$fecha = new Date("2008-01-02");
$fecha->diffDays(5);
echo $fecha; //2007-12-28
//Agregar años
$fecha = new Date("2008-01-02");
$fecha->addYears(3);
echo $fecha; //2011-01-02
//Quitar años
$fecha = new Date("2008-01-02");
$fecha->diffYears(3);
echo $fecha; //2005-01-02
// Restar una fecha y devolver dias de diferencia, la fecha interna no se
// modifica
$fecha = new Date("2008-01-02");
echo $fecha->diffDate("2008-01-10"); //Devuelve -8
$fecha = new Date("2008-01-30");
echo $fecha->diffDate("2008-01-25"); //Devuelve 5
El método addInterval y diffInterval realiza sumas y restas de intervalos respectivamente a otras fechas, la función siempre suma ó resta por lo cual pasar números negativos como segundo parámetro genera el mismo resultado.
Las operaciones tienen en cuenta años bisiestos, correcciones gregorianas, zonas horarias y rangos de fecha de cualquier longitud.
Tabla: Tipos de intervalos soportados por Date::addInterval
Constante
Descripción
INTERVAL_DAY
Establece un intervalo de días del calendario gregoriano
INTERVAL_WEEK
Establece un intervalo de semanas
INTERVAL_MONTH
Establece un intervalo de meses del calendario gregoriano
INTERVAL_YEAR
Establece un intervalo de años del calendario gregoriano
Ejemplo: Uso de addInterval para sumar intervalos a fechas
//Devuelve un objeto de fecha apartir de sumarle un intervalo a otra fecha
Date::addInterval("1980-05-11", 10, Date::INTERVAL_DAY); //1980-05-21
Date::addInterval("1981-02-27", 7, Date::INTERVAL_DAY); //1980-03-06
Date::addInterval("1980-05-11", 2, Date::INTERVAL_MONTH); //1980-07-11
Date::addInterval("1980-05-11", 5, Date::INTERVAL_YEAR); //1985-05-21
//Devuelve un objeto de fecha apartir de sumarle un intervalo a otra fecha
Date::diffInterval("1980-05-11", 10, Date::INTERVAL_DAY); //1980-05-01
Localización de Fechas
Por defecto los nombres de meses, dias, eras y formatos de fechas son devueltos usando la localización de la aplicación en config.ini. Es posible modificar la localización de un objeto fecha usando el método setLocale() que acepta un objeto Locale:
Ejemplo: Cambiar la localización de los objetos de fecha
<?php
$date = new Date('1986-02-02');
//Fecha en Inglés
$date->setLocale(new Locale('en_US'));
echo $date->getLocaleDate();
//Fecha en Francés
$date->setLocale(new Locale('fr_FR'));
echo $date->getLocaleDate();
//Fecha en Español
$date->setLocale(new Locale('es_AR'));
echo $date->getLocaleDate();
//Fecha en Chino
$date->setLocale(new Locale('zh_CN'));
echo $date->getLocaleDate();
Lo anterior genera la siguiente salida:
Sunday, February 2, 1986
Dimanche 2 Février 1986
Domingo 2 de Febrero de 1986
1986年2月2日星期日
El método getLocaleDate obtiene una fecha apta por la cultura establecida usando diferentes tipos de formatos. El método acepta un parámetro indicando el tipo de formato de fecha a obtener:
Tabla: Tipos de formatos localizados que soporta Date
Tipo Formato
Descripción
full
Obtiene una fecha apta para la localización en formato completo ó extendido. Es el formato predeterminado del método getLocaleDate().
long
Formato largo pero mas corto que 'full'.
medium
Formato de fecha medio, útil en reportes ó listados.
short
Formato de fecha corto.
El siguiente ejemplo ilustra las fechas obtenidas de acuerdo a cada tipo de formato localizado. Las variaciones incluso de paises de la misma lengua son tenidas en cuenta:
Ejemplo: Obtener fechas en formatos localizados de acuerdo a la cultura
<?php
$date = new Date('1985-11-01');
//Tipos de formatos en español de Mexico
$date->setLocale(new Locale('es_MX'));
echo $date->getLocaleDate('full');
echo $date->getLocaleDate('long');
echo $date->getLocaleDate('medium');
echo $date->getLocaleDate('short');
//Tipos de formatos en español de Colombia
$date->setLocale(new Locale('es_CO'));
echo $date->getLocaleDate('full');
echo $date->getLocaleDate('long');
echo $date->getLocaleDate('medium');
echo $date->getLocaleDate('short');
Generando la siguiente salida:
Viernes 1 de Noviembre de 1985
1 de Noviembre de 1985
01/11/1985
01/11/85
Viernes 1 de Noviembre de 1985
1 de Noviembre de 1985
1/11/1985
1/11/85
Establecer el formato de la fecha
Los formatos de fecha devueltos por getLocaleDate representan el estándar internacional de acuerdo a la Unicode para cada localización (idioma y territorio). Además de estos es posible obtener una fecha en un formato personalizado usando el método getUsingFormat(). Los formatos son aplicados por el componente y se evita el uso de funciones PHP como date ó strftime de esta forma puede que algunos formatos disponibles en ellas no se encuentren presentes.
Los modificadores de tipos de formato aceptados por este son los siguientes:
Tabla: Tipos de modificadores de formatos de fecha aceptados por Date::getUsingFormat
Tipo Modificador
Descripción
GGGG
Nombre de la era de la fecha. Antes de cristo ó después de cristo según la localización.
GGGGGG
Nombre abreviado de la era. a.c. y d.c.
yy
Año abreviado. El año 1997 sería 97.
yyyyy
Año completo.
dd
Dia del mes usando un cero al inicio cuando el dia es menor a 10.
d
Dia del mes.
EEEE
Nombre del día de la semana.
EEE
Nombre del día de la semana abreviado.
MMMM
Nombre del mes.
MMM
Nombre del mes abreviado.
MM
Numero del mes usando un cero al inicio cuando es menor a 10.
M
Número del mes.
r
Fecha en formato RFC-2822
c
Fecha ISO 8601
z
Día del año.
o
Número del año ISO-8601.
L
Muestra un 1 cuando es año biciesto y cero de lo contrario.
W
Número de la semana en el año.
N
Representación númerica de la fecha
t
Timestamp Unix
e
Identicador de Zona Horaria
Un ejemplo de uso de los modificadores de formato es:
Ejemplo: Obtener la fecha con un formato personalizado y una localización establecidad
$d = new Date('1999-10-18');
$d->setLocale(new Locale('en_US'));
echo $d->getUsingFormat('yyyy.MM.dd, DD EEEE r MMMM L c t');
Obtener la fecha y hora mundial
Cuando se desarrollan aplicaciones que serán implementadas en diferentes paises y/o continentes y el servidor de aplicaciones reside en un punto central el componente Date proporciona datos de fecha y hora que permiten lograr esto apartir de la zona horaria.
La información de zona horaria depende de la plataforma en la que está instalada la aplicación y de la versión de PHP, puede instalar una versión actualizada de la extensión php_timezone disponible en PECL para obtener los últimos datos de zona horaria.
Ejemplo: Obtener la fecha actual simultaneamente de acuerdo a diferentes zonas horarias
