Download the PHP package hibernator/hibernator-phplib without Composer

Hibernator 💤

Write PHP code that sleeps for months, survives server crashes, and wakes up exactly where it left off.

Hibernator is a Durable Execution Engine for PHP 8.2+. It eliminates the complexity of queues, cron jobs, and state machines by allowing you to write long-running business processes as simple, linear code.

🌟 The Problem: "Cron & Queue Spaghetti"

Modern applications are full of multi-step processes that span hours, days, or even months:

• User signs up -> Wait 3 days -> Send email -> Wait 7 days -> Check subscription.
• Order placed -> Charge card -> Wait for shipping -> Update inventory.

Traditionally, you implement this by fragmenting your logic into:

1. Database Columns: status = 'WAITING_FOR_EMAIL', next_check = '2025-01-01'.
2. Cron Jobs: Scripts that poll the DB every minute: SELECT * FROM users WHERE next_check < NOW().
3. Queue Workers: Jobs that handle one tiny slice of logic and then dispatch the next job.

The result? Your business logic is scattered across 10 different files, 3 different infrastructure pieces, and it's impossible to read the flow of the program.

⚡ The Solution: Hibernator

Hibernator lets you write the entire flow in one single PHP file.

How is this possible?

Hibernator uses PHP Fibers to suspend execution and the Replay Pattern (Event Sourcing) to restore state.

1. When you yield wait, Hibernator saves your execution history to the database and kills the process. Zero resources are used.
2. When the time is up, a Worker boots up the workflow.
3. It replays previous steps instantly from the database history (skipping the actual work) to restore variables and memory state.
4. It continues executing from the exact line where it left off.

📋 Requirements

• PHP 8.2+ (Native Fiber support required)
• ext-pdo (For database connectivity)
• MySQL/MariaDB (Default store implementation)

📦 Installation

Install via Composer:

🚀 Quick Start Guide

Step 1: Database Setup

You need to create the tables to store standard workflow state and event history. Run the following SQL in your database:

Step 2: Create an Activity

Activities are the building blocks of your workflow. They represent side effects (e.g., sending an email, charging a card, writing to a file). They must implement Hibernator\Activity\ActivityInterface.

Important: Activities should be idempotent if possible, as they might be retried in failure scenarios (though the Replay Pattern generally prevents re-execution of successful activities).

Step 3: Create a Workflow

Workflows define the flow of logic. They are deterministic code that orchestrates your activities.

• Use yield WorkflowContext::execute($activity) to run an activity.
• Use yield WorkflowContext::wait($duration) to sleep.

Step 4: Run a Workflow (The Orchestrator)

To start a new workflow, you need the Orchestrator. This is the engine that manages the Fibers.

Step 5: Run the Worker (The "Heartbeat")

When a workflow sleeps (e.g., wait('3 days')), it saves its state to the database and stops executing. To wake it up when the time comes, you need a Worker process running in the background.

Run this script in a supervisor process or a terminal:

📚 API Reference

Hibernator\Workflow\WorkflowContext

The static API used inside your Workflow classes.

execute(ActivityInterface $activity): mixed

Yields execution to the orchestrator to run an activity.

• Returns: The result of the activity's handle() method.
• Behavior: If the activity was already run in history, returns the cached result.

wait(string $duration): void

Pauses the workflow for a specified duration.

• $duration: A string understandable by PHP's DateTime::modify (e.g., "+1 day", "30 minutes").

sideEffect(callable $callable): mixed

Executes a non-deterministic snippet of code (like generating a random ID) and checkpoints the result so it is deterministic on replay.

⚙️ How It Works (Under the Hood)

Hibernator uses the Event Sourcing / Replay Pattern.

1. Run 1: You start the workflow. It runs until it hits an Activity. It executes the Activity, saves the result to the history table, and continues.
2. Sleep: It hits a wait() command. It saves a "timer started" state and updates the workflow status to sleeping. The PHP process exits.
3. Wake Up: The Worker sees the wake_up_time has passed. It calls Orchestrator->run().
4. Replay: The workflow starts from the beginning.
   • It hits the first Activity. It sees in history that it's already done. It skips execution and returns the saved result.
   • It hits the wait(). It sees the timer is done. It continues.
   • It executes the next step (new code).

Testing

Hibernator is designed for testing. You can easily test 7-day workflows in 1 second by mocking time.

See tests/TimeSkippingTest.php in the repository for a full example of how to use a fake time source to verify your long-running logic instantly.

License

MIT License. Free to use for personal and commercial projects.