Genai Laravel Laravel Package

Getting Started

Install the package and publish its migrations, then run php artisan migrate before touching any MCP tooling — the scheduler is the foundation everything else sits on.

composer require <vendor>/<package>
php artisan vendor:publish --tag=<package>-migrations
php artisan migrate

First things to look at:

1. The published migration(s) — specifically the requests and deliveries tables (available_at) and the claim-receipt table (expires_at). On v0.2.6+ these are required DATETIME columns; if you're coming from an earlier install you'll see a dedicated forward migration converting them.
2. The MCP tool/resource registration — where the package exposes scheduling operations to your MCP server. This is the entry point for actually using the scheduler.
3. The config file — look for claim TTLs, delivery retry windows, and any queue/connection bindings.

First meaningful use case: register the scheduling tools in your MCP server, then schedule a request with a future available_at and confirm a client can claim it once that instant passes. That single round trip exercises the requests table, the claim-receipt table, and the expires_at lifecycle — the three things v0.2.6 hardens.

Implementation Patterns

Treat scheduling instants as the source of truth. The package's model is: a request/delivery has an available_at, and a claim receipt has an expires_at. Your code should always compare against these columns rather than wall-clock now() scattered through queries, otherwise you defeat the point of the recent DATETIME normalization.

Migration-first upgrades. Any time you bump this package, run php artisan migrate before deploying application code that assumes the new schema. v0.2.6's forward migration converts available_at / expires_at to required DATETIME; skipping it leaves you on the old implicit-TIMESTAMP behaviour that silently rewrites your schedule.

Claim → deliver → release lifecycle. Wrap claim operations so that a failed delivery path still releases or expires the claim receipt. Because expires_at is now a plain DATETIME the package no longer gets free "auto-touch" semantics from the database — your application is responsible for renewing and expiring claims explicitly.

Testing pattern. Include a MariaDB lane in CI alongside SQLite/MySQL. The v0.2.6 fix exists precisely because MariaDB's first-TIMESTAMP auto-update rule only bites on MariaDB — SQLite-based test suites will never catch a regression here. The upstream project validates against MariaDB 10.6 and 11.4; mirror at least one of those.

Integrating with your own jobs. When a scheduled delivery fires, hand off to your queue with the package's request ID as a correlation key, and write the outcome back to the deliveries table so claim/lifecycle state stays consistent.

Gotchas and Tips

The headliner gotcha — MariaDB's implicit TIMESTAMP rule. Before v0.2.6, if available_at or expires_at happened to be the first TIMESTAMP column in the table, MariaDB would silently auto-update it on every unrelated UPDATE. That meant a bookkeeping write (e.g. bumping a updated_at or a status column) could quietly move a scheduled instant. v0.2.6 converts these to DATETIME to remove the behaviour. The upgrade fixes the future — it does not repair already-corrupted values. If you've been running an older version on MariaDB, audit rows with suspiciously recent or clustered available_at/expires_at values before assuming the schedule is intact.

Run migrations after upgrading — this is not optional. The release explicitly calls out that existing installs must run package migrations. The migration is additive/forward-only, converting column types in place without changing stored values.

Rollback keeps the corrected types. If you roll back the package, the migration deliberately does not restore the old automatic-TIMESTAMP behaviour. Don't expect a rollback to re-introduce the bug — that's by design, and it means a rollback won't help you "reproduce" pre-upgrade state for debugging.

Debugging scheduling drift. If requests aren't becoming available when expected, check the column definition first (SHOW CREATE TABLE), not the application logic. If you still see TIMESTAMP ... ON UPDATE CURRENT_TIMESTAMP, the forward migration hasn't run or didn't apply cleanly.

Extension point. The cleanest place to add behaviour (metrics, audit logging, custom claim policies) is around the claim/release operations rather than inside the schema. The package's columns are intentionally minimal; keep your extensions in application-level observers or decorated services so future package migrations stay low-risk.

Verification before you trust it in prod. Replicate the upstream's validation shape: run your migration test suite against a real MariaDB instance (10.6 or 11.4), not just a mocked connection. The whole class of bug this release addresses is invisible to mocked databases.