PHPackages                             meritum/serialization - 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. [Parsing & Serialization](/categories/parsing)
4. /
5. meritum/serialization

ActiveLibrary[Parsing & Serialization](/categories/parsing)

meritum/serialization
=====================

Pluggable object serialization for the Meritum ecosystem with item, collection, and pagination support

1.0.0(1mo ago)037MITPHPPHP ^8.4CI passing

Since Jun 12Pushed 1mo agoCompare

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

READMEChangelogDependencies (5)Versions (2)Used By (0)

meritum/serialization
=====================

[](#meritumserialization)

Pluggable object serialization with item, collection, and pagination support.

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

[](#requirements)

- PHP 8.4+
- `georgeff\kernel` ^1.6

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

[](#installation)

```
composer require meritum/serialization
```

Overview
--------

[](#overview)

The package is built around three concepts:

- **Serializer** — transforms a model into a plain array
- **Resource** — wraps a model (or iterable) with its serializer and optional metadata
- **Formatter** — accepts a resource, applies a format strategy, and returns a `JsonSerializable` envelope

The format strategy controls the output shape. Two strategies are provided out of the box, and you can supply your own by implementing `StrategyInterface`.

Serializers
-----------

[](#serializers)

Implement `SerializerInterface` to define how a model maps to an array:

```
use Meritum\Serialization\SerializerInterface;

final class UserSerializer implements SerializerInterface
{
    public function serialize(mixed $data): array
    {
        return [
            'id'    => $data->id,
            'name'  => $data->name,
            'email' => $data->email,
        ];
    }
}
```

To embed a related model, call the related serializer's `serialize()` directly. The formatter does not recurse — related data must be resolved to a plain array inside `serialize()`:

```
final class PostSerializer implements SerializerInterface
{
    public function serialize(mixed $data): array
    {
        return [
            'id'     => $data->id,
            'title'  => $data->title,
            'author' => new UserSerializer()->serialize($data->author),
        ];
    }
}
```

Formatter
---------

[](#formatter)

`Formatter` is the entry point. Construct it with a `StrategyInterface` and call `format()` with an `Item` or `Collection`:

```
use Meritum\Serialization\Formatter;
use Meritum\Serialization\Resource\Item;
use Meritum\Serialization\Strategy\DataArrayStrategy;

$formatter = new Formatter(new DataArrayStrategy());

$envelope = $formatter->format(new Item($user, new UserSerializer()));

// $envelope implements JsonSerializable — pass it directly to any JSON response
return new JsonResponse($envelope);
```

Item
----

[](#item)

Wrap a single model in an `Item`:

```
use Meritum\Serialization\Resource\Item;

$item = new Item($user, new UserSerializer());
$envelope = $formatter->format($item);
```

With `DataArrayStrategy` (the default), the output is:

```
{
  "data": {
    "id": 1,
    "name": "Mike",
    "email": "mike@georgeff.co"
  }
}
```

Collection
----------

[](#collection)

Wrap an iterable of models in a `Collection`. Any `iterable` is accepted, including generators:

```
use Meritum\Serialization\Resource\Collection;

$collection = new Collection($users, new UserSerializer());
$envelope = $formatter->format($collection);
```

Output:

```
{
  "data": [
    { "id": 1, "name": "Mike", "email": "mike@georgeff.co" },
    { "id": 2, "name": "Steve", "email": "steve@georgeff.co" }
  ]
}
```

Metadata
--------

[](#metadata)

Both `Item` and `Collection` accept call-site metadata via `addMeta()`. Multiple calls chain fluently. The `meta` key is omitted from the output entirely when empty:

```
$item = (new Item($user, new UserSerializer()))
    ->addMeta('version', 2)
    ->addMeta('requestId', 'abc123');

$envelope = $formatter->format($item);
```

```
{
  "data": { "id": 1, "name": "Mike", "email": "mike@georgeff.co" },
  "meta": { "version": 2, "requestId": "abc123" }
}
```

Pagination
----------

[](#pagination)

### Cursor pagination

[](#cursor-pagination)

Implement `CursorInterface` and attach it to a `Collection` with `setCursor()`:

```
use Meritum\Serialization\Pagination\CursorInterface;

final class MyCursor implements CursorInterface
{
    public function getPrevious(): ?string { ... }
    public function getNext(): ?string { ... }
    public function getPerPage(): int { ... }
}
```

```
$collection = (new Collection($users, new UserSerializer()))
    ->setCursor($cursor);

$envelope = $formatter->format($collection);
```

```
{
  "limit": 25,
  "previous": null,
  "next": "eyJpZCI6MjZ9",
  "data": [...]
}
```

### Offset pagination

[](#offset-pagination)

Implement `PaginatorInterface` and attach it with `setPaginator()`:

```
use Meritum\Serialization\Pagination\PaginatorInterface;

final class MyPaginator implements PaginatorInterface
{
    public function getCurrentPage(): int { ... }
    public function getLastPage(): int { ... }
    public function getTotal(): int { ... }
    public function getCount(): int { ... }
    public function getPerPage(): int { ... }
}
```

```
$collection = (new Collection($users, new UserSerializer()))
    ->setPaginator($paginator);

$envelope = $formatter->format($collection);
```

```
{
  "total": 100,
  "count": 20,
  "limit": 20,
  "current": 2,
  "last": 5,
  "data": [...]
}
```

`setCursor()` and `setPaginator()` are mutually exclusive — setting one clears the other. Pagination keys always appear before `data` in the output.

A bridge package for `meritum/database` paginators will provide concrete implementations of both interfaces.

Output strategies
-----------------

[](#output-strategies)

### `DataArrayStrategy` (default)

[](#dataarraystrategy-default)

Items are wrapped under a `data` key. Collections always include a `data` key. This is the default strategy registered by `SerializationModule`.

### `ArrayStrategy`

[](#arraystrategy)

Items are returned as a bare array with no `data` wrapper. Collections behave the same as `DataArrayStrategy` — the difference only applies to items.

```
use Meritum\Serialization\Formatter;
use Meritum\Serialization\Strategy\ArrayStrategy;

$formatter = new Formatter(new ArrayStrategy());

$envelope = $formatter->format(new Item($user, new UserSerializer()));
// {"id": 1, "name": "Mike", "email": "mike@georgeff.co"}
```

### Custom strategies

[](#custom-strategies)

Implement `StrategyInterface` to take full control of the output format:

```
use Meritum\Serialization\EnvelopeInterface;
use Meritum\Serialization\Envelope;
use Meritum\Serialization\Resource\ItemInterface;
use Meritum\Serialization\Resource\CollectionInterface;
use Meritum\Serialization\Strategy\StrategyInterface;

final class MyStrategy implements StrategyInterface
{
    public function item(ItemInterface $item): EnvelopeInterface
    {
        $data = ['result' => $item->getSerializer()->serialize($item->getData())];

        if ([] !== $item->getMeta()) {
            $data['meta'] = $item->getMeta();
        }

        return new Envelope($data);
    }

    public function collection(CollectionInterface $collection): EnvelopeInterface
    {
        $data = $collection->getPagination();
        $data['results'] = [];

        foreach ($collection->getData() as $model) {
            $data['results'][] = $collection->getSerializer()->serialize($model);
        }

        if ([] !== $collection->getMeta()) {
            $data['meta'] = $collection->getMeta();
        }

        return new Envelope($data);
    }
}
```

Kernel integration
------------------

[](#kernel-integration)

`SerializationModule` registers `FormatterInterface` in the kernel container. It uses `DataArrayStrategy` by default. To swap in a custom strategy, register `StrategyInterface` before booting:

```
use Meritum\Serialization\SerializationModule;
use Meritum\Serialization\Strategy\StrategyInterface;

$kernel->define(StrategyInterface::class, fn () => new MyStrategy())->share();
$kernel->addModule(new SerializationModule());
$kernel->boot();

$formatter = $kernel->getContainer()->get(FormatterInterface::class);
```

To run multiple formatters with different strategies in the same application, bypass the module and define them manually:

```
use Meritum\Serialization\Formatter;
use Meritum\Serialization\Strategy\ArrayStrategy;
use Meritum\Serialization\Strategy\DataArrayStrategy;

$kernel->define('formatter.default', fn () => new Formatter(new DataArrayStrategy()))->share();
$kernel->define('formatter.bare',    fn () => new Formatter(new ArrayStrategy()))->share();
```

License
-------

[](#license)

MIT

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance90

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

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

45d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c8147ce1d901e9fa2ec95d6408e5862025211f9ae60131e41fb115a5a0916ce4?d=identicon)[georgeff](/maintainers/georgeff)

---

Top Contributors

[![MikeGeorgeff](https://avatars.githubusercontent.com/u/6169468?v=4)](https://github.com/MikeGeorgeff "MikeGeorgeff (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/meritum-serialization/health.svg)

```
[![Health](https://phpackages.com/badges/meritum-serialization/health.svg)](https://phpackages.com/packages/meritum-serialization)
```

###  Alternatives

[sauladam/shipment-tracker

Parses tracking information for several carriers, like UPS, USPS, DHL and GLS by simply scraping the data. No need for any kind of API access.

9843.5k](/packages/sauladam-shipment-tracker)[jstewmc/rtf

Read and write Rich Text Format (RTF) documents with PHP

45153.1k6](/packages/jstewmc-rtf)[tcds-io/php-jackson

A lightweight, flexible object serializer for PHP, inspired by FasterXML/jackson

113.2k10](/packages/tcds-io-php-jackson)

PHPackages © 2026

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