PHPackages                             cocur/nqm - 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. cocur/nqm

ActiveLibrary[Database & ORM](/categories/database)

cocur/nqm
=========

Named Query Manager helps you SQL organise queries in files.

v0.4(10y ago)275.6k2MITPHPPHP >=5.4

Since May 28Pushed 3y ago4 watchersCompare

[ Source](https://github.com/cocur/nqm)[ Packagist](https://packagist.org/packages/cocur/nqm)[ RSS](/packages/cocur-nqm/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (6)Dependencies (6)Versions (12)Used By (0)

cocur/nqm
=========

[](#cocurnqm)

> Named Query Manager (NQM) helps you organise SQL queries in files.

[![Build Status](https://camo.githubusercontent.com/686aaf611df615412f3bcb7e9e80f4f28f2f1299b49efb79d773b83ae2e4e944/687474703a2f2f696d672e736869656c64732e696f2f7472617669732f636f6375722f6e716d2e737667)](https://travis-ci.org/cocur/nqm)[![Code Coverage](https://camo.githubusercontent.com/909fa2c7d44656eacbc78591334d01595e0cc007aba6189931ce4a0d2331bed8/687474703a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f636f6375722f6e716d2e737667)](https://coveralls.io/r/cocur/nqm)

Features
--------

[](#features)

- Wrapper for PDO
- Stores queries in the filesystem
- Caches queries in arrays or using APC
- Compatible with PHP >= 5.4 and HHVM

Installation
------------

[](#installation)

You can install `cocur/nqm` using Composer:

```
$ composer require cocur/nqm:@stable
```

*Tip: Use a concrete [version](https://github.com/cocur/nqm/releases) instead of `@stable`.*

Usage
-----

[](#usage)

In order to use NQM you need to initialise the `Cocur\NQM\NQM` class with an instance of `\PDO` and a query loader. NQM comes with a FilesystemQueryLoader query loader.

```
use Cocur\NQM\NQM;
use Cocur\NQM\QueryLoader\FilesystemQueryLoader;

$loader = new FilesystemQueryLoader(__DIR__.'/queries');
$pdo = new \PDO(...);
$nqm = new NQM($pdo, $loader);
```

After you have initialised the `NQM` object you can use it. Currently the class has three public methods to retrieve a query, prepare a statement or execute a statement.

The following command will return the SQL query stored in `./queries/find-all-users.sql`.

```
$nqm->getQuery('find-all-users');
```

NQM can also return a `\PDOStatement` object directly:

```
$stmt = $nqm->prepare('find-all-users');
$stmt->execute();
```

Or you can immediately execute the statement:

```
$stmt = $nqm->execute('find-user-by-id', [':id' => 42]);
```

### Query Cache

[](#query-cache)

To speed up loading of queries you can use the `Cocur\NQM\QueryLoader\CacheQueryLoader` to cache queries. The cache class implements the same interface as the other query loaders and the constructor accepts an instance of `QueryLoaderInterface`. If a query does not exist in the cache, the cache uses this loader to load the query. For example,

```
use Cocur\NQM\QueryLoader\CacheQueryLoader;
use Cocur\NQM\QueryLoader\FilesystemQueryLoader;

$loader = new FilesystemQueryLoader(__DIR__.'/queries');
$cache = new CacheQueryLoader($loader);

$pdo = new \PDO(...);
$nqm = new NQM($pdo, $cache);
```

### APC Query Cache

[](#apc-query-cache)

The `CacheQueryLoader` query loader stores cached queries in an array and therefore only on a per-request basis. While this often suffices in CLI applications for web apps it would be better to cache queries over multiple requests.

```
use Cocur\NQM\QueryLoader\ApcQueryLoader;
use Cocur\NQM\QueryLoader\FilesystemQueryLoader;

$loader = new FilesystemQueryLoader(__DIR__.'/queries');
$apc = new ApcQueryLoader($loader);

$pdo = new \PDO(...);
$nqm = new NQM($pdo, $apc);
```

Additionally if you have queries that you use more than once in a single request you can stack multiple query loaders. In the following example NQM will load queries from the array cache or if it's not cached it will look in the APC cache. As a last resort NQM loads the query from the filesystem.

```
use Cocur\NQM\QueryLoader\ApcQueryLoader;
use Cocur\NQM\QueryLoader\CacheQueryLoader;
use Cocur\NQM\QueryLoader\FilesystemQueryLoader;

$loader = new FilesystemQueryLoader(__DIR__.'/queries');
$apc = new ApcQueryLoader($loader);
$cache = new CacheQueryLoader($apc);

$pdo = new \PDO(...);
$nqm = new NQM($pdo, $cache);
```

### Array Query Loader

[](#array-query-loader)

Stores the queries in an array.

```
use Cocur\NQM\QueryLoader\ArrayQueryLoader;

$loader = new ArrayQueryLoader(['foo' => 'SELECT ...;']);
```

### Query Collection

[](#query-collection)

Sometimes you have multiple queries that are always executed together. For example, a `DROP TABLE`, `CREATE TABLE`sequence or if you have to create temporary tables for especially complex queries. Since PDO accepts only a single SQL statement per statement, you can use `QueryCollection` to execute multiple queries. Queries must be separated by `#;`, which must be placed on its own line.

```
DROP TABLE IF EXISTS users;
#;
CREATE TABLE users (...);
```

```
use Cocur\NQM\QueryCollection;

$collection = NQMQueryCollection($nqm);
// Just prepare the statements
$statements = $collection->prepare('drop-and-create-user-table');

// Prepare and execute the statements
$statements = $collection->execute('drop-and-create-user-table', ['foo'=>'bar']);
```

The `prepare()` and `execute()` methods return both a `Cocur\NQM\StatementCollection`. This collection class implements `\ArrayAccess` and `\Countable`.

```
$statements->all(); // -> \PDOStatement[]
$statements->first(); // -> \PDOStatement
$statements->last(); // -> \PDOStatement
```

### Doctrine Bridge

[](#doctrine-bridge)

If you don't have a `PDO` object, but a Doctrine `EntityManager` object you can use the Doctrine bridge to create a new `NQM` object.

```
use Cocur\NQM\Bridge\Doctrine\NQMFactory;

$nqm = NQMFactory::createFromEntityManager($entityManager, $queryLoader);
// NQM(...) object
```

Change log
----------

[](#change-log)

### Version 0.4 (6 October 2015)

[](#version-04-6-october-2015)

- Add `ArrayQueryLoader`

### Version 0.3 (16 February 2015)

[](#version-03-16-february-2015)

- Add support for query collections

### Version 0.2 (11 February 2015)

[](#version-02-11-february-2015)

- Add Doctrine bridge

### Version 0.1.2 (3 February 2015)

[](#version-012-3-february-2015)

- Moved development packages to `require-dev` in `composer.json`

### Version 0.1.1 (26 August 2014)

[](#version-011-26-august-2014)

- Renamed query loader class names

### Version 0.1 (28 May 2014)

[](#version-01-28-may-2014)

- Initial release

Author
------

[](#author)

#### [Florian Eckerstorfer](http://florian.ec) [![Support Florian](https://camo.githubusercontent.com/5d8be0f60738f32a93128d94dec1fa7ee75e6dce71b110ec7fbbf6d217c0a150/687474703a2f2f696d672e736869656c64732e696f2f6769747469702f666c6f7269616e65636b657273746f726665722e737667)](https://www.gittip.com/FlorianEckerstorfer/)

[](#florian-eckerstorfer-)

- [Twitter](http://twitter.com/Florian_)
- [App.net](http://app.net/florian)

License
-------

[](#license)

The MIT license applies to `cocur/nqm`. For the full copyright and license information, please view the LICENSE file distributed with this source code.

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity28

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~334 days

Recently: every ~628 days

Total

10

Last Release

1359d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a80f9fc61cd3a7d7779e8f120b458ca4d18fdd885d719bb77d3379b96bf714d9?d=identicon)[florianeckerstorfer](/maintainers/florianeckerstorfer)

---

Top Contributors

[![florianeckerstorfer](https://avatars.githubusercontent.com/u/149201?v=4)](https://github.com/florianeckerstorfer "florianeckerstorfer (2 commits)")

---

Tags

databasesqlpdoqueery

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/cocur-nqm/health.svg)

```
[![Health](https://phpackages.com/badges/cocur-nqm/health.svg)](https://phpackages.com/packages/cocur-nqm)
```

###  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)[ifsnop/mysqldump-php

PHP version of mysqldump cli that comes with MySQL

1.3k5.5M69](/packages/ifsnop-mysqldump-php)[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)[paragonie/easydb

Easy-to-use database abstraction

744273.4k23](/packages/paragonie-easydb)[clouddueling/mysqldump-php

PHP version of mysqldump cli that comes with MySQL

1.3k22.9k](/packages/clouddueling-mysqldump-php)[ezsql/ezsql

Advance database access library. Make interacting with a database ridiculously easy. An universal interchangeable CRUD system.

86946.7k](/packages/ezsql-ezsql)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)