joefallon/phpdatabase

This package contains simple to use database access layer.

v8.0.1 2025-10-12 23:41 UTC

Requires

• php: >=7.4.0
• ext-ctype: *
• ext-pdo: *

Requires (Dev)

• phpunit/phpunit: ^9.6

MIT

• Joe Fallon

• database

README

By Joe Fallon

A simple library for MySQL database access. It has the following features:

• Full suite of unit tests.
• It can be integrated into any existing project.
• Can be fully understood in just a few moments.
• The library implements the data mapper design patter (a.k.a. table gateway).

Installation

The easiest way to install PhpDatabase is with Composer. Create the following composer.json file and run the php composer.phar install command to install it.

{
    "require": {
        "joefallon/phpdatabase": "*"
    }
}

Usage

There are four main classes are are used to represent all of the relationships within a database:

• AbstractTableGateway
• AbstractJoinTableGateway
• PdoFactory

Entities

An entity is a class that represents a single row within a database. All entities must contain a primary key feild and optionally a created at and updated at field:

• primary key - This is the primary key of the row. It can be named anything.
• created at - This is the date and time that the row was created. It can be named anything.
• updated at - This is the date and time that the row was last updated. It can be named anything.

Additional data fields are added to the entity. Each data field that is added to the entity and should correlate one-to-one with columns within a given table.

Abstract Table Gateway

Instances of subclasses of AbstractTableGateway are used to mediate all access to a table within the database.

Each subclass must implement the abstract methods mapObjectToArray and mapArrayToObject. The method mapObjectToArray is used to convert an entity to an associative array. The names of the keys map to the column names within the database. The method mapArrayToObject is used to convert an associative array that was retrieved from the database into an object.

Additionally, several methods are provided to assist with access to the database. There are four major methods that are used to provide the basic CRUD (i.e. Create, Retrieve, Update, Delete) access to the database. The the following methods are used to provide public access:

• baseCreate($entity)
• baseRetrieve($id)
• baseUpdate($entity)
• baseDelete($id)

Abstract Join-Table Gateway

The class AbstractJoinTableGateway is used mediate access to join tables (i.e. junction table). These tables to represent many-to-many associations.

PDO Factory

The PdoFactory factory class is used to create a PHP PDO object.

Usage

Please refer to the unit tests for a detailed example of how to use this package.

Testing

This project uses PHPUnit for unit testing. Tests are written to be compatible with PHP 7.4+ and the project pins PHPUnit to the 9.6 series (the last major version that supports PHP 7.4).

• Install development dependencies and the test runner with:

  composer install

• Run the test suite from the project root with:

  ./vendor/bin/phpunit

PHPUnit configuration is provided in phpunit.xml and the test bootstrap is tests/bootstrap.php.

If you need to run a single test class or file, pass the path to PHPUnit, for example:

./vendor/bin/phpunit tests/JoeFallon/PhpDatabase/ExampleEntityTests.php

Notes

• The project previously used a small, custom test framework; it has been migrated to PHPUnit and all tests have been updated to use PHPUnit APIs.
• The library targets PHP >= 7.4. If you upgrade PHP beyond 7.4, consider updating PHPUnit to a newer major version and adjusting tests as needed.