PHPackages                             cable8mm/mma-scrapers - 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. cable8mm/mma-scrapers

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

cable8mm/mma-scrapers
=====================

A lightweight, extensible PHP library for scraping MMA data from multiple sources.

v0.3.0(1mo ago)144[1 PRs](https://github.com/cable8mm/mma-scrapers/pulls)MITHTMLPHP ^8.4CI passing

Since Apr 23Pushed 1w agoCompare

[ Source](https://github.com/cable8mm/mma-scrapers)[ Packagist](https://packagist.org/packages/cable8mm/mma-scrapers)[ RSS](/packages/cable8mm-mma-scrapers/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (6)Dependencies (6)Versions (7)Used By (0)

MMA Scrapers
============

[](#mma-scrapers)

A lightweight PHP library for scraping and parsing MMA data into simple DTOs.

[![build & tests](https://github.com/cable8mm/mma-scrapers/actions/workflows/run-tests.yml/badge.svg)](https://github.com/cable8mm/mma-scrapers/actions/workflows/run-tests.yml)[![coding style](https://github.com/cable8mm/mma-scrapers/actions/workflows/code-style.yml/badge.svg)](https://github.com/cable8mm/mma-scrapers/actions/workflows/code-style.yml)[![deploy-to-github-pages](https://github.com/cable8mm/mma-scrapers/actions/workflows/deploy-to-github-pages.yml/badge.svg)](https://github.com/cable8mm/mma-scrapers/actions/workflows/deploy-to-github-pages.yml)[![update changelog](https://github.com/cable8mm/mma-scrapers/actions/workflows/update-changelog.yml/badge.svg)](https://github.com/cable8mm/mma-scrapers/actions/workflows/update-changelog.yml)[![Packagist Dependency Version](https://camo.githubusercontent.com/12b64a0728d7f7bdd959c6a34f9a2878d56764715942298b2eb603f646f7fb3c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f6361626c65386d6d2f6d6d612d73637261706572732f706870)](https://camo.githubusercontent.com/12b64a0728d7f7bdd959c6a34f9a2878d56764715942298b2eb603f646f7fb3c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f6361626c65386d6d2f6d6d612d73637261706572732f706870)[![Packagist Version](https://camo.githubusercontent.com/0a51844d07b5a4f35657793cd20adc23fd799a87e71fe2181cf7b543f8c67b15/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6361626c65386d6d2f6d6d612d7363726170657273)](https://camo.githubusercontent.com/0a51844d07b5a4f35657793cd20adc23fd799a87e71fe2181cf7b543f8c67b15/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6361626c65386d6d2f6d6d612d7363726170657273)[![Packagist Downloads](https://camo.githubusercontent.com/d261414e85af286571fea3bb6fbc24a9665355961e4245e85f1d03e52b01334c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6361626c65386d6d2f6d6d612d7363726170657273)](https://camo.githubusercontent.com/d261414e85af286571fea3bb6fbc24a9665355961e4245e85f1d03e52b01334c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6361626c65386d6d2f6d6d612d7363726170657273)[![Packagist Stars](https://camo.githubusercontent.com/67ee5494a8e494561ff87b4949204508341111174a1b71be7daffa39094eb34d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f6361626c65386d6d2f6d6d612d7363726170657273)](https://camo.githubusercontent.com/67ee5494a8e494561ff87b4949204508341111174a1b71be7daffa39094eb34d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f6361626c65386d6d2f6d6d612d7363726170657273)[![GitHub License](https://camo.githubusercontent.com/c03729b56a53d4e32d80a3cc5170f40fb1868282b08eb2ee653e7885816cc788/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6361626c65386d6d2f6d6d612d7363726170657273)](https://camo.githubusercontent.com/c03729b56a53d4e32d80a3cc5170f40fb1868282b08eb2ee653e7885816cc788/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6361626c65386d6d2f6d6d612d7363726170657273)

Features
--------

[](#features)

- Source-specific scrapers and parsers for MMA websites.
- Normalized DTOs for events, fights, and fighters.
- Fixture-friendly parser design using Symfony DomCrawler.
- Mockable HTTP layer through `HttpClientInterface`.
- Helper services for fighter matching, Sherdog ID resolution, and fight deduplication.
- No database dependency.

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

[](#requirements)

- PHP `^8.4`
- Composer

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

[](#installation)

```
composer require cable8mm/mma-scrapers
```

For local development:

```
composer install
```

Supported Sources
-----------------

[](#supported-sources)

SourceEventsEvent detailFightsFightersNotesBlackCombatYesYesYesYesOfficial source supportSherdogNoNoNoYesFighter search and fighter detail supportTapologyNoNoNoNoPlanned sourceCore Concepts
-------------

[](#core-concepts)

The library is organized around a small pipeline:

```
HTTP client -> Scraper -> Parser -> DTO

```

Scrapers fetch HTML and delegate extraction to parsers. Parsers are deterministic and return DTOs. Aggregators and services are available when a consuming app needs to compare, merge, or deduplicate parsed results.

Project Structure
-----------------

[](#project-structure)

```
src/
  Aggregators/      Merge related event, fight, and fighter DTOs
  Contracts/        Scraper and HTTP interfaces
  DTO/              EventDTO, FightDTO, FighterDTO
  Enums/            Source, fight status, fight method, weight class
  Http/             Guzzle HTTP client implementation
  Matchers/         Fighter matching helpers
  Normalizers/      Text-to-enum normalization helpers
  Services/         Sherdog ID resolution and fight deduplication
  Sources/
    BlackCombat/
      Parsers/
      Scrapers/
    Sherdog/
      Parsers/
      Scrapers/

```

Usage
-----

[](#usage)

### Parse BlackCombat Events From HTML

[](#parse-blackcombat-events-from-html)

```
use Cable8mm\MmaScrapers\Sources\BlackCombat\Parsers\ParseEvents;

$html = file_get_contents('blackcombat_events.html');

$parser = new ParseEvents();
$events = $parser($html);
```

### Scrape BlackCombat Events

[](#scrape-blackcombat-events)

```
use Cable8mm\MmaScrapers\Http\DefaultHttpClient;
use Cable8mm\MmaScrapers\Sources\BlackCombat\Parsers\ParseEvents;
use Cable8mm\MmaScrapers\Sources\BlackCombat\Scrapers\EventsScraper;

$scraper = new EventsScraper(
    new DefaultHttpClient(),
    new ParseEvents()
);

$events = $scraper->scrape('https://www.blackcombat-official.com/event.php?page=10');
```

### Parse BlackCombat Fights

[](#parse-blackcombat-fights)

```
use Cable8mm\MmaScrapers\Sources\BlackCombat\Parsers\ParseFights;

$html = file_get_contents('event_detail.html');

$parser = new ParseFights();
$fights = $parser($html);
```

### Scrape a Sherdog Fighter

[](#scrape-a-sherdog-fighter)

```
use Cable8mm\MmaScrapers\Http\DefaultHttpClient;
use Cable8mm\MmaScrapers\Sources\Sherdog\Parsers\ParseFighter;
use Cable8mm\MmaScrapers\Sources\Sherdog\Scrapers\FighterScraper;

$scraper = new FighterScraper(
    new DefaultHttpClient(),
    new ParseFighter()
);

$fighter = $scraper->scrapeById(12345);
```

### Resolve a Sherdog Fighter ID

[](#resolve-a-sherdog-fighter-id)

```
use Cable8mm\MmaScrapers\Http\DefaultHttpClient;
use Cable8mm\MmaScrapers\Services\SherdogIdResolver;
use Cable8mm\MmaScrapers\Sources\Sherdog\Parsers\ParseSearchResults;
use Cable8mm\MmaScrapers\Sources\Sherdog\Scrapers\SearchFighterScraper;

$search = new SearchFighterScraper(new DefaultHttpClient());
$parser = new ParseSearchResults();
$resolver = new SherdogIdResolver();

$html = $search->search('Chan Sung Jung');
$candidates = $parser($html);

$sherdogId = $resolver->resolve('Chan Sung Jung', $candidates);
```

### Deduplicate Fights

[](#deduplicate-fights)

```
use Cable8mm\MmaScrapers\Aggregators\FightAggregator;
use Cable8mm\MmaScrapers\Aggregators\FighterAggregator;
use Cable8mm\MmaScrapers\Services\FightDeduplicator;

$deduplicator = new FightDeduplicator(
    new FightAggregator(new FighterAggregator())
);

$deduplicatedFights = $deduplicator->deduplicate($fights);
```

DTOs
----

[](#dtos)

### `EventDTO`

[](#eventdto)

```
new EventDTO(
    name: 'Black Combat 16',
    location: 'Incheon, South Korea',
    date: new DateTimeImmutable('2026-01-31'),
    url: '/eventDetail.php?eventSeq=285',
    externalId: '285'
);
```

### `FighterDTO`

[](#fighterdto)

```
new FighterDTO(
    name: 'Chan Sung Jung',
    nickname: 'The Korean Zombie',
    instagram: 'koreanzombiemma',
    teamname: 'Korean Zombie MMA',
    height: '170cm',
    win: 17,
    lose: 8,
    draw: 0,
    sherdogId: 36155
);
```

### `FightDTO`

[](#fightdto)

```
use Cable8mm\MmaScrapers\Enums\FightMethod;
use Cable8mm\MmaScrapers\Enums\FightStatus;
use Cable8mm\MmaScrapers\Enums\Source;
use Cable8mm\MmaScrapers\Enums\WeightClass;

new FightDTO(
    redFighter: $redFighter,
    blueFighter: $blueFighter,
    source: Source::OFFICIAL,
    status: FightStatus::FINISHED,
    weightClass: WeightClass::FEATHERWEIGHT,
    method: FightMethod::KO,
    round: 1,
    time: '3:14',
    winner: $redFighter,
    fightDate: new DateTimeImmutable('2026-01-31')
);
```

Design Rules
------------

[](#design-rules)

- Keep source implementations isolated under `src/Sources/{SourceName}`.
- Put HTTP access in scrapers, not parsers.
- Keep parsers deterministic: raw HTML in, DTOs out.
- Test parsers with static HTML fixtures.
- Keep storage, API delivery, and application workflows outside this package.

Development
-----------

[](#development)

Run tests:

```
composer test
```

Run Pint:

```
composer lint
```

Generate API documentation:

```
composer apidoc
```

Testing
-------

[](#testing)

Parser and scraper tests use HTML fixtures from `tests/Fixtures`.

```
$html = file_get_contents(__DIR__.'/../../Fixtures/BlackCombat/event_detail.html');

$parser = new ParseFights();
$fights = $parser($html);

$this->assertNotEmpty($fights);
```

Avoid real HTTP calls in tests. Inject a mocked `HttpClientInterface` when testing scrapers.

Contributing
------------

[](#contributing)

1. Keep the existing source/parser/scraper boundaries.
2. Add or update fixtures for parser changes.
3. Add unit tests for new behavior.
4. Run `composer test` and `composer lint` before opening a pull request.

License
-------

[](#license)

MMA Scrapers is open-sourced software licensed under the [MIT license](LICENSE).

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance96

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

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

Total

5

Last Release

35d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c910c874a0263a18f9f976273054cd45faa3ffbcba7891992f4ab52d0656dd93?d=identicon)[Sam Lee](/maintainers/Sam%20Lee)

---

Top Contributors

[![cable8mm](https://avatars.githubusercontent.com/u/2672043?v=4)](https://github.com/cable8mm "cable8mm (33 commits)")

---

Tags

black-combatcrawlerdata-extractiondom-crawlermmaphpscrapersherdogsports-dataufcweb-scrapingphpcrawlerscraperweb-scraping data extractiondom-crawlermmaufcsports-datasherdogblack-combat

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/cable8mm-mma-scrapers/health.svg)

```
[![Health](https://phpackages.com/badges/cable8mm-mma-scrapers/health.svg)](https://phpackages.com/packages/cable8mm-mma-scrapers)
```

###  Alternatives

[craftcms/cms

Craft CMS

3.6k3.6M2.9k](/packages/craftcms-cms)[spatie/crawler

Crawl all internal links found on a website

2.8k17.7M58](/packages/spatie-crawler)[blackfire/player

A powerful web crawler and web scraper with Blackfire support

49517.1k](/packages/blackfire-player)[crwlr/crawler

Web crawling and scraping library.

37116.4k2](/packages/crwlr-crawler)[spatie/laravel-export

Create a static site bundle from a Laravel app

670139.5k6](/packages/spatie-laravel-export)[vdb/php-spider

A configurable and extensible PHP web spider

1.3k184.2k7](/packages/vdb-php-spider)

PHPackages © 2026

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