mktime()

La función mktime() de PHP construye un timestamp Unix a partir de partes individuales de fecha y hora — hora, minuto, segundo, mes, día y año. Es la inversa de date(): mientras que date() convierte un timestamp en una cadena con formato, mktime() convierte las partes de una fecha en un timestamp que puedes almacenar, comparar o usar en cálculos aritméticos.

Este capítulo cubre el orden de los argumentos (que confunde a casi todo el mundo), cómo mktime() normaliza automáticamente los valores fuera de rango, su comportamiento con las zonas horarias y cuándo es mejor usar las clases DateTime en su lugar.

Sintaxis

mktime(
    int $hour = (current hour),
    ?int $minute = (current minute),
    ?int $second = (current second),
    ?int $month  = (current month),
    ?int $day    = (current day),
    ?int $year   = (current year)
): int|false

El primer argumento, $hour, es obligatorio desde PHP 8.0 — llamar a mktime() sin argumentos lanza un ArgumentCountError. Cualquier argumento que se omita toma como valor predeterminado la parte correspondiente de la fecha y hora local actuales. La función devuelve el timestamp como un entero, o false si los argumentos producen una fecha fuera del rango válido.

Un timestamp Unix es el número de segundos transcurridos desde la época Unix — 1 de enero de 1970, 00:00:00 UTC. Es la unidad común para las fechas en PHP, bases de datos y sistemas operativos.

Atención al orden de los argumentos. mktime() recibe el tiempo antes que la fecha: hora, minuto, segundo, mes, día, año. Esto es distinto de cómo solemos escribir las fechas (año-mes-día), por lo que es la fuente más frecuente de errores.

Construir un timestamp específico

Para representar un momento concreto, pasa las seis partes. Aquí construimos las 2:30 PM del 15 de junio de 2024:

Establecemos la zona horaria explícitamente para que la salida sea reproducible. Sin date_default_timezone_set(), mktime() interpreta las partes en la zona horaria configurada en el servidor, lo que puede desplazar el timestamp resultante.

Aritmética de fechas con mktime()

Como un timestamp es simplemente un número de segundos, puedes sumar o restar segundos para avanzar o retroceder una fecha. Para encontrar la fecha 30 días después de un día dado, añade 30 × 86400 segundos (hay 86.400 segundos en un día):

Añadir 30 días a una fecha

Este enfoque de segundos brutos funciona bien para días enteros, pero ignora las transiciones de horario de verano: un "día" no siempre son exactamente 86.400 segundos. Para una aritmética de calendario correcta en límites de cambio de hora, usa DateTime::modify() o DateInterval en su lugar.

Normalización automática

Una característica útil de mktime() es que normaliza los valores fuera de rango: los ajusta a la fecha correcta en lugar de fallar. Si pasas el mes 13 obtienes enero del año siguiente; si pasas el día 0 obtienes el último día del mes anterior:

Esto hace que mktime() sea conveniente para cálculos del tipo "último día de este mes": mktime(0, 0, 0, $month + 1, 0, $year) devuelve el último día de $month. Ten en cuenta que esta permisividad también significa que mktime() no rechazará una fecha claramente inválida como el 30 de febrero — simplemente la ajustará. Si necesitas validar una fecha del calendario, usa checkdate() primero.

Errores frecuentes

• Orden de argumentos incorrecto. Escribir mktime(2024, 6, 15) pensando que es año-mes-día produce una fecha sin sentido. Recuerda: primero el tiempo, luego mes, día, año.
• Sin argumentos en PHP 8. mktime() sin argumentos lanza ArgumentCountError. Para obtener el timestamp actual, usa time() en su lugar.
• Años de dos dígitos. Pasa siempre un año completo de cuatro dígitos. Valores como 0–69 se mapean a 2000–2069 y 70–100 a 1970–2000, lo cual raramente es lo que se desea.

mktime() vs. las clases DateTime

mktime() es procedimental y trabaja en la zona horaria local. Para partes en UTC, usa su función hermana gmmktime(). Para código nuevo, prefiere las clases orientadas a objetos DateTime y DateTimeImmutable — estas llevan información de zona horaria, gestionan la aritmética con horario de verano y evitan el cálculo manual de segundos:

Conclusión

mktime() construye un timestamp Unix a partir de partes de fecha y hora, normalizando automáticamente los valores fuera de rango — lo que lo hace útil para aritmética de fechas rápida y trucos del tipo "último día del mes". Ten en cuenta sus peculiaridades: el tiempo va antes que la fecha en la lista de argumentos, y una llamada sin argumentos ahora genera un error (usa time() para "ahora"). Para trabajar con zonas horarias y horario de verano en PHP moderno, usa DateTimeImmutable y DateInterval. Consulta también checkdate() para validación y strtotime() para analizar cadenas de fecha en formato legible.

Práctica