PHPackages                             spiriitlabs/commit-history - 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. spiriitlabs/commit-history

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

spiriitlabs/commit-history
==========================

Fetch commit history from GitLab or GitHub repositories

V1.0.1(1mo ago)0383↓38.9%1[1 PRs](https://github.com/SpiriitLabs/commit-history-lib/pulls)1MITPHPPHP >=8.2CI passing

Since Jan 12Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/SpiriitLabs/commit-history-lib)[ Packagist](https://packagist.org/packages/spiriitlabs/commit-history)[ RSS](/packages/spiriitlabs-commit-history/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (6)Versions (4)Used By (1)

Commit History Library
======================

[](#commit-history-library)

A framework-agnostic PHP library for fetching commit history from GitHub and GitLab repositories, with support for detecting dependency changes.

Features
--------

[](#features)

- Fetch commit history from **GitHub** (including Enterprise) and **GitLab** (including self-hosted)
- Detect dependency changes in commits (Composer and npm)
- Year-based filtering with automatic pagination
- Support for private repositories via access tokens
- Fully typed with PHP 8.2+ readonly classes

Requirements
------------

[](#requirements)

- PHP 8.2 or higher

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

[](#installation)

```
composer require spiriitlabs/commit-history
```

Usage
-----

[](#usage)

### Basic Setup with GitHub

[](#basic-setup-with-github)

```
use Spiriit\CommitHistory\Contract\HttpClientInterface;
use Spiriit\CommitHistory\Provider\Github\GithubProvider;
use Spiriit\CommitHistory\Provider\Github\CommitParser;
use Spiriit\CommitHistory\Service\FeedFetcher;

// Implement the HttpClientInterface (see Contracts section below)
$httpClient = new MyHttpClient();

// Create a GitHub provider
$provider = new GithubProvider(
    httpClient: $httpClient,
    parser: new CommitParser(),
    baseUrl: 'https://api.github.com',
    owner: 'symfony',
    repo: 'symfony',
    token: 'ghp_xxxx', // optional, required for private repos
    ref: 'main',       // optional, filter by branch
);

// Create the feed fetcher
$feedFetcher = new FeedFetcher(
    provider: $provider,
    availableYearsCount: 6, // optional, defaults to 6 years
);

// Fetch commits for a specific year
$commits = $feedFetcher->fetch(2024);

foreach ($commits as $commit) {
    echo sprintf(
        "[%s] %s by %s\n",
        $commit->date->format('Y-m-d'),
        $commit->title,
        $commit->author
    );
}
```

### Using GitLab

[](#using-gitlab)

```
use Spiriit\CommitHistory\Provider\Gitlab\GitlabProvider;
use Spiriit\CommitHistory\Provider\Gitlab\CommitParser;

$provider = new GitlabProvider(
    httpClient: $httpClient,
    parser: new CommitParser(),
    baseUrl: 'https://gitlab.com',              // or your self-hosted instance
    projectId: '12345678',
    token: 'glpat-xxxx',                        // optional
    ref: 'main',                                // optional
);
```

### Detecting Dependency Changes

[](#detecting-dependency-changes)

Enable dependency detection to flag commits that modify dependency files:

```
use Spiriit\CommitHistory\Service\DependencyDetectionService;

$dependencyService = new DependencyDetectionService(
    provider: $provider,
    dependencyFiles: ['composer.json', 'composer.lock', 'package.json', 'package-lock.json'],
    trackDependencyChanges: true,
);

$feedFetcher = new FeedFetcher(
    provider: $provider,
    dependencyDetectionService: $dependencyService,
);

$commits = $feedFetcher->fetch(2024);

foreach ($commits as $commit) {
    if ($commit->hasDependenciesChanges) {
        echo $commit->title . " (has dependency changes)\n";
    }
}
```

### Available Methods

[](#available-methods)

```
// Fetch commits for a specific year (defaults to current year)
$commits = $feedFetcher->fetch(2024);

// Get available years for filtering
$years = $feedFetcher->getAvailableYears(); // [2024, 2023, 2022, ...]
```

Contracts
---------

[](#contracts)

### HttpClientInterface

[](#httpclientinterface)

You must provide an implementation of `HttpClientInterface`:

```
interface HttpClientInterface
{
    /**
     * @param array $headers
     * @return array{status: int, headers: array, body: string}
     */
    public function request(string $method, string $url, array $headers = []): array;
}
```

Example implementation using Guzzle:

```
use Spiriit\CommitHistory\Contract\HttpClientInterface;
use GuzzleHttp\Client;

class GuzzleHttpClient implements HttpClientInterface
{
    private Client $client;

    public function __construct()
    {
        $this->client = new Client();
    }

    public function request(string $method, string $url, array $headers = []): array
    {
        $response = $this->client->request($method, $url, ['headers' => $headers]);

        return [
            'status' => $response->getStatusCode(),
            'headers' => $response->getHeaders(),
            'body' => (string) $response->getBody(),
        ];
    }
}
```

Data Objects
------------

[](#data-objects)

### Commit

[](#commit)

PropertyTypeDescription`id``string`Commit SHA (short)`title``string`Commit message (first line)`date``DateTimeImmutable`Commit date`author``string`Author name`url``string`URL to commit on GitHub/GitLab`authorEmail``?string`Author email`hasDependenciesChanges``bool`Whether commit modifies dependency filesExtending
---------

[](#extending)

### Adding a New Provider

[](#adding-a-new-provider)

1. Create a `CommitParser` implementing `CommitParserInterface`
2. Create a provider implementing `ProviderInterface`

```
use Spiriit\CommitHistory\Provider\ProviderInterface;
use Spiriit\CommitHistory\Provider\CommitParserInterface;
use Spiriit\CommitHistory\DTO\Commit;

class BitbucketCommitParser implements CommitParserInterface
{
    public function parse(array $data): Commit
    {
        // Parse Bitbucket API response into Commit DTO
    }
}

class BitbucketProvider implements ProviderInterface
{
    public function __construct(
        private readonly HttpClientInterface $httpClient,
        private readonly CommitParserInterface $parser,
        // ... other params
    ) {}

    public function getCommits(?\DateTimeImmutable $since = null, ?\DateTimeImmutable $until = null): array
    {
        // Fetch and parse commits from Bitbucket API
    }

    public function getCommitFileNames(string $commitId): array
    {
        // Return list of changed files for dependency detection
    }

    public function getCommitDiff(string $commitId): array
    {
        // Return map of filename => diff content
    }
}
```

Symfony Integration
-------------------

[](#symfony-integration)

For Symfony projects, use the [SpiriitLabs Commit History Bundle](https://github.com/spiriitlabs/commit-history-bundle) which provides:

- Pre-configured service definitions
- Symfony HTTP client adapter
- Twig templates for rendering a timeline UI
- YAML/PHP configuration

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance89

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity49

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

Total

2

Last Release

56d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1807e890fb651ea404b659ae9e720c3d71020b13ed4385faaf79ae77d45fb3c6?d=identicon)[SpiriitLabs](/maintainers/SpiriitLabs)

---

Top Contributors

[![lotimopa](https://avatars.githubusercontent.com/u/267104737?v=4)](https://github.com/lotimopa "lotimopa (1 commits)")[![RomainMILLAN](https://avatars.githubusercontent.com/u/42139000?v=4)](https://github.com/RomainMILLAN "RomainMILLAN (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/spiriitlabs-commit-history/health.svg)

```
[![Health](https://phpackages.com/badges/spiriitlabs-commit-history/health.svg)](https://phpackages.com/packages/spiriitlabs-commit-history)
```

###  Alternatives

[fntneves/laravel-transactional-events

Transaction-aware Event Dispatcher for Laravel

3202.6M2](/packages/fntneves-laravel-transactional-events)[ipinfo/ipinfo

The official PHP library for IPinfo, the most reliable, accurate, and in-depth source of IP address data available anywhere. We process terabytes of data to produce our custom IP geolocation, company, carrier and IP type data sets. Visit our developer docs at https://ipinfo.io/developers.

2891.2M11](/packages/ipinfo-ipinfo)[craftcms/plugin-installer

Craft CMS Plugin Installer

283.3M4](/packages/craftcms-plugin-installer)[typo3/cms-recordlist

TYPO3 CMS Recordlist - Lists database records in the TYPO3 backend module (Web>List).

178.0M48](/packages/typo3-cms-recordlist)[broadway/uuid-generator

UUID generator for broadway/broadway.

202.1M11](/packages/broadway-uuid-generator)

PHPackages © 2026

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