PHPackages                             sanmai/sliding-window-counter - 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. [Caching](/categories/caching)
4. /
5. sanmai/sliding-window-counter

ActiveLibrary[Caching](/categories/caching)

sanmai/sliding-window-counter
=============================

Short-lived cache-backed time series with anomaly detection

0.2.3(7mo ago)410.3k↓20.1%[1 issues](https://github.com/sanmai/sliding-window-counter/issues)1GPL-2.0-or-laterPHPPHP >=8.2CI passing

Since Apr 10Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/sanmai/sliding-window-counter)[ Packagist](https://packagist.org/packages/sanmai/sliding-window-counter)[ RSS](/packages/sanmai-sliding-window-counter/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (7)Dependencies (9)Versions (8)Used By (1)

Sliding Window Counter
======================

[](#sliding-window-counter)

[![Latest Stable Version](https://camo.githubusercontent.com/c5737d0b47f7387afea1883994d4a3eed1c31687c9ded5e015c30d372bc24e3c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73616e6d61692f736c6964696e672d77696e646f772d636f756e7465722e737667)](https://packagist.org/packages/sanmai/sliding-window-counter)[![License](https://camo.githubusercontent.com/ed42067eaa69c1aa894da73896eff46136230b85a8721036e648d251b4f933c6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d47504c2d2d322e302532304f522532304170616368652d2d322e302d626c75652e737667)](https://github.com/sanmai/sliding-window-counter#license)

Short-lived cache-backed time series with anomaly detection
-----------------------------------------------------------

[](#short-lived-cache-backed-time-series-with-anomaly-detection)

A lightweight, efficient PHP library for tracking time-based events and detecting anomalies without the overhead of databases or logs.

Table of Contents
-----------------

[](#table-of-contents)

- [Overview](#whats-this-all-about)
- [Features](#features)
- [How It Works](#how-it-works-the-simple-version)
- [Installation](#installation)
- [Quick Start](#quick-start)
    - [Setting up a counter](#setting-up-a-counter)
    - [Tracking events](#tracking-events)
    - [Detecting unusual activity](#detecting-unusual-activity)
    - [Getting more stats](#getting-more-stats)
- [Advanced Usage](#adjusting-sensitivity)
- [Cache Adapters](#available-cache-adapters)
- [Technical Details](#technical-details-for-the-curious)
- [Contributing](#contributing)
- [License](#license)

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

[](#installation)

```
composer require sanmai/sliding-window-counter
```

What's this all about?
----------------------

[](#whats-this-all-about)

Ever needed to track how many times something happens over time and spot when those numbers get weird? That's what this library does, and it does it efficiently.

Real-world example: Imagine you want to detect when suspicious messages from specific IP ranges suddenly spike. Instead of digging through logs or querying databases, this library uses in-memory caching to track events and spot unusual patterns before it is too late.

Features
--------

[](#features)

- Lightweight - Uses your existing cache infrastructure
- Fast - No database queries or log parsing
- Robust anomaly detection - Based on standard deviations
- Flexible time windows - Configure to your needs
- Production-ready - Originally developed for Tumblr

How it works (the simple version)
---------------------------------

[](#how-it-works-the-simple-version)

1. Divide time into buckets - We slice time into equal chunks (like 5-minute windows or hourly buckets)
2. Count events in cache - Each event increments a counter in the appropriate time bucket
3. Create time series on demand - When needed, we assemble these buckets into a continuous series
4. Apply statistical analysis - We calculate mean, standard deviation, and detect outliers

The library handles all the tricky parts like:

- What happens when current time doesn't perfectly align with your time buckets
- Calculating meaningful statistics on the fly
- Determining what counts as "unusual" activity (with adjustable sensitivity)

Quick Start
-----------

[](#quick-start)

### Setting up a counter

[](#setting-up-a-counter)

```
// Create a counter that tracks hourly data for the past 24 hours
$counter = new \SlidingWindowCounter\SlidingWindowCounter(
    'visitor-counter',     // Name for your counter
    3600,                  // Window size: 3600 seconds (1 hour)
    3600 * 24,             // Keep data for 24 hours
    new \SlidingWindowCounter\Cache\MemcachedAdapter($memcached)
);
```

### Tracking events

[](#tracking-events)

```
// Count a visit from this IP address
$counter->increment($_SERVER['REMOTE_ADDR']);

// You can also count by other keys
$counter->increment('user_' . $user_id);
$counter->increment('product_' . $product_id);
```

### Detecting unusual activity

[](#detecting-unusual-activity)

```
// Check if current activity is abnormal
$result = $counter->detectAnomaly($_SERVER['REMOTE_ADDR']);

if ($result->isAnomaly()) {
    // Something unusual is happening!
    $direction = $result->getDirection(); // Returns DIRECTION_UP, DIRECTION_DOWN, or DIRECTION_NONE

    if ($direction === \SlidingWindowCounter\AnomalyDetectionResult::DIRECTION_UP) {
        // Unusually high activity
        echo "Spike detected! Current: " . $result->getLatest();
        echo "Normal range: " . $result->getLow() . " to " . $result->getHigh();
    }
}
```

### Getting more stats

[](#getting-more-stats)

```
// Get all stats as an array (values rounded to 2 decimal places by default)
$stats = $result->toArray();

// Or access individual values
$mean = $result->getMean();
$stdDev = $result->getStandardDeviation();
$currentValue = $result->getLatest();

// You can also get historical variance directly
$variance = $counter->getHistoricVariance($_SERVER['REMOTE_ADDR']);
$sampleCount = $variance->getCount();
```

Adjusting Sensitivity
---------------------

[](#adjusting-sensitivity)

You can control how sensitive the anomaly detection is by specifying the number of standard deviations that define "normal":

```
// Higher sensitivity (1 standard deviation) - detects more anomalies
$result = $counter->detectAnomaly($_SERVER['REMOTE_ADDR'], 1);

// Default sensitivity (2 standard deviations)
$result = $counter->detectAnomaly($_SERVER['REMOTE_ADDR']);

// Lower sensitivity (3 standard deviations) - only extreme outliers
$result = $counter->detectAnomaly($_SERVER['REMOTE_ADDR'], 3);

// Extremely low sensitivity (5 standard deviations) - only detects extreme outliers
$result = $counter->detectAnomaly($_SERVER['REMOTE_ADDR'], 5);
```

A quick stats refresher:

- 1 standard deviation: ~68% of normal values in this range (very sensitive)
- 2 standard deviations: ~95% of normal values in this range (still very sensitive)
- 3 standard deviations: ~99.7% of normal values in this range (fairly sensitive)
- 5 standard deviations: ~99.99994% of normal values in this range (1 in ~1.7 million chance)

Five standard deviations from the mean is a definite anomaly: there's only a ~0.000057% chance that a data point this extreme occurs by random chance under the null hypothesis.

Available Cache Adapters
------------------------

[](#available-cache-adapters)

The library supports multiple caching backends through a simple adapter interface. An example using regular Memcached:

```
$adapter = new \SlidingWindowCounter\Cache\MemcachedAdapter($memcached);
```

### Creating Your Own Adapter

[](#creating-your-own-adapter)

Need to use a different cache system? Implementing a custom adapter is straightforward:

```
use SlidingWindowCounter\Cache\CounterCache;

class RedisAdapter implements CounterCache
{
    private $redis;

    public function __construct(Redis $redis)
    {
        $this->redis = $redis;
    }

    public function increment(string $cache_name, string $cache_key, int $ttl, int $step)
    {
        $key = "{$cache_name}:{$cache_key}";
        $this->redis->setnx($key, 0); // Create if not exists
        $this->redis->expire($key, $ttl);
        return $this->redis->incrby($key, $step);
    }

    public function get(string $cache_name, string $cache_key): ?int
    {
        $value = $this->redis->get("{$cache_name}:{$cache_key}");
        return is_numeric($value) ? (int) $value : null;
    }
}
```

Technical Details (for the curious)
-----------------------------------

[](#technical-details-for-the-curious)

The library uses an elegant sliding window approach to time series data. Here's how it works under the hood:

- Material frames: The actual cached data buckets aligned to window boundaries
- Logical frames: Windows aligned to the current time (which may overlap multiple material frames)

When calculating values for logical frames that don't perfectly align with material frames, we perform weighted extrapolation to ensure smooth transitions in the time series.

Consider these two scenarios:

1. Perfectly aligned frames: When the query time aligns with cache bucket boundaries, we can use the raw values directly.

[![Aligned Frames](docs/images/logical-frames-aligned.svg)](docs/images/logical-frames-aligned.svg)

2. Misaligned frames: When the query time doesn't align with cache boundaries, we extrapolate values based on overlapping portions.

[![Misaligned Frames](docs/images/logical-frames-disaligned.svg)](docs/images/logical-frames-disaligned.svg)

For a more detailed explanation of the internal workings, check out [this Cloudflare blog post](https://blog.cloudflare.com/counting-things-a-lot-of-different-things/) which explains a similar approach.

License
-------

[](#license)

This library is dual-licensed under the GNU General Public License v2.0 or later and the Apache License 2.0. You may choose either license to govern your use of this software.

- For GPL-2.0-or-later license terms, see the [LICENSE-GPL](LICENSE-GPL) file
- For Apache-2.0 license terms, see the [LICENSE](LICENSE) file

When using this library, you must comply with the terms of at least one of these licenses.

All contributions to this project have been reviewed and confirmed by the respective authors as dual-licensed. If you believe your code was included without proper attribution or license representation, please contact us and we'll address it immediately.

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance59

Moderate activity, may be stable

Popularity30

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity44

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 ~30 days

Recently: every ~20 days

Total

7

Last Release

220d ago

PHP version history (2 changes)0.1PHP ^8.1

0.2PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/edcb8dde95c71b1c97c3c91e57d3548795fa2014c657744fb878e2be3b5949fc?d=identicon)[sanmai](/maintainers/sanmai)

---

Top Contributors

[![sanmai](https://avatars.githubusercontent.com/u/139488?v=4)](https://github.com/sanmai "sanmai (34 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/sanmai-sliding-window-counter/health.svg)

```
[![Health](https://phpackages.com/badges/sanmai-sliding-window-counter/health.svg)](https://phpackages.com/packages/sanmai-sliding-window-counter)
```

###  Alternatives

[infection/infection

Infection is a Mutation Testing framework for PHP. The mutation adequacy score can be used to measure the effectiveness of a test set in terms of its ability to detect faults.

2.2k26.2M1.8k](/packages/infection-infection)[react/cache

Async, Promise-based cache interface for ReactPHP

444112.4M40](/packages/react-cache)[wp-media/wp-rocket

Performance optimization plugin for WordPress

7431.3M3](/packages/wp-media-wp-rocket)[illuminate/cache

The Illuminate Cache package.

12835.6M1.4k](/packages/illuminate-cache)[colinmollenhour/php-redis-session-abstract

A Redis-based session handler with optimistic locking

6325.6M14](/packages/colinmollenhour-php-redis-session-abstract)[cheprasov/php-redis-client

Php client for Redis. It is a fast, fully-functional and user-friendly client for Redis, optimized for performance. RedisClient supports the latest versions of Redis starting from 2.6 to 6.0

1281.2M21](/packages/cheprasov-php-redis-client)

PHPackages © 2026

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