DEV Community: chatii

Ask Your Eloquent Model "Is It Due?": Yarunoka's Laravel Bridge Is Out

chatii — Tue, 11 Aug 2026 13:30:11 +0000

In my previous post, I introduced Yarunoka, a language-independent JSON DSL for calendar-aware schedules:

https://dev.to/chatii/schedules-are-rules-not-lists-of-timestamps-introducing-yarunoka-98i

The core idea was: schedules are rules, not lists of timestamps. A rule like "the 25th of every month, moved to the previous business day if needed" should live in the data itself, not be scattered across conditionals in application code.

At the end of that post, I listed a Laravel bridge as one of the next steps. It is now released.

composer require yarunoka/laravel

Packagist: https://packagist.org/packages/yarunoka/laravel
Documentation: https://yarunoka.dev/docs/php/laravel/1.0/

Yarunoka itself actually started inside a personal Laravel application—I extracted the specification and the evaluation engine first, and this bridge brings it back to where it came from.

A schedule as a model attribute

yarunoka/core gives you a parser, a validator, and an evaluator. But in a Laravel application, I do not want to assemble those by hand every time. If I have a Routine model that represents something recurring, I want this:

$routine->schedule

The bridge provides an Eloquent cast that stores a Yrnk Schedule directly in a JSON column:

use Yarunoka\Laravel\Schedule;

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

The schedule column holds plain JSON:

{
  "label": "Recurring process",
  "description": "Runs at 10:00 on business days.",
  "days": ["business_day"],
  "times": ["10:00"]
}

And reading the attribute gives you a Schedule object back. The rule stays as data in the database, readable by humans, editable through a UI, and usable by the application—without turning into code.

Asking "is it due?"

Once the schedule is a model attribute, you can ask the question the whole project is named after (yaru no ka? — "so, do we do it?"):

if ($routine->schedule->isDue(
    now(),
    since: $routine->last_run_at,
)) {
    // do it
}

Note the since argument. A periodic checker rarely wakes up at exactly 10:00:00. If the previous check was at 09:55 and the current one is at 10:05, the 10:00 occurrence happened in between.

So isDue() does not ask "is now the scheduled time?" It asks "was there an occurrence between the last check and now?" That is the question a real application needs answered.

Why core has no `isDue()`

This method only exists in the bridge, and that is intentional.

As I wrote in the previous post, Yarunoka is not a job scheduler. It does not execute anything, and it knows nothing about job state or last successful runs. The core evaluator only offers a pure query:

$evaluator->hasMatchIn($schedule, $since, $at);

"Did this interval contain an occurrence?" What happens after true is the application's business—run a job, send a notification, or do nothing.

isDue() is a thin, application-flavored word on top of hasMatchIn(). Convenient vocabulary belongs in the bridge; the core stays a pure query engine.

The calendar lives in your environment

A Yrnk Schedule can say "days": ["business_day"], but what counts as a business day is a separate concern. In most Laravel applications, that definition is shared across the whole app, not stored per record. So the bridge lets you put the Calendar in config/yarunoka.php:

return [
    'timezone' => 'Asia/Tokyo',
    'calendar' => [
        'holidays' => 'yasumi-Japan',
        'business_holidays' => [
            '2026-08-14',
        ],
        'business_days' => [],
    ],
    'resolvers' => [],
];

With this in place, a stored schedule only needs the rule:

{
  "days": [25],
  "shift": ["prev", "or_same", "business_day"],
  "times": ["10:00"]
}

"What is a business day?" is answered by the environment. If you have Yasumi installed, 'yasumi-Japan' supplies Japanese public holidays.

Date lists can be names

Look at the config again: business_holidays holds a list of dates, but holidays holds a string. Every date-list position in the Calendar accepts either the dates themselves or the name of something that resolves them. yasumi-Japan is one such name.

You can add your own names with Resolvers. This is for date sets that cannot be fixed values:

company holidays managed in the database;
extra business days editable from an admin panel;
holiday data fetched from an external API.

'resolvers' => [
    'company-holidays' => CompanyHolidayResolver::class,
],

Resolvers are built by Laravel's service container, so ordinary dependency injection works:

class CompanyHolidayResolver implements YrnkResolverInterface
{
    public function __construct(
        private CompanyHolidayRepository $repository,
    ) {
    }

    // ...
}

Now company-holidays is usable anywhere the DSL accepts a name—in the config Calendar, or inside schedules stored in the database:

'calendar' => [
    'business_holidays' => 'company-holidays',
],

From the core's point of view, this is just "resolve the date set named company-holidays". Whether that means a database query or an API call is the bridge's problem, not the core's.

Or bind a layer directly

There is a second route. Each Calendar layer—holidays, business holidays, extra business days—can be supplied straight from the container, bypassing the config:

use Yarunoka\Resolvers\YrnkBusinessHolidaysResolverInterface;

$this->app->bind(
    YrnkBusinessHolidaysResolverInterface::class,
    DatabaseBusinessHolidaysResolver::class,
);

A binding takes precedence over the same layer in the config. If the source of your business holidays already exists as an application service, binding it directly is more natural than registering a name in the config. The config describes the environment; the container supplies the implementations.

Validation is real validation

Since schedules are stored as JSON, invalid schedules must not reach the database. The bridge ships a validation rule:

use Yarunoka\Laravel\Rules\ValidYrnkSchedule;

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

This is not a simplified lookalike validator. It loads the input as actual Yarunoka and checks the structure, the values, the Calendar vocabulary, and whether every Resolver name can be resolved. The Eloquent cast validates on save as well, so even a direct assignment cannot sneak a broken schedule into the database.

One Schedule, or Schedules

A small design story. A Yrnk document can hold multiple schedules:

{
  "schedules": [
    { "days": ["mon"], "times": ["10:00"] },
    { "days": ["fri"], "times": ["18:00"] }
  ]
}

Pulled along by that structure, my first version of the Laravel Schedule cast held this whole schedules array. So $routine->schedule—singular—contained multiple schedules inside. I caught it right before release.

What an Eloquent attribute named schedule should hold is, obviously, one schedule. The fact that a Yrnk document can hold many is a separate question from what one model attribute holds. The final design:

'schedule' => Schedule::class,   // one schedule
'schedules' => Schedules::class, // a combination of schedules

There is also a cast for a whole Yrnk Document, for cases where each record should carry its own timezone and Calendar. One column can store a Schedule, a Schedules, or a full Document—whichever unit fits your use case.

Why the bridge is separate

Yarunoka started inside a Laravel application, so I could have released it as a Laravel-only library from day one. But the schedule rules themselves and "how to use them in Laravel" are different things.

yarunoka/core reads Yrnk, writes it, validates it, and answers occurrence queries. yarunoka/laravel adds the config, the container integration, the Eloquent casts, the validation rule, and isDue().

The previous post said Yarunoka is indifferent to execution. In the same way, the core is indifferent to Laravel. You get to use it in a Laravel-native way, without the DSL itself becoming Laravel-specific.

Try it

composer require yarunoka/laravel

The service provider is auto-discovered. To customize the config:

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

Documentation: https://yarunoka.dev/docs/php/laravel/1.0/
Packagist: https://packagist.org/packages/yarunoka/laravel
GitHub: https://github.com/yarunoka-dev
Website: https://yarunoka.dev/

A TypeScript implementation and more are still on the roadmap. Feedback is very welcome.

Schedules Are Rules, Not Lists of Timestamps: Introducing Yarunoka

chatii — Thu, 06 Aug 2026 10:49:20 +0000

How would you represent this schedule as data?

Payday is on the 25th of every month. If the 25th is not a business day, move it to the previous business day.

A plain timestamp cannot express it. A cron expression cannot carry the business-day rule. In many applications, the meaning ends up scattered across conditionals in application code.

I wanted the schedule itself to preserve that meaning.

So I created Yarunoka, a language-independent specification for a small JSON DSL called Yrnk.

Website: https://yarunoka.dev/
GitHub organization: https://github.com/yarunoka-dev

The name comes from the Japanese question やるのか？ (yaru no ka?), roughly meaning:

So, do we do it?

That is also the question the evaluator exists to answer.

A schedule should carry its own meaning

Here is the payday example in Yrnk:

{
  "label": "Payday transfer",
  "description": "At 10:00 on the 25th of every month. If the 25th is not a business day, move it to the previous business day.",
  "days": [25],
  "shift": ["prev", "or_same", "business_day"],
  "times": ["10:00"]
}

Even without reading the implementation, the general meaning is visible in the data.

The exact semantics are defined by the specification, including details that could otherwise be interpreted differently.

label and description are human-facing annotations. They are carried with the schedule, but they never affect evaluation.

Yarunoka is not a job scheduler

Yarunoka does not execute anything.

It only handles two responsibilities:

Describe when occurrences exist.
Answer whether a given instant or interval contains an occurrence.

The caller decides what to do with the answer.

It might:

execute a job;
send a notification;
display an event in a calendar;
start an event in a game;
or do nothing at all.

Yarunoka does not know about queues, retries, catch-up behavior, job state, or the last successful execution. Those are application concerns.

This separation is important. The same schedule document can be used by very different applications without being tied to one execution system.

Why I made it

I have always found the distinction between calendars and to-do lists uncomfortable.

A to-do list usually describes what to do. A calendar describes when something happens. But to me, both are still plans, and deciding whether something belongs in a calendar or a to-do list often feels like unnecessary work.

I was also building a personal AI agent. I wanted the agent to understand my schedules and remember recurring activities.

For that, I did not only want a list of generated dates. I wanted a representation that preserved the rule behind those dates:

every third Monday;
every 90 minutes during business hours;
the last business day of the month;
a collection day that is skipped on public holidays.

In other words, I wanted schedules with meaning.

The document model

A Yrnk document is built from three main concepts:

Calendar: definitions such as holidays, business holidays, extra business days, workweeks, business hours, and named date sets.
Schedule: rules that describe occurrences.
Resolver: a date set supplied by the host application at runtime.

Here is a complete document:

{
  "label": "Internal company schedule",
  "description": "Company schedules evaluated with Japanese public holidays and a company-specific closure date.",
  "version": "1.0",
  "timezone": "Asia/Tokyo",
  "resolvers": ["yasumi-Japan"],
  "calendar": {
    "holidays": "yasumi-Japan",
    "business_holidays": "founding-day",
    "business_days": [],
    "date_sets": {
      "founding-day": ["2026-10-01"]
    }
  },
  "schedules": [
    {
      "label": "Company anniversary",
      "description": "A company-specific all-day closure.",
      "days": ["founding-day"],
      "allday": true
    },
    {
      "label": "Payday transfer",
      "description": "At 10:00 on the 25th of every month. If the 25th is not a business day, move it to the previous business day.",
      "days": [25],
      "shift": ["prev", "or_same", "business_day"],
      "times": ["10:00"]
    }
  ]
}

In this example:

Japanese public holidays are supplied by an external resolver.
founding-day is a company-specific business holiday.
the company anniversary is an all-day occurrence;
payday is normally the 25th at 10:00;
if the 25th is not a business day, payday moves to the previous business day.

The PHP implementation can integrate with Yasumi to provide holiday dates.

More examples

The third Monday of every month at 10:00

{
  "label": "Monthly meeting",
  "description": "Held at 10:00 on the third Monday of every month.",
  "days": [
    ["3rd", "mon"]
  ],
  "times": ["10:00"]
}

Every 90 minutes during business hours on business days

{
  "label": "Periodic business-hours process",
  "description": "Occurs every 90 minutes during configured business hours on business days.",
  "days": ["business_day"],
  "times": {
    "every": [90, "minute"],
    "between": "business_hour"
  }
}

Only on the business day before a break

{
  "label": "Pre-break check",
  "description": "Occurs at 08:00 on a business day when the following day is a business holiday.",
  "days": ["business_day"],
  "if": ["next", "business_holiday"],
  "times": ["08:00"]
}

if filters candidate days without moving them.

The first and third Friday, skipped on public holidays

{
  "label": "Recycling collection",
  "description": "At 07:30 on the first and third Friday of each month, except on public holidays.",
  "days": [
    ["1st", "fri"],
    ["3rd", "fri"]
  ],
  "if": ["not", "holiday"],
  "times": ["07:30"]
}

A matching holiday is removed rather than moved to another date.

Why a DSL?

I wanted a format whose intent could be understood by both humans and generative AI.

A reader should be able to inspect the JSON and understand the broad schedule without first studying an implementation. When the meaning could be ambiguous, the specification defines the exact interpretation.

This also makes workflows such as these possible:

generate Yrnk from natural-language input;
explain a Yrnk document in natural language;
validate schedules in a UI;
store and edit rules without turning them into application code;
implement the same semantics in multiple programming languages.

The DSL describes the meaning. Language implementations provide parsing, validation, and occurrence queries.

The PHP implementation

The first implementation is yarunoka/core.

composer require yarunoka/core

It requires PHP 8.4 or newer and has no runtime dependencies.

A simplified example:

use Yarunoka\YrnkEvaluator;
use Yarunoka\YrnkParser;

$document = (new YrnkParser())->parse($json);
$payday = $document->schedules[0];

$evaluator = YrnkEvaluator::fromYrnk($document);

$matches = $evaluator->matches(
    $payday,
    new DateTimeImmutable('2026-07-24T10:00:00+09:00'),
);

The evaluator can also answer whether an interval contains an occurrence. The result is still only a query result; the application decides what happens next.

Possible use cases

I designed Yarunoka as a general-purpose schedule representation rather than a feature for one specific application.

Possible uses include:

business systems involving holidays and business-day adjustments;
adapters for job execution platforms such as Apache Airflow;
calendar and reminder applications;
recurring routines for AI agents;
time-based events in games;
test data generation and schedule verification.

Some ideas, such as abstract expressions like “the first half of March” or “early in the month,” are not covered by version 1.0 yet.

Current status

The project currently provides:

version 1.0 of the language specification;
JSON Schemas;
a conformance test kit for language implementations;
the PHP implementation;
documentation.

The conformance tests exist so that different language implementations can evaluate the same document with the same meaning.

What comes next

The current plans include:

a Laravel bridge;
a TypeScript implementation;
UI-oriented validation and editing libraries;
a Python implementation;
more abstract calendar vocabulary.

The PHP implementation came first because I am a PHP developer. The specification itself is not tied to PHP.

Conclusion

Schedules are rules, not lists of timestamps.

Yarunoka is an attempt to carry those rules—and their meaning—between humans, generative AI, and applications.

The project is still young, and feedback is very welcome.

Website: https://yarunoka.dev/
GitHub: https://github.com/yarunoka-dev
Original Japanese article: https://zenn.dev/chatii/articles/c4cff5831cd621

My Days at Laravel Live Japan 2026

chatii — Tue, 02 Jun 2026 15:48:53 +0000

Japanese version available on note.

Hi, I'm chatii @chatii.
I recently attended Laravel Live Japan 2026.
Here's what inspired me and what I took home from the conference.

Profile

Organizer of PHP Conference Kagawa
Encountered PHP back in the 4.x era
Freelancer
English level: "Can read reasonably well," "Can write a little," "Can listen a bit," "Cannot speak at all."

5/23 PHP×Tokyo - Laravel Live Japan PRE-PARTY

PHP×Tokyo - Laravel Live Japan PRE-PARTY - connpass

(English follows Japanese) PHP×Tokyoは、PHPやLaravelが好きなエンジニアのためのインターナショナルなミートアップです。日英のライブ翻訳付きなので、英語が得意でなくても大丈夫です！言語の壁を越えて、PHP/Laravelについて語り合いましょう！登壇者も募集中です！登壇を希望する方はこちらからご応募ください。登壇は日本語・英語どちらでも大丈夫です。 #### タイムテーブル * 13:00 - 13:30 受付 & ネットワーキング * 13:30 - 13:40 オープニング * 13:40 - 14:10 "Man...

phpxtky.connpass.com

I first participated in "PHP×Tokyo March 2026." It was my first time attending a meetup with international participants.
I couldn't speak English, but I hoped to be able to communicate somehow.

Back in March, David helped me immensely with translation, which made me feel a bit apologetic...

At the PRE-PARTY, I took the plunge. During the networking session, I managed to approach Victor Ukam, who gave the talk "Manage AI Prompts as Versioned Files in PHP," and said in English, "I have a question...!"

Well... communication after that relied on Google Translate, but I was able to overcome the "first hurdle." You could say I successfully executed <?= "Hello, World" ?>.

Also, it was great to see Ivan again, who came from Russia. I first met him in March, and I was so happy he came over to say hello!

5/25 Eve of the Conference, Gyoza Restaurant

Zumi organized an unofficial pre-party via the laravel-live-jp channel on the "Laravel Japan" Discord.
Participating in these "fringe events" around a conference is always fun. I had booked a hotel from the day before, so I joined in.

The real-time translation app that Albert Chen built was incredibly high-performance...

5/26 Day 1

...Actually, I couldn't sleep at all after the gyoza party. I already suffer from insomnia, and even though I tried my best to sleep, it didn't work.
So, unable to sleep, I was asking Claude for "Quick English phrases for tech conferences" and checking if my pronunciation was understandable using ChatGPT's voice input. Just trying to build some makeshift confidence.

A tech conference with such a glamorous stage felt very fresh. As a conference organizer myself, there were many points I could use for reference.
Furthermore, that real-time translation was a godsend. While I was occasionally concerned about the "Reconnecting..." messages, I thought I'd love to use a translation system like that in Kagawa—one that handles such specialized vocabulary.

Also, the international speakers were so good at "showmanship," smoothly handling live demos while delivering great talks.

After Party

I had one specific goal: to say hello to Matthieu Napoli. He was the catalyst for starting my own meetup, "PHP Lovers Meetup"!

To explain the background, I'm a big fan of Bref (running PHP on AWS Lambda), which he developed. In 2023, I heard on the user Slack that he was "going to visit Japan." After many twists and turns, we held:
"PHP Lovers Meetup vol.0 ~ It starts from <?php"

At that time, I never dreamed I would see him again. Then I saw on Twitter that he was participating in Laravel Live Japan! I just had to tell him, "Thank you for that time..."

And... I did it! I successfully said hello.

// Detect dark theme var iframe = document.getElementById('tweet-2059229348788310420-116'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2059229348788310420&theme=dark" }

(Wait, English...? Well, just a little, maybe the first two sentences... I tried my best, okay?)

Also, at the smoking area, I managed a "multi-turn" conversation in English with someone from Singapore.

Everyone communicated with me in earnest, even someone with my limited English. I'm truly grateful. Just like writing code, I realized the importance of actually speaking it.

5/27 Day 2 and Post-Event

Due to the lack of sleep, I was in "energy-saving mode." I still managed to get a thorough demo of LaraCopilot and see a demo of Sentry.

After the main event, a group of us went to a bar on the 4th floor of the venue, Tachikawa Stage Garden, and later joined @asumikam's group.
We ended up at a HUB and had even more great conversations.
Before I knew it, it was 3 AM. Spending time together until that hour was a precious experience.

Final Thoughts

I want to be able to speak English so bad!

Also, for a while after coming back, my brain was stuck in "English mode" even when speaking Japanese.
Talking to my kids, I sounded like I was speaking broken, machine-translated Japanese. (Maybe other non-native speakers know this feeling!)

Thanks to Generative AI, we don't have to do everything ourselves anymore, but being able to use English "on the fly" still feels essential.
Above all, I just want to communicate more!

And someday, I hope to welcome international participants and speakers to PHP Conference Kagawa.

Hello dev.to. I attended Laravel Live Japan over the past 2 days. I'm starting to write posts (or other outputs) in English because I'm excited about conversation with international developers. But my English is not good. It's my challenge.

chatii — Thu, 28 May 2026 12:59:39 +0000