PHPackages                             tithely/picomapper - 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. [Database & ORM](/categories/database)
4. /
5. tithely/picomapper

ActiveLibrary[Database & ORM](/categories/database)

tithely/picomapper
==================

Minimalist data mapper built on PicoDb

4.0.0(2mo ago)137.4k—7.1%1[2 PRs](https://github.com/tithely/picomapper/pulls)MITPHPPHP >=8.0CI passing

Since May 7Pushed 2mo ago17 watchersCompare

[ Source](https://github.com/tithely/picomapper)[ Packagist](https://packagist.org/packages/tithely/picomapper)[ RSS](/packages/tithely-picomapper/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (3)Versions (22)Used By (0)

PicoMapper
==========

[](#picomapper)

PicoMapper is a minimalist data mapper built on PicoDb.

[![Run Tests](https://github.com/tithely/picomapper/workflows/Run%20Tests/badge.svg)](https://github.com/tithely/picomapper/workflows/Run%20Tests/badge.svg)

Features
--------

[](#features)

- Built on [PicoDb](https://github.com/elvanto/picodb)
- No configuration files
- License: MIT

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

[](#requirements)

- PHP >= 7.3
- PDO extension
- Sqlite, Mssql, Mysql or Postgresql

Documentation
-------------

[](#documentation)

### Installation

[](#installation)

```
composer require tithely/picomapper
```

### Setup

[](#setup)

```
use PicoDb\Database;
use PicoMapper\Mapper;
use PicoMapper\Definition;

$db = new Database([...]);
$mapper = new Mapper($db);
```

### Concepts

[](#concepts)

#### Definition

[](#definition)

In order to map to or from the database, a mapping must be built from a definition. A definition consists of a table, a primary key (one or more columns that uniquely identifies a record), columns, children (other definitions) and special options that control things like what is considered a deleted record.

Consider a blog system with posts, comments and authors. A post has one author and many comments, a comment has one author. Assuming posts, comments and authors have their own tables, a suitable definition would look like the following:

```
$author = (new Definition('authors'))
    ->withColumns('name')
    ->withDeletionTimestamp('deleted');

$comment = (new Definition('comments'))
    ->withColumns('content')
    ->withOne($author, 'author', 'id', 'author_id')
    ->withDeletionTimestamp('deleted');

$post = (new Definition('posts'))
    ->withColumns('title', 'content')
    ->withOne($author, 'author', 'id', 'author_id')
    ->withMany($comment, 'comments', 'post_id')
    ->withDeletionTimestamp('deleted');

$mapping = $mapper->mapping($post);
```

The second constructor argument for `Definition` is an array of columns that uniquely identify a record within the table. By default it's `['id']`.

Data to be set on insert and update can be set by calling `withCreationData()` and `withModificationData()` respectively. For example if you wanted to add a `date_entered` and `date_modified` columns to the `$post` definition, you would enter it as follows:

```
$post = (new Definition('posts'))
    ->withColumns('title', 'content')
    ->withOne($author, 'author', 'id', 'author_id')
    ->withMany($comment, 'comments', 'post_id')
    ->withCreationData(['date_entered' => gmdate('Y-m-d G:i:s')])
    ->withModificationData(['date_modified' => gmdate('Y-m-d G:i:s')]);
    ->withDeletionTimestamp('deleted');
```

#### Mapping

[](#mapping)

Mappings have the same interface as PicoDb's `Table` class. That is, you can chain conditions and call `findOne()` or `findAll()` to fetch records or `insert()`, `update()`, `remove()` and `save()` to modify records. In all cases, the definition will be used to intelligently return or accept a structured array.

In the example above you could fetch or save a post using the following structured array, and all table relationships will be followed automatically.

```
$post = [
    'id' => 'abc123',
    'author' => [
        'id' => 'zxy321',
        'name' => 'John Doe'
    ],
    'title' => 'Data Mappers Rock',
    'content' => 'They save you time',
    'comments' => [
        [
            'id' => 'def456',
            'post_id' => 'abc123',
            'author' => [
                'id' => 'zxy321',
                'name' => 'John Doe'
            ],
            'content' => 'Did you like my post?'
        ],
        [
            'id' => 'hij789',
            'post_id' => 'abc123',
            'author' => [
                'id' => 'klm012',
                'name' => 'Jane Doe'
            ],
            'content' => 'Nice article!'
        ],
    ]
];

$mapper->save($post);
$saved = $mapper->eq('id', 'abc123')->findOne();

// $saved will be identical in structure to post
```

#### Hooks

[](#hooks)

Hooks are callbacks that can be triggered when a mapping performs the successful insert, update or removal of a record. A hook registered against a mapper will be used for all top level mappings it creates.

```
$mapper->registerHook('updated', function ($table, $key, $updated, $original) {
    printf('Table %s (ID: %s) was updated...', $table, implode(':', $key));
});
```

###  Health Score

55

—

FairBetter than 98% of packages

Maintenance82

Actively maintained with recent releases

Popularity31

Limited adoption so far

Community18

Small or concentrated contributor base

Maturity74

Established project with proven stability

 Bus Factor1

Top contributor holds 50.8% 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 ~137 days

Recently: every ~340 days

Total

19

Last Release

89d ago

Major Versions

0.x-dev → 1.0.02020-12-07

1.0.1 → 2.0.02021-11-18

2.3.0 → 3.0.02025-06-05

3.0.0 → 4.0.02026-02-18

PHP version history (3 changes)0.1.0PHP >=7.0

1.0.0PHP >=7.3

3.0.0PHP >=8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/7cf1c2feb7af5eafbcec1d7258f9909e785bb27bda7ca57e47a2794241bf960c?d=identicon)[joshmcrae](/maintainers/joshmcrae)

---

Top Contributors

[![joshmcrae](https://avatars.githubusercontent.com/u/12324115?v=4)](https://github.com/joshmcrae "joshmcrae (31 commits)")[![bensinclair](https://avatars.githubusercontent.com/u/1043658?v=4)](https://github.com/bensinclair "bensinclair (17 commits)")[![rrigby](https://avatars.githubusercontent.com/u/16025441?v=4)](https://github.com/rrigby "rrigby (7 commits)")[![StewPoll](https://avatars.githubusercontent.com/u/6897645?v=4)](https://github.com/StewPoll "StewPoll (3 commits)")[![Glenn-Ewing](https://avatars.githubusercontent.com/u/1903393?v=4)](https://github.com/Glenn-Ewing "Glenn-Ewing (2 commits)")[![CoreyRDean](https://avatars.githubusercontent.com/u/2882068?v=4)](https://github.com/CoreyRDean "CoreyRDean (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tithely-picomapper/health.svg)

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

###  Alternatives

[doctrine/orm

Object-Relational-Mapper for PHP

10.2k285.3M6.2k](/packages/doctrine-orm)[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k115.1M102](/packages/jdorn-sql-formatter)[illuminate/database

The Illuminate Database package.

2.8k52.4M9.4k](/packages/illuminate-database)[ramsey/uuid-doctrine

Use ramsey/uuid as a Doctrine field type.

90440.3M211](/packages/ramsey-uuid-doctrine)[reliese/laravel

Reliese Components for Laravel Framework code generation.

1.7k3.4M16](/packages/reliese-laravel)[wildside/userstamps

Laravel Userstamps provides an Eloquent trait which automatically maintains `created\_by` and `updated\_by` columns on your model, populated by the currently authenticated user in your application.

7511.7M13](/packages/wildside-userstamps)

PHPackages © 2026

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