README

Feriados nacionales del Perú y cálculo de plazos en días hábiles para Laravel, como los cuenta la Ley 27444. Sin conectarse a ningún servicio externo.

Requisitos

• PHP 8.2 o superior
• Laravel 12 o 13

Instalación

composer require aeunius/laravel-feriados-peru

El service provider y el facade Feriados se registran solos.

Uso

use Aeunius\FeriadosPeru\Facades\Feriados;

Feriados::esFeriado('2026-07-28');   // true
Feriados::esFeriado('2023-06-07');   // false: el 7 de junio rige desde 2024

Feriados::delAnio(2026);             // Collection de 16 Feriado, en orden

$navidad = Feriados::proximo('2026-12-24');
$navidad->fecha;                     // CarbonImmutable 2026-12-25
$navidad->nombre;                    // 'Navidad'
$navidad->tipo;                      // TipoFeriado::Nacional
$navidad->esMovil();                 // false

Las fechas se aceptan como texto ('2026-07-28') o como cualquier DateTimeInterface. Solo cuenta el día, no la hora, y en la zona horaria de la propia fecha. proximo() devuelve el primer feriado después de la fecha, sin contar la fecha misma.

Días hábiles y plazos

Un día hábil no es feriado ni cae en fin de semana.

Feriados::esDiaHabil('2026-07-28');                       // false

// Notificado el lunes 27 de julio de 2026, un plazo de 5 días hábiles salta
// Fiestas Patrias (28 y 29) y el fin de semana, y termina el 5 de agosto.
Feriados::sumarDiasHabiles('2026-07-27', 5);              // CarbonImmutable 2026-08-05
Feriados::diasHabilesEntre('2026-07-27', '2026-08-05');   // 5
Feriados::esVencido('2026-07-27', 5);                     // ¿hoy ya pasó el 5 de agosto?
Feriados::esVencido('2026-07-27', 5, hoy: '2026-08-05');  // false: el último día aún vale

El cómputo sigue el TUO de la Ley 27444: el plazo en días se cuenta en días hábiles consecutivos (art. 145), a partir del día hábil siguiente a la notificación (art. 144). Por eso:

• sumarDiasHabiles() no cuenta la fecha de partida. Con días negativos cuenta hacia atrás y con 0 devuelve la misma fecha.
• diasHabilesEntre() tampoco cuenta $desde, pero sí $hasta: es la inversa de sumarDiasHabiles(). Si $hasta es anterior, el resultado es negativo.
• esVencido() compara contra hoy, en la zona horaria de la aplicación.

Los días no laborables del sector público también cortan el plazo; ver Días no laborables. Los feriados regionales cortan el plazo si los agregas; ver Ajustar el calendario.

Fin de semana

Por defecto, sábado y domingo no son hábiles. Para una entidad que atiende los sábados, publica la configuración:

php artisan vendor:publish --tag=feriados-peru-config

y deja solo el domingo en config/feriados-peru.php:

'fin_de_semana' => [CarbonInterface::SUNDAY],

Sin Laravel

El motor no necesita la aplicación:

use Aeunius\FeriadosPeru\Support\Calendario;
use Aeunius\FeriadosPeru\Support\Pascua;
use Carbon\CarbonInterface;

Calendario::peru()->esFeriado('2026-04-03');   // true (Viernes Santo)
Calendario::peru(finDeSemana: [CarbonInterface::SUNDAY])
    ->sumarDiasHabiles('2026-09-11', 1);       // sábado 2026-09-12
Pascua::domingo(2026);                         // CarbonImmutable 2026-04-05

Qué feriados incluye

Los del art. 6 del D. Leg. 713 y sus modificaciones: 16 en 2026.

"Desde" es el primer año en que se aplicó el feriado. La Ley 31788 se publicó el 15 de junio de 2023, después del 7 de junio de ese año, así que el primer feriado fue en 2024.

La Pascua se calcula con el algoritmo de Butcher, válido para cualquier año del calendario gregoriano (desde 1583).

Días no laborables

Cada año el Gobierno declara por decreto supremo días no laborables para el sector público, casi siempre para armar feriados largos. No son feriados:

• Solo obligan al sector público, que compensa las horas después. El sector privado trabaja, salvo acuerdo con el empleador.
• Los decretos los declaran hábiles para efectos tributarios.
• Para el procedimiento administrativo, el TUO de la Ley 27444 (art. 145.1) excluye del cómputo los días "no laborables del servicio".

Por eso el paquete los distingue de los feriados:

Feriados::esFeriado('2026-07-27');       // false
Feriados::esNoLaborable('2026-07-27');   // true (D.S. 075-2026-PCM)
Feriados::delAnio(2026);                 // 16 feriados
Feriados::delAnio(2026, conNoLaborables: true);   // 18: suma el 2 ene y el 27 jul

Por defecto, cortan los plazos, como en la Ley 27444. Para un plazo tributario o del sector privado, cuéntalos como hábiles:

Feriados::sumarDiasHabiles('2026-07-24', 1);                                  // 2026-07-30
Feriados::conNoLaborablesInhabiles(false)->sumarDiasHabiles('2026-07-24', 1);  // 2026-07-27

o en toda la aplicación, con 'no_laborables_inhabiles' => false en la configuración.

El paquete trae los de alcance nacional desde 2025:

Agregar los que se declaren después

No hace falta esperar una versión nueva. Publica la configuración y agrégalos en extraordinarios:

'extraordinarios' => [
    ['fecha' => '2026-12-24', 'nombre' => 'Día no laborable', 'tipo' => 'no_laborable', 'norma' => 'D.S. 999-2026-PCM'],
    ['fecha' => '2026-10-15', 'nombre' => 'Feriado por ley', 'tipo' => 'extraordinario'],
],

tipo es no_laborable (sector público, compensable), extraordinario (un feriado para todos, por una sola vez) o regional (un feriado solo donde opera tu aplicación, por una sola vez). Si coincide con un feriado, gana el feriado. Una fecha o un tipo mal escritos lanzan una excepción al arrancar.

Ajustar el calendario

Cada aplicación puede adaptar el catálogo a su realidad desde config/feriados-peru.php, sin esperar una versión nueva.

Feriados regionales o locales

El paquete solo trae los nacionales. Los de tu región o entidad que se repiten cada año van en regionales, y cortan los plazos como los nacionales (el art. 145 de la Ley 27444 también excluye los feriados regionales):

'regionales' => [
    ['mes' => 9, 'dia' => 24, 'nombre' => 'Virgen de las Mercedes'],
    ['mes' => 1, 'dia' => 18, 'nombre' => 'Aniversario de Lima', 'desde' => 2027],
],

Quedan con TipoFeriado::Regional. Para uno de una sola fecha, usa extraordinarios con 'tipo' => 'regional'.

Omitir feriados

Para no considerar un feriado del paquete, ponlo en omitir, por su clave o por una fecha puntual:

'omitir' => [
    'fuerza_aerea',   // en todos los años
    '2026-07-27',     // solo ese día: tu entidad trabajó el no laborable
],

Las claves son anio_nuevo, jueves_santo, viernes_santo, dia_del_trabajo, batalla_de_arica, san_pedro_y_san_pablo, fuerza_aerea, fiestas_patrias_28, fiestas_patrias_29, batalla_de_junin, santa_rosa_de_lima, combate_de_angamos, todos_los_santos, inmaculada_concepcion, batalla_de_ayacucho y navidad. Cada Feriado la trae en $feriado->clave.

Una clave o una fecha mal escritas lanzan una excepción al arrancar, para que un error de tipeo no pase desapercibido.

Sin Laravel, las mismas opciones son argumentos de Calendario::peru():

Calendario::peru(
    regionales: [['mes' => 9, 'dia' => 24, 'nombre' => 'Virgen de las Mercedes']],
    omitir: ['fuerza_aerea'],
);

Desarrollo

Todo corre en Docker con la imagen oficial composer:2, así que no hace falta tener PHP instalado:

make install   # dependencias
make test      # Pest
make analyse   # PHPStan
make lint      # Pint, sin cambiar archivos
make help      # todos los comandos

El CI prueba con Laravel 12 y 13, con PHP 8.2 a 8.5, y también con las versiones mínimas de las dependencias.

Los cambios de cada versión están en el CHANGELOG.

Licencia

MIT. Ver LICENSE.md.