Download the PHP package getpastthemonkey/db-link without Composer

DB Link

DB Link is a lightweight database abstraction layer for PHP, partly inspired by Django.

Please note that DB Link does not manage the database structure for you. If you update a model class, you must update the database schema accordingly, and vice versa.

Configuration

For the database connection, DB Link will look for a function called dblink_create_pdo() that must be defined by the user. The function must have the following signature:

A basic usage might be the following implementation:

Make sure that this function is included before calling any DB Link functions. If the function is not found, a LogicException will be thrown.

Creating Models

You can create your models by extending the Model class. The get_table_name() function should return the name of the relevant database table as a string. The get_attributes() function should return an array, where the keys are the database column names, and the values are instances of a Field subclass.

Currently, only the field types IntegerField and CharField are supported, but more field types are planned for future updates, such as TextField, DateField, or DateTimeField. In the meantime, use CharField for these purposes.

Run Queries

Here is a showcase of the available query functionality.

All of these examples return a Query object. The function calls may be chained arbitrarily. The Query class implements the Countable interface, so the count() function can be used to obtain the number of returned rows. The Query class also implements the Iterator interface, so the query results may be obtained by iterating over the Query instance.

List of Filters

The following table shows all available filter classes. All of them are in the \Getpastthemonkey\DbLink\filters namespace.

Load Single Model Instance

If you filter for a single instance, you can use the get() method of the Query class.

If the query does not return an entry, a ObjectDoesNotExistException will be thrown. If the query returns more than one entry, a MultipleObjectsReturnedException will be thrown.

Accessing Model Attributes

The Model class implements the ArrayAccess interface, and it overloads most magic methods. Thus, there are two ways of accessing model attributes.

The first way of accessing the model attributes is via the ArrayAccess interface, which allows array-style access.

The second option is to use the magic method overloads by accessing the attributes in a class-member style. Note that this option might give warnings in IDEs, as the attributes are not defined in the class.

Updating Model Attributes

Updating model attributes is possible in the same two ways as accessing model attributes: Either through the ArrayAccess interface or the overloaded magic methods.

Here is an example that uses the ArrayAccess interface to update an attribute and save it back to the database. Saving internally also validated the current field values.

To check if an instance is valid without saving it, call validate() instead of save(). If the instance is invalid, a ValidationException will be thrown. If it instead is valid, nothing will happen.

Creating New Instances

By calling the constructor of a Model subclass, a new model instance is created. All fields hold the defined default value. If a field does not have a default value, it will be NULL. Note that the new instance only exists in the PHP runtime, but it is not saved in the database. To add the instance to the database, you must call save().

Here is an example of how to create a new User and save it to the database.

Deleting Instances

Single model instances can be deleted by calling the delete() function. Note that the database entry will be deleted, but the model instance still exists in the code.

Here is an example for how to delete a user with ID 123.

Bulk deletion is supported by calling delete() on a Query instance. All entries returned by the query will be deleted.

Here is an example for how to delete all users that are not administrators.

Troubleshooting

As DB Link is a new project, there is not yet a complete guide to frequently asked questions or problems. If you have any questions or problems, do not hesitate to open a GitHub issue.