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(3mo ago)01.0k↓57.9%1[1 issues](https://github.com/SpiriitLabs/commit-history-lib/issues)[1 PRs](https://github.com/SpiriitLabs/commit-history-lib/pulls)1MITPHPPHP >=8.2CI passing

Since Jan 12Pushed 3mo 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 yesterday

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

43

—

FairBetter than 89% of packages

Maintenance82

Actively maintained with recent releases

Popularity20

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

102d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/108736513?v=4)[Spiriit](/maintainers/SpiriitLabs)[@SpiriitLabs](https://github.com/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

[jlzan1314/swoft-entity

swoft 2.0 entity creater

121.5k](/packages/jlzan1314-swoft-entity)

PHPackages © 2026

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