PHPackages                             ecourty/kodi-nfo-parser - 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. [Image & Media](/categories/media)
4. /
5. ecourty/kodi-nfo-parser

ActiveLibrary[Image & Media](/categories/media)

ecourty/kodi-nfo-parser
=======================

A PHP library to parse and serialize Kodi NFO files (Movie, TvShow, Episode, Artist, Album, MusicVideo, MovieSet).

1.0.0(2mo ago)00MITPHPPHP >=8.3CI passing

Since Mar 7Pushed 2mo agoCompare

[ Source](https://github.com/EdouardCourty/kodi-nfo-parser)[ Packagist](https://packagist.org/packages/ecourty/kodi-nfo-parser)[ RSS](/packages/ecourty-kodi-nfo-parser/feed)WikiDiscussions main Synced 1mo ago

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

kodi-nfo-parser
===============

[](#kodi-nfo-parser)

[![PHP CI](https://github.com/EdouardCourty/kodi-nfo-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/EdouardCourty/kodi-nfo-parser/actions/workflows/ci.yml)

A framework-agnostic PHP library for parsing and serializing [Kodi NFO files](https://kodi.wiki/view/NFO_files) — the XML metadata files that Kodi stores alongside your media.

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

[](#table-of-contents)

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Supported NFO Types](#supported-nfo-types)
- [NFO Variants](#nfo-variants)
- [Serialization](#serialization)
- [Error Handling](#error-handling)
- [Development](#development)

---

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

[](#installation)

```
composer require ecourty/kodi-nfo-parser
```

**Requirements**: PHP >= 8.3
**Extensions**: `ext-simplexml`

---

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

[](#quick-start)

### Parsing a file

[](#parsing-a-file)

```
use Ecourty\KodiNfoParser\NfoParser;
use Ecourty\KodiNfoParser\Model\MovieNfo;

$parser = new NfoParser();
$nfo = $parser->parseFile('/path/to/movie.nfo');

if ($nfo instanceof MovieNfo) {
    echo $nfo->title;       // "Inception"
    echo $nfo->year;        // 2010
    echo $nfo->plot;        // "A thief who steals..."
}
```

### Parsing a string

[](#parsing-a-string)

```
$nfo = $parser->parseString(file_get_contents('tvshow.nfo'));
```

---

Supported NFO Types
-------------------

[](#supported-nfo-types)

All 7 Kodi NFO types are supported. Each is parsed into a typed readonly model.

NFO TypeModelRoot XML tagMovie`MovieNfo```TV Show`TvShowNfo```Episode`EpisodeNfo```Artist`ArtistNfo```Album`AlbumNfo```Music Video`MusicVideoNfo```Movie Set`MovieSetNfo```### Multi-episode files

[](#multi-episode-files)

When an `.nfo` file contains multiple `` blocks, the parser returns a single `EpisodeNfo` with all episodes accessible via `$nfo->episodes`:

```
use Ecourty\KodiNfoParser\Model\EpisodeNfo;

$nfo = $parser->parseFile('s01e01e02.nfo');

if ($nfo instanceof EpisodeNfo) {
    foreach ($nfo->episodes as $episode) {
        echo $episode->title;   // each episode's title
        echo $episode->season;  // season number
        echo $episode->episode; // episode number
    }
}
```

---

NFO Variants
------------

[](#nfo-variants)

The parser automatically detects the variant of each NFO file — no configuration needed.

VariantContentDescription**Metadata**XML onlyStandard NFO with full media metadata**Parsing**URL onlySingle-line scraper URL; Kodi fetches metadata remotely**Combination**XML + trailing URLMetadata NFO with an additional scraper URL appendedFor Parsing NFOs, you can also build a model directly:

```
$nfo = $parser->parseParsingNfo('https://www.imdb.com/title/tt1375666/');
```

On Combination NFOs, the scraper URL is available on the model:

```
echo $nfo->scraperUrl; // "https://www.imdb.com/title/tt1375666/"
```

---

Serialization
-------------

[](#serialization)

Any model can be serialized back to a valid NFO XML string using `NfoSerializer`:

```
use Ecourty\KodiNfoParser\NfoSerializer;
use Ecourty\KodiNfoParser\Model\MovieNfo;

$serializer = new NfoSerializer();

$movie = new MovieNfo(
    title: 'Inception',
    year: 2010,
    plot: 'A thief who steals corporate secrets...',
);

$xml = $serializer->serialize($movie);
file_put_contents('movie.nfo', $xml);
```

---

Error Handling
--------------

[](#error-handling)

All exceptions extend `Ecourty\KodiNfoParser\Exception\NfoException`.

ExceptionWhen thrown`NfoFileNotFoundException`The file does not exist or is not readable`NfoFileReadException`The file could not be read`InvalidNfoException`The content is not valid NFO XML`UnknownNfoTypeException`The root XML tag is not a known Kodi NFO type```
use Ecourty\KodiNfoParser\Exception\NfoException;
use Ecourty\KodiNfoParser\Exception\NfoFileNotFoundException;

try {
    $nfo = $parser->parseFile('/path/to/file.nfo');
} catch (NfoFileNotFoundException $e) {
    // file missing
} catch (NfoException $e) {
    // any other NFO-related error
}
```

---

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

[](#development)

```
# Install dependencies
composer install

# Run tests
composer test

# Run PHPStan (level max)
composer phpstan

# Run CS fixer
composer cs-fix
```

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance94

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

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

Unknown

Total

1

Last Release

63d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/3150ffb131124e5f03272d9ed8084c514f18fff6aafff1a5973c016993f6ef66?d=identicon)[ecourty](/maintainers/ecourty)

---

Top Contributors

[![EdouardCourty](https://avatars.githubusercontent.com/u/37371516?v=4)](https://github.com/EdouardCourty "EdouardCourty (2 commits)")

---

Tags

parserserializermetadatamedianfokodi

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ecourty-kodi-nfo-parser/health.svg)

```
[![Health](https://phpackages.com/badges/ecourty-kodi-nfo-parser/health.svg)](https://phpackages.com/packages/ecourty-kodi-nfo-parser)
```

###  Alternatives

[s9e/text-formatter

Multi-purpose text formatting and markup library. Plugins offer support for BBCodes, Markdown, emoticons, HTML, embedding third-party media (YouTube, etc...), enhanced typography and more.

2413.1M29](/packages/s9e-text-formatter)[essence/essence

Extracts information about medias on the web, like youtube videos, twitter statuses or blog articles.

770562.9k3](/packages/essence-essence)[dereuromark/media-embed

A PHP library to deal with all those media services around, parsing their URLs and embedding their audio/video content in websites.

182530.3k11](/packages/dereuromark-media-embed)[cohensive/embed

Media Embed (for Laravel or as a standalone).

120370.4k](/packages/cohensive-embed)[classic-o/nova-media-library

Tool and field that will let you managing files and add them to the posts

154172.0k](/packages/classic-o-nova-media-library)[tomatophp/filament-media-manager

Manage your media files using spatie media library with easy to use GUI for FilamentPHP

14543.9k3](/packages/tomatophp-filament-media-manager)

PHPackages © 2026

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