Download the PHP package rrigby/picomapper without Composer

PicoMapper

PicoMapper is a minimalist data mapper built on PicoDb.

Features

• Built on PicoDb
• No configuration files
• License: MIT

Requirements

• PHP >= 8.3
• PDO extension
• Sqlite, Mssql, Mysql or Postgresql

Documentation

Installation

Setup

Concepts

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:

Authors are shared between posts and comments, so the author definition is read-only: it's fetched with the post but never written.

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

Relationships

withOne() and withMany() take the child definition, the property name, the column in the child table, and the column in the parent table (id by default):

When the relationship goes through a join table, use withOneByJoin() or withManyByJoin(). After the parent column, pass the join table, the join table column that references the parent, then the join table column that references the child:

Primary keys

Call useAutoIncrement() to let the database generate a single column primary key on insert. Any value in the data is ignored, and the generated ID is set on the record passed to the children and hooks:

Read-only definitions

A definition marked with readOnly() is fetched as normal but never written. Inserts, updates and removals skip it, which is useful for lookup data such as the authors above.

Soft deletes

With withDeletionTimestamp(), removing a record sets that column to the current UTC time instead of deleting the row, and fetches ignore records where it is set. Extra columns to set on removal can be added with withDeletionData():

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:

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.

• save() updates the record if its primary key exists and inserts it otherwise. The data must include the primary key.
• update() throws a MappingException if the primary key is missing or the record doesn't exist.
• Children are synchronised on update: new children are inserted, changed ones updated, and children missing from the data are removed.
• Writes that touch several tables run in a transaction, unless one is already open.

Create a new mapping for each query, as conditions added to a mapping stay on it.

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.

Every hook receives the table name and the record's primary key values. The remaining arguments depend on the event:

Transactions and debugging

$mapper->table('posts') returns a plain PicoDb Table for queries that don't need mapping.

Development