PHPackages joomla/database - 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. [Framework](/categories/framework) 4. / 5. joomla/database ActiveJoomla-package[Framework](/categories/framework) joomla/database =============== Joomla Database Package 4.0.0(9mo ago)30347.9k↓25.6%37[6 issues](https://github.com/joomla-framework/database/issues)[6 PRs](https://github.com/joomla-framework/database/pulls)9GPL-2.0-or-laterPHPPHP ^8.3.0CI passing Since Jun 4Pushed 2mo ago21 watchersCompare [ Source](https://github.com/joomla-framework/database)[ Packagist](https://packagist.org/packages/joomla/database)[ Docs](https://github.com/joomla-framework/database)[ RSS](/packages/joomla-database/feed)WikiDiscussions 4.x-dev Synced 1mo ago READMEChangelog (10)Dependencies (15)Versions (49)Used By (9)Security (1) The Database Package [![Build Status](https://github.com/joomla-framework/database/actions/workflows/ci.yml/badge.svg?branch=3.x-dev)](https://github.com/joomla-framework/database) [![Build status](https://camo.githubusercontent.com/82ab9501915565d7ff3ad8b47c9a1a64c44ed62134a256d74607e22c6c0543f0/68747470733a2f2f63692e6170707665796f722e636f6d2f6170692f70726f6a656374732f7374617475732f6d3265683735613167396b39793539753f7376673d74727565)](https://ci.appveyor.com/project/joomla/database) ======================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================= [](#the-database-package--) [![Latest Stable Version](https://camo.githubusercontent.com/f598639ce2269a6e20c0cc407dcd00ca6ff5ecf3a4d33cb1119a616a426055a2/68747470733a2f2f706f7365722e707567782e6f72672f6a6f6f6d6c612f64617461626173652f762f737461626c65)](https://packagist.org/packages/joomla/database)[![Total Downloads](https://camo.githubusercontent.com/f5a2b444990e43b0732797ef5ce8710fa5daeff542f11a4ab6fbe993c1038dc8/68747470733a2f2f706f7365722e707567782e6f72672f6a6f6f6d6c612f64617461626173652f646f776e6c6f616473)](https://packagist.org/packages/joomla/database)[![Latest Unstable Version](https://camo.githubusercontent.com/1d5a40805f468ca3a0ed0c23788d28c5616f5a69950b024fa7aa9788c9c5365f/68747470733a2f2f706f7365722e707567782e6f72672f6a6f6f6d6c612f64617461626173652f762f756e737461626c65)](https://packagist.org/packages/joomla/database)[![License](https://camo.githubusercontent.com/6b18505c78a40b22c164ef76ab96c41cfdcefe2eb25451dfc494af3ff7a189ab/68747470733a2f2f706f7365722e707567782e6f72672f6a6f6f6d6c612f64617461626173652f6c6963656e7365)](https://packagist.org/packages/joomla/database) Introduction ------------ [](#introduction) The *Database* package is designed to manage the operations of data management through the use of a generic database engine. ``` // Example for initialising a database driver in a custom application class. use Joomla\Application\AbstractApplication; use Joomla\Database; class MyApplication extends AbstractApplication { /** * Database driver. * * @var Database\DatabaseDriver * @since 1.0 */ protected $db; protected function doExecute() { // Do stuff } protected function initialise() { // Make the database driver. $dbFactory = new Database\DatabaseFactory; $this->db = $dbFactory->getDriver( $this->get('database.driver'), array( 'host' => $this->get('database.host'), 'user' => $this->get('database.user'), 'password' => $this->get('database.password'), 'port' => $this->get('database.port'), 'socket' => $this->get('database.socket'), 'database' => $this->get('database.name'), ) ); } } ``` Escaping Strings and Input -------------------------- [](#escaping-strings-and-input) Strings must be escaped before using them in queries (never trust any variable input, even if it comes from a previous database query from your own data source). This can be done using the `escape` and the `quote` method. The `escape` method will generally backslash unsafe characters (unually quote characters but it depends on the database engine). It also allows for optional escaping of additional characters (such as the underscore or percent when used in conjunction with a `LIKE` clause). The `quote` method will escape a string and wrap it in quotes, however, the escaping can be turned off which is desirable in some situations. The `quote` method will also accept an array of strings and return an array quoted and escaped (unless turned off) string. ``` function search($title) { // Get the database driver from the factory, or by some other suitable means. $db = DatabaseDriver::getInstance($options); // Search for an exact match of the title, correctly sanitising the untrusted input. $sql1 = 'SELECT * FROM #__content WHERE title = ' . $db->quote($title); // Special treatment for a LIKE clause. $search = $db->quote($db->escape($title, true) . '%', false); $sql2 = 'SELECT * FROM #__content WHERE title LIKE ' . $search; if (is_array($title)) { $sql3 = 'SELECT * FROM #__content WHERE title IN (' . implode(',', $db->quote($title)) . ')'; } // Do the database calls. } ``` In the first case, the title variable is simply escaped and quoted. Any quote characters in the title string will be prepended with a backslash and the whole string will be wrapped in quotes. In the second case, the example shows how to treat a search string that will be used in a `LIKE` clause. In this case, the title variable is manually escaped using `escape` with a second argument of `true`. This will force other special characters to be escaped (otherwise you could set yourself up for serious performance problems if the user includes too many wildcards). Then, the result is passed to the `quote` method but escaping is turned off (because it has already been done manually). In the third case, the title variable is an array so the whole array can be passed to the `quote` method (this saves using a closure and a ) Shorthand versions are available the these methods: - `q` can be used instead of `quote` - `qn` can be used instead of `quoteName` - `e` can be used instead of `escape` These shorthand versions are also available when using the `Database\DatabaseQuery` class. Iterating Over Results ---------------------- [](#iterating-over-results) The `Database\DatabaseIterator` class allows iteration over database results ``` $db = DatabaseDriver::getInstance($options); $iterator = $db->setQuery( $db->createQuery()->select('*')->from('#__content') )->getIterator(); foreach ($iterator as $row) { // Deal with $row } ``` It allows also to count the results. ``` $count = count($iterator); ``` Logging ------- [](#logging) `Database\DatabaseDriver` implements the `Psr\Log\LoggerAwareInterface` so is ready for integrating with a logging package that supports that standard. Drivers log all errors with a log level of `LogLevel::ERROR`. If debugging is enabled (using `setDebug(true)`), all queries are logged with a log level of `LogLevel::DEBUG`. The context of the log include: - **sql** : The query that was executed. - **category** : A value of "databasequery" is used. ### An example to log error by Monolog [](#an-example-to-log-error-by-monolog) Add this to `composer.json` ``` { "require" : { "monolog/monolog" : "1.*" } } ``` Then we push Monolog into Database instance. ``` use Monolog\Logger; use Monolog\Handler\StreamHandler; use Monolog\Processor\PsrLogMessageProcessor; // Create logger object $logger = new Logger('sql'); // Push logger handler, use DEBUG level that we can log all information $logger->pushHandler(new StreamHandler('path/to/log/sql.log', Logger::DEBUG)); // Use PSR-3 logger processor that we can replace {sql} with context like array('sql' => 'XXX') $logger->pushProcessor(new PsrLogMessageProcessor); // Push into DB $db->setLogger($logger); $db->setDebug(true); // Do something $db->setQuery('A WRONG QUERY')->execute(); ``` This is the log file: ``` [2014-07-29 07:25:22] sql.DEBUG: A WRONG QUERY {"sql":"A WRONG QUERY","category":"databasequery","trace":[...]} [] [2014-07-29 07:36:01] sql.ERROR: Database query failed (error #42000): SQL: 42000, 1064, You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'A WRONG QUERY' at line 1 {"code":42000,"message":"SQL: 42000, 1064, You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'A WRONG QUERY' at line 1"} [] ``` Installation via Composer ------------------------- [](#installation-via-composer) Add `"joomla/database": "~4.0"` to the require block in your composer.json and then run `composer install`. ``` { "require": { "joomla/database": "~4.0" } } ``` Alternatively, you can simply run the following from the command line: ``` composer require joomla/database "~4.0" ``` If you want to include the test sources, use ``` composer require --prefer-source joomla/database "~4.0" ``` ### Health Score 64 — FairBetter than 99% of packages Maintenance67 Regular maintenance activity Popularity49 Moderate usage in the ecosystem Community38 Small or concentrated contributor base Maturity91 Battle-tested with a long release history Bus Factor1 Top contributor holds 50.9% 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 ~110 days Recently: every ~79 days Total 43 Last Release 90d ago Major Versions 1.7.1 → 2.0.0-beta2020-06-05 1.8.0 → 2.0.0-rc2021-07-13 2.1.1 → 3.0.02023-10-06 2.2.1 → 3.4.12025-04-06 3.4.3 → 4.0.02025-07-24 PHP version history (8 changes)1.0-alphaPHP >=5.3.10 1.4.0PHP >=5.3.10|>=7.0 1.5.0PHP ^5.3.10|~7.0 2.0.0-betaPHP ^7.2.5 2.0.0-rcPHP ^7.2.5|^8.0 2.1.1PHP ^7.2.5|~8.0.0|~8.1.0 3.0.0PHP ^8.1.0 4.0.0PHP ^8.3.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/305a2164440014dcef9ac681c139fe5e8a1ce1d7a8c3b3cfb828497729a4c70e?d=identicon)[wilsonge](/maintainers/wilsonge) --- Top Contributors [![mbabker](https://avatars.githubusercontent.com/u/368545?v=4)](https://github.com/mbabker "mbabker (630 commits)")[![wilsonge](https://avatars.githubusercontent.com/u/1986000?v=4)](https://github.com/wilsonge "wilsonge (86 commits)")[![Hackwar](https://avatars.githubusercontent.com/u/313866?v=4)](https://github.com/Hackwar "Hackwar (69 commits)")[![nibra](https://avatars.githubusercontent.com/u/827605?v=4)](https://github.com/nibra "nibra (67 commits)")[![photodude](https://avatars.githubusercontent.com/u/10253980?v=4)](https://github.com/photodude "photodude (57 commits)")[![HLeithner](https://avatars.githubusercontent.com/u/1497730?v=4)](https://github.com/HLeithner "HLeithner (55 commits)")[![richard67](https://avatars.githubusercontent.com/u/7413183?v=4)](https://github.com/richard67 "richard67 (53 commits)")[![twister65](https://avatars.githubusercontent.com/u/26852967?v=4)](https://github.com/twister65 "twister65 (47 commits)")[![frankmayer](https://avatars.githubusercontent.com/u/825497?v=4)](https://github.com/frankmayer "frankmayer (39 commits)")[![dongilbert](https://avatars.githubusercontent.com/u/718028?v=4)](https://github.com/dongilbert "dongilbert (26 commits)")[![alikon](https://avatars.githubusercontent.com/u/181681?v=4)](https://github.com/alikon "alikon (15 commits)")[![PhilETaylor](https://avatars.githubusercontent.com/u/400092?v=4)](https://github.com/PhilETaylor "PhilETaylor (14 commits)")[![SharkyKZ](https://avatars.githubusercontent.com/u/7325021?v=4)](https://github.com/SharkyKZ "SharkyKZ (14 commits)")[![heelc29](https://avatars.githubusercontent.com/u/66922325?v=4)](https://github.com/heelc29 "heelc29 (12 commits)")[![ianmacl](https://avatars.githubusercontent.com/u/176534?v=4)](https://github.com/ianmacl "ianmacl (10 commits)")[![andrepereiradasilva](https://avatars.githubusercontent.com/u/9630530?v=4)](https://github.com/andrepereiradasilva "andrepereiradasilva (7 commits)")[![joomla-jenkins](https://avatars.githubusercontent.com/u/929228?v=4)](https://github.com/joomla-jenkins "joomla-jenkins (5 commits)")[![eddieajau](https://avatars.githubusercontent.com/u/700871?v=4)](https://github.com/eddieajau "eddieajau (4 commits)")[![kamil-tekiela](https://avatars.githubusercontent.com/u/6583064?v=4)](https://github.com/kamil-tekiela "kamil-tekiela (4 commits)")[![zero-24](https://avatars.githubusercontent.com/u/2596554?v=4)](https://github.com/zero-24 "zero-24 (3 commits)") --- Tags databasejoomlajoomla-frameworkmysqlphppostgresqlsql-serversqliteframeworkdatabasejoomla ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/joomla-database/health.svg) ``` [![Health](https://phpackages.com/badges/joomla-database/health.svg)](https://phpackages.com/packages/joomla-database) ``` ### Alternatives [joomla/application Joomla Application Package 23404.8k11](/packages/joomla-application)[joomla/string Joomla String Package 181.9M13](/packages/joomla-string)[joomla/di Joomla DI Package 15391.2k11](/packages/joomla-di)[joomla/input Joomla Input Package 10408.8k15](/packages/joomla-input)[joomla/registry Joomla Registry Package 16468.6k20](/packages/joomla-registry) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)