php-arr-core

A canonical domain model for the *arr ecosystem.

php-arr-core provides shared domain models, value objects, enums and normalization logic used across *arr service SDKs such as Sonarr, Radarr, Jellyseerr and NZBGet.

The goal is to eliminate duplicated DTOs, inconsistent status handling and ad-hoc mappings between services that conceptually model the same things.

---

Why does this exist?

The *arr ecosystem is highly cohesive:

• Sonarr, Radarr, Jellyseerr and NZBGet all model:
  • media
  • downloads
  • queues
  • file sizes
  • progress
  • statuses
• Yet each service exposes these concepts using:
  • different naming
  • different units
  • different status values
  • different lifecycle semantics

This results in:

• duplicated DTOs
• repeated status mapping logic
• fragile integrations
• inconsistent developer experience

php-arr-core solves this by defining one canonical domain model that all *arr SDKs map to.

---

What this package is

✅ Pure PHP (no framework dependencies) ✅ Canonical domain models ✅ Value objects (FileSize, Duration, Progress, etc.) ✅ Normalized enums and statuses ✅ Mapping helpers and contracts

---

What this package is NOT

❌ HTTP clients ❌ API DTOs ❌ Guzzle, Curl, or PSR-18 implementations ❌ Service-specific assumptions

---

Core design principles

1. Canonical domain > API representation

APIs change. Domains evolve slowly.

This package models what things are, not how services expose them.

---

2. Value objects over primitives

Anything that:

• has units
• appears in multiple services
• requires conversion or logic

…is modeled as a value object.

Examples:

• FileSize
• Duration
• Progress

---

3. Status normalization is centralized

Each service uses its own status vocabulary.

All normalization happens once, in core.

SDKs should never contain switch or if blocks for statuses.

---

4. Mapping happens at the boundary

Service SDKs are responsible for mapping their API DTOs into php-arr-core domain objects.

Core never depends on service-specific code.

---

Package structure

src/
├── Domain/
│   ├── Media/
│   ├── Download/
│   ├── Request/
│   └── User/
├── ValueObject/
│   ├── FileSize.php
│   ├── Duration.php
│   ├── Progress.php
│   └── ArrId.php
├── Enum/
│   ├── MediaStatus.php
│   ├── DownloadStatus.php
│   └── Service.php
├── Mapping/
│   ├── StatusNormalizer.php
│   └── ServiceCapabilities.php

---

Example usage

use MartinCamen\ArrCore\Domain\Download\DownloadItem;
use MartinCamen\ArrCore\ValueObject\FileSize;
use MartinCamen\ArrCore\ValueObject\Progress;
use MartinCamen\ArrCore\Enum\DownloadStatus;

$item = new DownloadItem(
    id: ArrId::fromInt(123),
    name: 'Example.Movie.2024',
    size: FileSize::fromGB(8.5),
    progress: Progress::fromPercentage(42),
    status: DownloadStatus::Downloading
);

---

How service SDKs integrate

Each service SDK:

1. Defines API-specific DTOs
2. Fetches raw data via HTTP
3. Maps DTOs → php-arr-core domain models

Example:

$queueItems = $sonarr->queue();

$coreItems = array_map(
    fn($item) => SonarrToCoreMapper::mapQueueItem($item),
    $queueItems
);

---

Supported services

This package is designed to be used by:

• Sonarr SDK
• Radarr SDK
• Jellyseerr SDK
• NZBGet SDK
• Prowlarr SDK (planned)

---

Versioning & stability

php-arr-core follows semantic versioning.

Breaking changes only occur when:

• a domain concept changes
• a value object’s behavior changes

New services and fields should be additive whenever possible.

---

Contributing

Contributions are welcome, especially:

• new value objects
• improved normalization
• additional service mappings

Before adding new models, consider:

Is this a domain concept or an API detail?

If unsure, open an issue.