PHPackages                             blumilksoftware/heatmap - 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. blumilksoftware/heatmap

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

blumilksoftware/heatmap
=======================

Heatmap library for PHP

v0.0.2(2y ago)41652[2 issues](https://github.com/blumilksoftware/heatmap/issues)1MITPHPPHP ^8.2

Since Jan 10Pushed 3mo ago3 watchersCompare

[ Source](https://github.com/blumilksoftware/heatmap)[ Packagist](https://packagist.org/packages/blumilksoftware/heatmap)[ RSS](/packages/blumilksoftware-heatmap/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (2)Dependencies (3)Versions (5)Used By (1)

[![Packagist PHP Version Support](https://camo.githubusercontent.com/9b0309a6033aea35268a519414ef82c2c6a649f6faacf21ee9d69c37a8aa700f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f626c756d696c6b736f6674776172652f686561746d61703f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/9b0309a6033aea35268a519414ef82c2c6a649f6faacf21ee9d69c37a8aa700f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f626c756d696c6b736f6674776172652f686561746d61703f7374796c653d666f722d7468652d6261646765) [![Packagist Version](https://camo.githubusercontent.com/cf3578c00603aebc8f2a317de95e83bc2e03e5c59f1bf9bcd889deea5cc8d0f3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f626c756d696c6b736f6674776172652f686561746d61703f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/cf3578c00603aebc8f2a317de95e83bc2e03e5c59f1bf9bcd889deea5cc8d0f3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f626c756d696c6b736f6674776172652f686561746d61703f7374796c653d666f722d7468652d6261646765) [![Packagist Downloads](https://camo.githubusercontent.com/f018b8005c700e5c32d8487b77d355325b0d6059cee23bad1521387e58cff568/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f626c756d696c6b736f6674776172652f686561746d61703f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/f018b8005c700e5c32d8487b77d355325b0d6059cee23bad1521387e58cff568/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f626c756d696c6b736f6674776172652f686561746d61703f7374796c653d666f722d7468652d6261646765)

About
-----

[](#about)

Making a heatmap from custom datasets should be extremely easy. We are here to help you with that.

What's a heatmap? It is a data visualization technique that shows magnitude of a phenomenon as color in two dimensions\[[1](https://en.wikipedia.org/wiki/Heat_map)\], and you can know it from GitHub user profile pages:

[![./docs/github.png](./docs/github.png)](./docs/github.png)

### Installation

[](#installation)

The Heatmap is distributed as Composer library via [Packagist](https://packagist.org/packages/blumilksoftware/heatmap). To add it to your project, execute the following command:

```
composer require blumilksoftware/heatmap
```

### Usage

[](#usage)

You can use any set of data you want. By default, dates will be taken from `"created_at"` key of arrays or objects implementing `\ArrayAccess` interface. Builder accepts also objects implementing `\Blumilk\HeatmapBuilder\Contracts\TimeGroupable` contract with mandatory `getTimeGroupableIndicator()` method returning a string with proper date:

```
$data = [
    ["created_at" => "2025-11-01 00:00:00", /** (...) */],
    ["created_at" => "2025-11-03 00:00:00", /** (...) */],
    ["created_at" => "2025-11-16 00:00:00", /** (...) */],
    ["created_at" => "2025-11-16 00:00:00", /** (...) */],
    ["created_at" => "2025-11-18 00:00:00", /** (...) */],
    ["created_at" => "2025-11-19 00:00:00", /** (...) */],
];
```

Then create an instance of `\Blumilk\HeatmapBuilder\HeatmapBuilder`. By default, it will be working on day-based periods for last week from the moment you are calling it:

```
$builder = new HeatmapBuilder();
$result = $builder->build($data);
```

Method `build()` returns array of tiles that can be serialized into JSON with simple `json_encode()` function or any other serializer:

```
[
  {
    "label": "2025-11-16",
    "count": 2,
    "description": ""
  },
  {
    "label": "2025-11-17",
    "count": 0,
    "description": ""
  },
  {
    "label": "2025-11-18",
    "count": 1,
    "description": ""
  },
  {
    "label": "2025-11-19",
    "count": 1,
    "description": ""
  },
  {
    "label": "2025-11-20",
    "count": 0,
    "description": ""
  },
  {
    "label": "2025-11-21",
    "count": 0,
    "description": ""
  },
  {
    "label": "2025-11-22",
    "count": 0,
    "description": ""
  },
  {
    "label": "2025-11-23",
    "count": 0,
    "description": ""
  }
]
```

### Customizing the Heatmap Builder watching period

[](#customizing-the-heatmap-builder-watching-period)

By default, the `HeatmapBuilder` automatically sets its observation period to the last seven days if no custom period (`$period`) is provided during instantiation. This default behavior ensures a rolling seven-day view from the current day.

If you need to specify a custom period (e.g., the entire month of January), you can achieve this by explicitly passing a `CarbonPeriod` instance to the builder, as shown in the example below:

```
// Define a custom period for the entire month of January 2025
$period = CarbonPeriod::create(
    Carbon::parse('2025-01-01'),
    '1 day',
    Carbon::parse('2025-01-31')
);

// Instantiate the HeatmapBuilder with the custom period
$builder = new HeatmapBuilder(
    now: Carbon::now(),
    periodInterval: PeriodInterval::Daily,
    period: $period // Include the custom period
);

// Generate the heatmap data
$result = $builder->build($data);
```

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance44

Moderate activity, may be stable

Popularity17

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 50% 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 ~1 days

Total

2

Last Release

736d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/10898728?v=4)[Krzysztof Rewak](/maintainers/krzysztofrewak)[@krzysztofrewak](https://github.com/krzysztofrewak)

---

Top Contributors

[![BarTracz](https://avatars.githubusercontent.com/u/115506125?v=4)](https://github.com/BarTracz "BarTracz (7 commits)")[![krzysztofrewak](https://avatars.githubusercontent.com/u/10898728?v=4)](https://github.com/krzysztofrewak "krzysztofrewak (5 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (1 commits)")[![perisicnikola37](https://avatars.githubusercontent.com/u/79047182?v=4)](https://github.com/perisicnikola37 "perisicnikola37 (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/blumilksoftware-heatmap/health.svg)

```
[![Health](https://phpackages.com/badges/blumilksoftware-heatmap/health.svg)](https://phpackages.com/packages/blumilksoftware-heatmap)
```

###  Alternatives

[illuminate/support

The Illuminate Support package.

630113.0M41.4k](/packages/illuminate-support)[spatie/holidays

Calculate public holidays

402860.1k2](/packages/spatie-holidays)[craftcms/feed-me

Import content from XML, RSS, CSV or JSON feeds into entries, categories, Craft Commerce products, and more.

293952.6k33](/packages/craftcms-feed-me)[solspace/craft-freeform

The most flexible and user-friendly form building plugin!

54681.3k19](/packages/solspace-craft-freeform)[pimcore/data-importer

Adds a comprehensive import functionality to Pimcore Datahub

46855.5k5](/packages/pimcore-data-importer)[flarum/core

Delightfully simple forum software.

201.4M2.3k](/packages/flarum-core)

PHPackages © 2026

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