PHPackages                             zlikavac32/alarm-scheduler - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. zlikavac32/alarm-scheduler

ActiveLibrary[Utility & Helpers](/categories/utility)

zlikavac32/alarm-scheduler
==========================

SIGALRM scheduler

0.2.1(7y ago)35.2k1MITPHPPHP ^7.1CI failing

Since Feb 15Pushed 6y ago1 watchersCompare

[ Source](https://github.com/zlikavac32/alarm-scheduler)[ Packagist](https://packagist.org/packages/zlikavac32/alarm-scheduler)[ RSS](/packages/zlikavac32-alarm-scheduler/feed)WikiDiscussions master Synced 3d ago

READMEChangelogDependencies (3)Versions (5)Used By (1)

Alarm scheduler
===============

[](#alarm-scheduler)

[![Build Status](https://camo.githubusercontent.com/d1967411491179c5d9f4e78c786b538d5b758eb6ff375ec4da4c36b044f96c5e/68747470733a2f2f7472617669732d63692e6f72672f7a6c696b6176616333322f616c61726d2d7363686564756c65722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/zlikavac32/alarm-scheduler)

This library provides support for multiple `SIGALRM` handlers.

Table of contents
-----------------

[](#table-of-contents)

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [API](#api)
    1. [AlarmHandler](#alarmhandler)
    2. [AlarmScheduler](#alarmscheduler)
    3. [InterruptException](#interruptexception)
    4. [InterruptAlarmHandler](#interruptalarmhandler)
    5. [CatchThrowableAlarmHandler](#catchthrowablealarmhandler)
4. [Usage](#usage)
5. [Rule of thumb](#rule-of-thumb)
6. [Examples](#examples)

Introduction
------------

[](#introduction)

As of PHP 7.1, async signals are supported through [pcntl\_async\_signals()](http://php.net/manual/en/function.pcntl-async-signals.php) function. With that nice feature, [pcntl\_alarm()](http://php.net/manual/en/function.pcntl-alarm.php) became more helpful than ever.

Only issue is, we can set one signal handler per process.

This library provides simple scheduler for `SIGALRM` and allows multiple targets to be scheduled with some arbitrary delay.

Installation
------------

[](#installation)

Recommended installation is through Composer.

```
composer require zlikavac32/alarm-scheduler
```

API
---

[](#api)

Two interfaces are provided, one for alarm handler and the other for the alarm scheduler.

Do note that this library does not call `pcntl_async_signals(true);`. It's the responsibility of the library user to call it where they find it applicable.

### AlarmHandler

[](#alarmhandler)

Interface `\Zlikavac32\AlarmScheduler\AlarmHandler` is used to implement alarm handler. Method `handle()` will be called from the signal handler so check [Rule of thumb](#rule-of-thumb) for more info.

Current scheduler is passed into `handle()` to allow rescheduling of the handler (or scheduling a new one).

AlarmScheduler
--------------

[](#alarmscheduler)

Interface `\Zlikavac32\AlarmScheduler\AlarmScheduler` is used to implement alarm scheduler. Implementation should take control over `SIGALRM` handling.

Methods must be safe to be called from within the signal handler. Check [Rule of thumb](#rule-of-thumb) for more info.

InterruptException
------------------

[](#interruptexception)

Exception representing hard interrupt that must be respected by the scheduler implementation.

It can be thrown from the alarm handler in order to cause exception from the signal handler.

Users are not restricted to this exception for the hard interrupt as described in the [Rule of thumb](#rule-of-thumb) section.

InterruptAlarmHandler
---------------------

[](#interruptalarmhandler)

Causes hard interrupt from alarm scheduler by throwing `InterruptException`

CatchThrowableAlarmHandler
--------------------------

[](#catchthrowablealarmhandler)

Alarm handler that wraps any other alarm handler and catches any throwable caught from it is implemented in `\Zlikavac32\AlarmScheduler\CatchThrowableAlarmHandler`. What is caught is passed into `\Zlikavac32\AlarmScheduler\ThrowableHandler`. If the throwable handler throws anything, it's silently ignored.

Simple throwable handler that just ignores everything is provided through `\Zlikavac32\AlarmScheduler\IgnoreThrowableHandler`.

Usage
-----

[](#usage)

First create the scheduler (currently, only single implementation is provided).

```
$scheduler = new \Zlikavac32\AlarmScheduler\NaiveAlarmScheduler();
```

When it's applicable to take over of `SIGALRM` handling, call

```
$scheduler->start();
```

Method `start()` must be called before any additional use of scheduler methods.

Then implement some alarm handler.

```
$handler = new class implements \Zlikavac32\AlarmScheduler\AlarmHandler {

   public function handle(\Zlikavac32\AlarmScheduler\AlarmScheduler $scheduler): void {
       echo (new DateTime())->format('i\\m:s\\s'), "\n";
   }
};
```

Next, schedule alarm handler.

```
$scheduler->schedule(5, $handler); // to run $handler in 5 seconds
```

Now, this will not block. If script reaches end before handlers are triggered, it will exit without triggering them.

For testing purposes, we can sleep for a few seconds. We can also print current time.

```
echo (new DateTime())->format('i\\m:s\\s'), "\n";

$sleep = 7;
while ($sleep = sleep($sleep));
```

Rule of thumb
-------------

[](#rule-of-thumb)

If `SIGALRM` is not blocked, it can interrupt scheduler methods at any point. Scheduler implementations must be safe to be run from within the signal handler. In most cases that means blocking signal until scheduler method is to be finished, and then unblocking it. PHP VM takes care of the rest.

No exception, except `\Zlikavac32\AlarmScheduler\InterruptException`, should be thrown from the alarm handler. If exception is thrown, and scheduler implementation does not catch it (which is not the requirement), it could leave the scheduler in inconsistent state.

If custom async exception is a requirement, alternative is to use `SIGUSR1` or `SIGUSR2` to throw exception from a different stack frame. PHP VM will deffer signal handling until current handler finishes. That means it will not affect scheduler stack frame.

```
pcntl_signal(SIGUSR1, function (): void {
    throw new SomeDomainSpecificException();
});

$scheduler->schedule(2, new class implements \Zlikavac32\AlarmScheduler\AlarmHandler {

    public function handle(\Zlikavac32\AlarmScheduler\AlarmScheduler $scheduler): void {
        posix_kill(getmypid(), SIGUSR1);
    }
});
```

`sleep()` may not be safe to use with `SIGALRM` so check how your system handles sleeping before using this library.

Examples
--------

[](#examples)

Examples with code comments can be found in [examples](/examples) directory.

###  Health Score

27

—

LowBetter than 47% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity21

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~34 days

Total

3

Last Release

2623d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1078270?v=4)[Marijan Šuflaj](/maintainers/zlikavac32)[@zlikavac32](https://github.com/zlikavac32)

---

Top Contributors

[![zlikavac32](https://avatars.githubusercontent.com/u/1078270?v=4)](https://github.com/zlikavac32 "zlikavac32 (16 commits)")

---

Tags

alarmpcntlphpsignalschedulersignalalarmpcntlSIGALRM

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/zlikavac32-alarm-scheduler/health.svg)

```
[![Health](https://phpackages.com/badges/zlikavac32-alarm-scheduler/health.svg)](https://phpackages.com/packages/zlikavac32-alarm-scheduler)
```

###  Alternatives

[seld/signal-handler

Simple unix signal handler that silently fails where signals are not supported for easy cross-platform development

18279.3M27](/packages/seld-signal-handler)[peppeocchi/php-cron-scheduler

PHP Cron Job Scheduler

8292.6M37](/packages/peppeocchi-php-cron-scheduler)[kigkonsult/icalcreator

iCalcreator is the PHP implementation of rfc2445/rfc5545 and rfc updates, management of calendar information

2482.8M20](/packages/kigkonsult-icalcreator)[symfony/scheduler

Provides scheduling through Symfony Messenger

9112.8M100](/packages/symfony-scheduler)[duncan3dc/fork-helper

Simple class to fork processes in PHP and allow multi-threading

81574.0k4](/packages/duncan3dc-fork-helper)[rewieer/taskschedulerbundle

Task Scheduler with CRON for Symfony

63247.9k](/packages/rewieer-taskschedulerbundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)