Download the PHP package tccl/database without Composer

database - v1.11.0

This library provides a really simple PDO database connection wrapper in addition to providing several database abstraction mechanisms for representing database entities and schemas. This package is designed to eliminate boilerplate associated with connecting to the database and managing credentials. Note that this library does not provide fine-tuned query abstractions.

While targeting PDO lets the library use any database engine, the abstractions code has been tested and developed for use with MySQL. That isn't to say it won't necessarily work with another database engine though. You might have more of a problem with compatibility with the Entity framework classes.

Primary authors:

Roger Gee <[email protected]>

Installing

This library is available as a composer package. Require 'tccl/database' in your composer.json file and then install.

Classes

TCCL\Database\DatabaseConnection
    Wraps PDO to represent a database connection

TCCL\Database\Entity
    Provides an abstraction for managing a single entity

TCCL\Database\EntityInsertSet
    Provides an abstraction for inserting multiple Entity objects

TCCL\Database\EntityList
    Provides an abstraction for manipulating lists of database entities

TCCL\Database\Schema
    Provides abstraction for defining and installing schemas

TCCL\Database\ReflectionEntity
    Provides an Entity abstraction where metadata is obtained from doc comments

TCCL\Database\ReflectionEntityTrait
    Used with ReflectionEntity

Usage

[DatabaseConnection]

Use a DatabaseConnection instance to manage a database connection. The connection parameters are to be stored in the $GLOBALS superglobal. The bucket under this array is arbitrary and may be arbitrarily nested. The structure of the bucket is an indexed array with three parts like:

[ReflectionEntity]

Works like Entity but uses reflection to gather table/field metadata. In this way, you do not register individual fields but supply doc comments that denote the entity fields/table info.

When you subclass a ReflectionEntity, you must use the ReflectionEntityTrait in the same class.

/**

• Represents a 'fruit' entity.

• @table fruit_record */ class Fruit extends ReflectionEntity { use ReflectionEntityTrait;

  /**

  • The entity ID.
  • @field id
  • @key */ private $id;

  /**

  • The fruit's common name.
  • @field common_name */ private $name;

  /**

  • The fruit's scientific name.
  • @field scientific_name */ private $scientificName;

  /**

  • The number of calories.
  • @field calories */ private $calories;

  public function __construct($id = null) { $this->id = $id;

  $db = /* Get DatabaseConnection instance... */;
  parent::__construct($db);

  } }

You can inherit ReflectionEntity types. The ReflectionEntity will inherit schema. If schema are specified in both parent and child classes, then the functionality will merge. The most-derived class has precedence when it comes to table names, fields, ETC.

[Schema]

This class provides a way to manage schemas programmatically. Currently, the functionality only supports creating initial schema, not applying database updates.

A "Schema" object implements an array interface, so you can denote the schema using a PHP array. Since the order of table definitions is important, you must define the tables in the array in the correct order. Table field metadata (i.e. types, constraints, ETC.) are specified in this array. You should use the constants defined in class Schema for field sizes and types. Here is an example that demonstrates all of the capabilities:

$schema = new Schema;
$schema['table'] = [
    // Specify primary keys like this. You may specify more than one to get
    // a compound primary key
    'primary keys' => [
        // Field definitions...

        // A SERIAL_TYPE gets AUTO_INCREMENT. You may optionally specify a
        // "size" and "not null" properties.
        'id' => [
            'type' => Schema::SERIAL_TYPE,
            'not null' => true,
        ],
    ],

    // Non-constrained fields are specified here.
    'fields' => [
        // Field definitions...

        // Integer types can have a "size".
        'thing1' => [
            'type' => Schema::INTEGER_TYPE,
            'size' => Schema::SIZE_TINY,
        ],
        'thing2' => [
            'type' => Schema::INTEGER_TYPE,
            'not null' => true,
            'default' => 345,
        ],

        // String types may have a "length".
        'string1' => [
            'type' => Schema::VARCHAR_TYPE,
            'not null' => false,
            'length' => 1024,
        ],

        // NUMERIC types *MUST* specify "precision" and "scale".
        'net_worth' => [
            'type' => Schema::NUMERIC_TYPE,
            'precision' => 9,
            'scale' => 2,
        ],

        'batting_average' => [
            'type' => Schema::FLOAT_TYPE,
        ],
        'memoir' => [
            'type' => Schema::BLOB_TYPE,
            'size' => Schema::SIZE_BIG,
        ],
    ],

    // Foreign keys are specified like this. Do not specify the foreign
    // key field in the "fields" or any other section.
    'foreign keys' => [
        'other_table_id' => [
            // "key" is a single field definition
            'key' => [
                'type' => DatabaseSchema::INTEGER_TYPE,
            ],

            'table' => 'other_table',
            'field' => 'id',
        ],
    ],

    // Unique keys are specified like this. These reference existing fields.
    'unique keys' => [
        // UNIQUE keys may be compound.
        'unique_thing1' => ['thing1'],
    ],

    // Indexes are specified like this. These reference existing fields.
    'indexes' => [
        'index_thing2' => ['thing2'],
    ],
];

To commit the schema, call the "execute" method:

// $conn = ...
$schema->execute($conn);

To test your schema generation, just use the object like a string:

echo "MY SCHEMA: $schema";