Download the PHP package linio/database without Composer

Linio Database

Linio Database is a component of the Linio Framework. It aims to abstract database access by wrapping PDO and providing helper methods to speed up development.

Install

The recommended way to install Linio Database is through composer.

Tests

Run the test suite in Docker with PHP 8.3.36 and MySQL; PHP does not need to be installed on the host:

$ docker compose run --build --rm tests

If your network uses a custom CA certificate bundle, set SSL_CERT_FILE to that bundle. When Docker Bake requests permission to read the bundle outside the project, build with access limited to that file, then run the tests:

Docker mounts the certificate bundle as a build secret to download Composer dependencies. The temporary combined CA bundle is removed in the same build step and is not stored in the image.

The MySQL container remains running after the tests finish. Stop and remove it with:

$ docker compose down

To run the test suite directly on the host instead, install the Composer dependencies and run PHPUnit:

$ composer install
$ vendor/bin/phpunit

Code coverage in Docker

Rebuild the test image after updating the Dockerfile. Xdebug is installed but disabled for normal test runs. Enable it to generate coverage reports:

The coverage directory is mounted from the host so the reports remain available after the container exits. Open the HTML report on macOS with open coverage/html/index.html. Reports are excluded from Git and Docker builds.

Usage

Roles

For performance reasons, you might want to use slave databases for read queries while sending write queries to the master database. When creating a connection, you can specify the connection role: ROLE_MASTER or ROLE_SLAVE. Only one master connection is allowed.

You can have multiple slave connections. The weight parameter is used to balance the queries among the slaves. Database servers capable of handling more load should have higher weight paramaters.

In order to force a read query to use the master connection, use the parameter forceMasterConnection when using the fetch methods.

Safe Mode

When you use read replicas to improve the performance in your database, in a master-slave setup, the replication lag between the instances may cause some issues when you try to read data that you have recently modified.

The safe mode option guarantees that, once you have used the master connection to issue a query, every query from this moment on will use the same connection for reads.

To prevent replication lag issues, this library uses the safe mode by default. To override this behavior, set the $safeMode parameter to false when instantiating the DatabaseManager object.

Methods

addConnection

getConnections

fetchAll

fetchOne

fetchValue

fetchKeyPairs

fetchColumn

fetchLazy

In this example, when this while loop reached the end of the result set, the fetch() method will return an empty array.

execute

escapeValue

escapeValues

Exceptions

Linio\Component\Database\Exception\DatabaseConnectionException

Reasons:

• Invalid driver name
• Invalid connections parameters
• Error when trying to establish a connection to the database

Linio\Component\Database\Exception\InvalidQueryException

Reasons:

• Lost connection to the database before creating the statement
• Malformed SQL query
• Wrong table or field names

Linio\Component\Database\Exception\FetchException

Reasons:

• Lost connection to the database after creating the statement

Linio\Component\Database\Exception\TransactionException

Reasons:

• Failure to begin, commit or rollback a transaction

Linio\Component\Database\Exception\DatabaseException

Reasons:

• All exceptions extend from this
• Non-specific errors

Drivers

DatabaseManager::MYSQL

Adapter options:

• host string
• port int
• dbname string
• username string
• password string
• pdo_attributes array optional

DatabaseManager::PGSQL

Adapter options:

• host string
• port int
• dbname string
• username string
• password string
• pdo_attributes array optional

DatabaseManager::SQLITE

Adapter options:

• filepath

DatabaseManager::SQLSRV

Adapter options:

• host string
• port int
• dbname string
• username string
• password string
• pdo_attributes array optional