yarunoka/laravel

Laravel integration for the Yarunoka schedule definition DSL

0.6.0 2026-08-09 23:51 UTC

Requires

• php: ^8.4
• illuminate/container: ^13.0
• illuminate/contracts: ^13.0
• illuminate/database: ^13.0
• illuminate/support: ^13.0
• yarunoka/core: ^1.2

Requires (Dev)

• azuyalabs/yasumi: ^2.11
• bamarni/composer-bin-plugin: ^1.8
• orchestra/testbench: ^11.1
• phpunit/phpunit: ^13.0

Suggests

• azuyalabs/yasumi: Answer the yasumi-{Provider} resolver names with computed public holidays

MIT

• DSL
• validation
• schedule
• calendar
• laravel
• eloquent
• scheduling

Published on Packagist.org on 2026-08-09 23:52 UTC

README

Laravel integration for the Yarunoka schedule definition DSL.

What is this?

Yarunoka is a small JSON DSL — Yrnk — that states calendar rules like "payday is the 25th, moved up to the previous business day" as data, plus a pure engine that answers questions about them. The DSL and the engine live in yarunoka/core; the language-independent specification lives in the spec repository.

This package binds that engine into Laravel:

• A service provider builds the evaluation environment (timezone, calendar, resolvers) from config/yarunoka.php and binds YrnkEvaluator / YrnkParser into the container — scoped per request, and yielding to any binding the application makes itself.
• Eloquent casts store schedules in JSON columns with validation on both paths: a schedule column comes back as a Schedule wrapper with the firing decision (isDue), a schedules-part column as Schedules (a list of Schedule composed with any), and a whole-document column as a bare Yrnk.
• Validation rules (ValidYrnk, ValidYrnkSchedule, ValidYrnkSchedules) reject a bad request with the engine's own message on the validation error.
• Container-made resolvers: a name in the config maps to a class the Laravel container instantiates on first use, so constructor injection works; binding one of the core's layer interfaces wins over the config.

Warning

The 0.x releases exist to exercise the release pipeline. They are not intended for use. This notice will be removed at 1.0.0.

Installation

composer require yarunoka/laravel

Requires PHP 8.4 or newer and Laravel 13. The service provider is registered by package auto-discovery. To publish the config:

php artisan vendor:publish --tag=yarunoka-config

Quick example

Name the wall-clock timezone and the calendar once, in the config:

// config/yarunoka.php
return [
    'timezone' => 'Asia/Tokyo',
    'calendar' => [
        'holidays' => 'yasumi-Japan', // resolved automatically when azuyalabs/yasumi is installed
        'business_holidays' => ['2026-08-14'],
        'business_days' => [],
    ],
    'resolvers' => [],
];

Cast a JSON column to one schedule by naming the wrapper in casts() (Schedules::class casts a column of many the same way):

use Yarunoka\Laravel\Schedule;

class Routine extends Model
{
    protected function casts(): array
    {
        return ['schedule' => Schedule::class];
    }
}

Validate a request and store the schedule as it was spelled — an invalid schedule never reaches the database:

use Yarunoka\Laravel\Rules\ValidYrnkSchedule;

$validated = $request->validate([
    'schedule' => ['required', new ValidYrnkSchedule()],
]);

$routine = Routine::create(['schedule' => $validated['schedule']]);

Ask the firing question from a poller — was there a scheduled point since the last run?

if ($routine->schedule->isDue(now(), since: $routine->last_run_at)) {
    // fire, then advance last_run_at
}

Documentation

• yarunoka/core — the DSL and the engine this package wraps, with guides on reading, writing, and evaluating documents
• The spec repository — the DSL specification

License

MIT