date_format()

date_format()

Introducción

Las fechas y horas están en todas partes en las aplicaciones reales: marcas de tiempo en publicaciones de blog, fechas de pedidos en una tienda en línea, entradas de registro, eventos de calendario. PHP almacena estos momentos internamente de una forma que no es legible para las personas, por lo que necesitas una manera de convertir un objeto de fecha en una cadena que alguien pueda leer — "2023-03-03", "Friday, March 3rd" o "03/03/2023 1:00 PM". Eso es exactamente lo que hace date_format().

Este capítulo cubre qué es date_format(), su sintaxis, los caracteres de formato más útiles y los problemas comunes relacionados con zonas horarias e inmutabilidad.

¿Qué es la función date_format()?

La función date_format() da formato a un objeto DateTime como una cadena según un patrón que tú proporcionas. Es un alias procedural del método orientado a objetos DateTime::format() — ambos producen resultados idénticos, así que usa el estilo que mejor se adapte a tu base de código:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

// These two lines are equivalent
echo date_format($date, 'Y-m-d');   // procedural
echo $date->format('Y-m-d');        // object-oriented

Sintaxis

date_format(DateTimeInterface $object, string $format): string

• $object — una instancia de DateTime (o DateTimeImmutable). Esta es la fecha que deseas representar.
• $format — una cadena construida con caracteres de formato (como Y, m, d). Cualquier carácter que no sea un carácter de formato se imprime de forma literal.
• Valor de retorno — la fecha formateada como una cadena.

Cómo usar la función date_format()

Primero crea un objeto de fecha con la clase DateTime, que está integrada en PHP:

<?php

$date = new DateTime('2023-03-03');

Esto crea una fecha establecida en el 3 de marzo de 2023 a medianoche. Por defecto, DateTime usa la zona horaria configurada en el servidor, lo que significa que el mismo código puede producir resultados distintos en diferentes máquinas. Para obtener resultados predecibles, establece siempre la zona horaria de forma explícita:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

Ahora dale el formato que quieras:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'Y-m-d');
// Output: 2023-03-03

Para aplicaciones PHP modernas, prefiere DateTimeImmutable sobre DateTime. Métodos como modify() mutan un DateTime en su lugar, lo cual es una fuente común de errores cuando el objeto se pasa entre funciones; DateTimeImmutable devuelve un nuevo objeto en su lugar y funciona con date_format() exactamente de la misma manera:

<?php

$date = new DateTimeImmutable('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'd/m/Y');
// Output: 03/03/2023

Formatos de fecha comunes

Hay muchas formas diferentes de dar formato a fechas usando la función date_format(). Estos son algunos de los formatos más comunes:

• Y-m-d: La fecha en formato YYYY-MM-DD.
• d/m/Y: La fecha en formato DD/MM/YYYY.
• m/d/Y: La fecha en formato MM/DD/YYYY.
• H:i:s: La hora en formato de 24 horas (p. ej., 13:00:00).
• h:i:s a: La hora en formato de 12 horas (p. ej., 01:00:00 am).

Caracteres de formato

Además de los formatos comunes anteriores, puedes construir tu propio patrón a partir de caracteres de formato individuales. Estos son los que usarás con más frecuencia:

• Y: El año en cuatro dígitos (p. ej., 2023).
• y: El año en dos dígitos (p. ej., 23).
• m: El mes como número de dos dígitos (p. ej., 03).
• M: El nombre abreviado del mes (p. ej., Mar).
• F: El nombre completo del mes (p. ej., March).
• d: El día del mes como número de dos dígitos (p. ej., 03).
• D: El nombre abreviado del día (p. ej., Fri).
• l: El nombre completo del día (p. ej., Friday).
• j: El día del mes sin ceros iniciales (p. ej., 3).
• S: Sufijo ordinal en inglés para el día del mes (p. ej., st, nd, rd, th).
• H: La hora en formato de 24 horas (p. ej., 13).
• h: La hora en formato de 12 horas (p. ej., 01).
• i: Los minutos como número de dos dígitos (p. ej., 05).
• s: Los segundos como número de dos dígitos (p. ej., 30).
• a: am o pm.

Para la lista completa de todos los caracteres admitidos, consulta PHP date and time y el capítulo date() — date_format() usa los mismos caracteres.

Aquí tienes un ejemplo de un formato de fecha personalizado:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'l, F jS Y, h:i:s a');
// Output: Friday, March 3rd 2023, 12:00:00 am

Para imprimir un carácter de formato de forma literal en lugar de que sea interpretado, escápalo con una barra diagonal inversa:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, '\T\o\d\a\y \i\s l');
// Output: Today is Friday

date_format() vs date()

Ambas funciones dan formato a fechas, pero toman entradas diferentes:

• date() trabaja con una marca de tiempo Unix (un número entero) y tiene como valor predeterminado "ahora". Úsala para un formato rápido sin dependencia de zona horaria: date('Y-m-d').
• date_format() trabaja con un objeto DateTime, por lo que lleva su propia zona horaria y admite aritmética (añadir días, calcular diferencias) antes de dar formato. Úsala cuando necesites manipular la fecha.

Si tienes una cadena como "3 March 2023", primero construye un DateTime — date_create_from_format() y strtotime() son los puntos de entrada habituales.

Conclusión

La función date_format() en PHP proporciona una forma sencilla de dar formato a un objeto DateTime como una cadena legible. Al comprender los caracteres de formato disponibles y las buenas prácticas — establecer la zona horaria de forma explícita y preferir DateTimeImmutable — puedes garantizar una salida de fechas precisa y predecible en todos los entornos donde se ejecute tu código.

Práctica