PHPackages pinga/db - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. pinga/db ActiveLibrary[Database & ORM](/categories/database) pinga/db ======== Safe and convenient SQL database access in a driver-agnostic way v0.1.3(3y ago)060011MITPHPPHP >=8.1.0 Since Jan 27Pushed 3y agoCompare [ Source](https://github.com/getpinga/db)[ Packagist](https://packagist.org/packages/pinga/db)[ Docs](https://github.com/getpinga/db)[ RSS](/packages/pinga-db/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (4)DependenciesVersions (5)Used By (1) Pinga DB ======== [](#pinga-db) Safe and convenient SQL database access in a driver-agnostic way. Features -------- [](#features) - Convenient interface - Write less code for the same tasks - Safe against SQL injections through the use of prepared statements - Data returned by the server has the correct native types (i.e. no stringified fields) - Driver-agnostic support for multiple database systems Requirements ------------ [](#requirements) - PHP 8.1.0+ - PDO extension Installation ------------ [](#installation) 1. Include the library via Composer: ``` $ composer require pinga/db ``` 2. Include the Composer autoloader: ``` require __DIR__ . '/vendor/autoload.php'; ``` Usage ----- [](#usage) ### Connecting to a database [](#connecting-to-a-database) - From a dynamic database configuration: ``` $dataSource = new \Pinga\Db\PdoDataSource('mysql'); // see "Available drivers for database systems" below $dataSource->setHostname('localhost'); $dataSource->setPort(3306); $dataSource->setDatabaseName('mydatabase'); $dataSource->setCharset('utf8mb4'); $dataSource->setUsername('myusername'); $dataSource->setPassword('mypassword'); $db = \Pinga\Db\PdoDatabase::fromDataSource($dataSource); ``` This is the most convenient way to establish the database connection since the correct DSN will be created for you automatically. You can use the various setters with a fluent interface in order to set up your configuration. You can leave out any options that you don't need and check the `PdoDataSource` class for other available setters. Connections will be created lazily, i.e. they won't consume any resources before they're actually used. All that happens automatically. - From a DSN (data source name): ``` $db = \Pinga\Db\PdoDatabase::fromDsn( new \Pinga\Db\PdoDsn( 'mysql:dbname=my-database;host=localhost', 'my-username', 'my-password' ) ); ``` The parameters of the `PdoDsn` constructor are exactly the same as the parameters to the `PDO` constructor. But if you don't need another `PDO` instance, it's more efficient to go without `PDO` and create this library's instance from a DSN directly. Connections will be created lazily, i.e. they won't consume any resources before they're actually used. - Using an existing `PDO` instance: ``` // $pdo = new PDO('mysql:dbname=my-database;host=localhost;charset=utf8mb4', 'my-username', 'my-password'); $db = \Pinga\Db\PdoDatabase::fromPdo($pdo); ``` This will not cause another database connection to be created but instead re-use the existing connection from the `PDO` instance that you provided. Furthermore, you can benefit from the strong guarantees about this library's behavior and from its convenience while still being able to use your existing `PDO` instance without any side effects. Just pass `true` as the second argument to the `fromPdo` method to completely preserve the original state of your `PDO` instance: ``` $db = \Pinga\Db\PdoDatabase::fromPdo($pdo, true); ``` #### Available drivers for database systems [](#available-drivers-for-database-systems) ``` \Pinga\Db\PdoDataSource::DRIVER_NAME_MYSQL; \Pinga\Db\PdoDataSource::DRIVER_NAME_POSTGRESQL; \Pinga\Db\PdoDataSource::DRIVER_NAME_SQLITE; ``` ### Selecting data [](#selecting-data) When selecting data, you get the desired results with just one method call. And, of course, you can easily choose whether you want to get multiple rows, a single row, a single value only, or a single column from all rows. ``` $rows = $db->select('SELECT id, name FROM books'); // or $rows = $db->select( 'SELECT name, year FROM books WHERE author = ? ORDER BY copies DESC LIMIT 0, 10', [ 'Charles Dickens' ] ); // or $row = $db->selectRow( 'SELECT author, year FROM books WHERE author ? ORDER BY year ASC LIMIT 0, 1', [ 'Miguel de Cervantes' ] ); // or $value = $db->selectValue( 'SELECT year FROM books WHERE name ? AND name ? ORDER BY year DESC LIMIT 0, 1', [ 'Tale of Two Cities', 'Alice in Wonderland' ] ); // or $column = $db->selectColumn( 'SELECT author FROM books ORDER BY copies DESC LIMIT ?, ?', [ 0, 3 ] ); ``` ### Inserting data [](#inserting-data) For simple insertions, you can use a convenient shorthand: ``` $db->insert( 'books', [ // set 'name' => 'Don Quixote', 'author' => 'Miguel de Cervantes', 'year' => 1612 ] ); ``` Does your table have automatically generated primary IDs? Access to these inserted IDs is available with another short method call. The sequence name is only required for *some* database drivers, e.g. PostgreSQL. ``` $newId = $db->getLastInsertId(); // or $newId = $db->getLastInsertId('my-sequence-name'); ``` If you need to execute more advanced statements, please refer to section "Executing statements" below. ### Updating data [](#updating-data) For simple updates, you can use a convenient shorthand as well: ``` $db->update( 'books', [ // set 'author' => 'J. K. Rowling', 'copies' => 2 ], [ // where 'name' => "Harry Potter and the Philosopher's Stone" ] ); ``` Do you want to know how many rows have been updated by this operation? Just grab the return value from the `update` method call. If you need to execute more advanced statements, please refer to section "Executing statements" below. ### Deleting data [](#deleting-data) Again, for simple deletions, you can use a convenient shorthand: ``` $db->delete( 'books', [ // where 'author' => 'C. S. Lewis', 'year' => 1949 ] ); ``` The return value from the `delete` method call will tell you how many rows have been deleted by this operation. If you need to execute more advanced statements, please refer to section "Executing statements" below. ### Executing statements [](#executing-statements) You can execute any arbitrary SQL statements as shown in the following examples: ``` $db->exec( 'INSERT INTO books (name, author, year) VALUES (?, ?, ?) ON DUPLICATE KEY UPDATE copies = copies + 1', [ "Harry Potter and the Philosopher's Stone", 'J. K. Rowling', 1997 ] ); // or $db->exec( "UPDATE books SET name = CONCAT(LEFT(name, 5), ' in ', RIGHT(name, 10)) WHERE year >= ? AND year < ?", [ 1860, 1890 ] ); ``` For every statement that you execute, the return value will be the number of rows affected. If the statement that you're executing is an `INSERT`, you can get the inserted IDs via the `getLastInsertId` method, again. ### Transactions [](#transactions) Transaction controls are as easy as they should be: ``` $db->beginTransaction(); // and later $db->commit(); // or $db->rollBack(); // and optionally $active = $db->isTransactionActive(); ``` ### Error handling [](#error-handling) The methods from this library do not return any error codes. You will be informed about any problem via an exception. ### Input escaping [](#input-escaping) There's no need for you to escape any input manually. Just use the methods as shown above by using placeholders and passing the data separately. All input will be escaped for you automatically. ### Performance profiling [](#performance-profiling) In order to monitor query performance during development, you can enable performance profiling: ``` $db->setProfiler(new \Pinga\Db\SimpleProfiler()); ``` Whenever you want to see the analyzed queries or store them in a log file, you can get all measurements recorded by the profiler as an array: ``` $db->getProfiler()->getMeasurements(); ``` Typically, you'll want to sort the measurements before retrieving them, so that the longest-running queries are listed first: ``` $db->getProfiler()->sort(); ``` ### Server and client information [](#server-and-client-information) In order to retrieve some information about the database server that you're connected to or about the database client used by PHP, you can use one of the following methods: ``` $db->getDriverName(); // e.g. 'MySQL' $db->getServerInfo(); // e.g. 'Uptime: 82196 Threads: 1 Questions: 2840 Slow queries: 0 Opens: 23 Flush tables: 1 Open tables: 33 Queries per second avg: 0.736' $db->getServerVersion(); // e.g. '5.5.5-10.1.13-MariaDB' $db->getClientVersion(); // e.g. 'mysqlnd 5.0.1-dev' ``` ### Listeners [](#listeners) #### Connection established [](#connection-established) ``` $db->addOnConnectListener(function (\Delight\Db\PdoDatabase $db) { // do something }); ``` Contributing ------------ [](#contributing) All contributions are welcome! If you wish to contribute, please create an issue first so that your feature, problem or question can be discussed. License ------- [](#license) This project is licensed under the terms of the [MIT License](https://opensource.org/licenses/MIT). ### Health Score 26 — LowBetter than 43% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity17 Limited adoption so far Community11 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 65% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~2 days Total 4 Last Release 1201d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/f8f87416e80fdfb906a1e9d206c9a20584ae27bdd20815170b69efd49e8e9436?d=identicon)[getpinga](/maintainers/getpinga) --- Top Contributors [![getpinga](https://avatars.githubusercontent.com/u/121483313?v=4)](https://github.com/getpinga "getpinga (39 commits)")[![ocram](https://avatars.githubusercontent.com/u/1681478?v=4)](https://github.com/ocram "ocram (21 commits)") --- Tags databasemysqlsqlitepostgresqlsqlpdopgsql ### Embed Badge ![Health badge](/badges/pinga-db/health.svg) ``` [![Health](https://phpackages.com/badges/pinga-db/health.svg)](https://phpackages.com/packages/pinga-db) ``` ### Alternatives [doctrine/dbal Powerful PHP database abstraction layer (DBAL) with many features for database schema introspection and management. 9.7k578.4M5.6k](/packages/doctrine-dbal)[aura/sqlquery Object-oriented query builders for MySQL, Postgres, SQLite, and SQLServer; can be used with any database connection library. 4572.9M34](/packages/aura-sqlquery)[ezsql/ezsql Advance database access library. Make interacting with a database ridiculously easy. An universal interchangeable CRUD system. 86946.7k](/packages/ezsql-ezsql)[atlas/query Object-oriented query builders and performers for MySQL, Postgres, SQLite, and SQLServer. 41249.0k7](/packages/atlas-query)[aura/sqlschema Provides facilities to read table names and table columns from a database using PDO. 41234.1k4](/packages/aura-sqlschema)[delight-im/db Safe and convenient SQL database access in a driver-agnostic way 49156.8k7](/packages/delight-im-db) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)