PHPackages                             ray/aura-sql-module - 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. ray/aura-sql-module

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

ray/aura-sql-module
===================

aura/sql module for Ray.Di

1.17.1(3mo ago)9457.3k↓19.1%166MITPHPPHP ^8.1CI passing

Since Dec 24Pushed 2mo ago4 watchersCompare

[ Source](https://github.com/ray-di/Ray.AuraSqlModule)[ Packagist](https://packagist.org/packages/ray/aura-sql-module)[ RSS](/packages/ray-aura-sql-module/feed)WikiDiscussions 1.x Synced 3d ago

READMEChangelog (10)Dependencies (22)Versions (56)Used By (6)

Ray.AuraSqlModule
=================

[](#rayaurasqlmodule)

[![codecov](https://camo.githubusercontent.com/0023a9b111f8c3066d33ae331b9cd4fdfd33f68269487560cdf27adfb212f67c/68747470733a2f2f636f6465636f762e696f2f67682f7261792d64692f5261792e4175726153716c4d6f64756c652f6272616e63682f312e782f67726170682f62616467652e7376673f746f6b656e3d6763576166747a6f5870)](https://codecov.io/gh/ray-di/Ray.AuraSqlModule)[![Type Coverage](https://camo.githubusercontent.com/3b1889854cc9321e245b2488894f1fc889031d08338c53ad89a7a10f2009470f/68747470733a2f2f73686570686572642e6465762f6769746875622f7261792d64692f5261792e4175726153716c4d6f64756c652f636f7665726167652e737667)](https://shepherd.dev/github/ray-di/Ray.AuraSqlModule)[![Continuous Integration](https://github.com/ray-di/Ray.AuraSqlModule/actions/workflows/continuous-integration.yml/badge.svg?branch=2.x)](https://github.com/ray-di/Ray.AuraSqlModule/actions/workflows/continuous-integration.yml)

An [Aura.Sql](https://github.com/auraphp/Aura.Sql) Module for [Ray.Di](https://github.com/koriym/Ray.Di)

Versions
--------

[](#versions)

Two lines are maintained. **Pick by how your application declares metadata** — the required PHP version follows from the Aura.Sql major you depend on, not from this package directly.

- **1.13.x** — use this if your application still relies on **Doctrine annotations** (`@Transactional`, `@Named` in docblocks). Depends on `ray/di` ^2.13, which ships `doctrine/annotations`. Supports Aura.Sql 4 and 5.
- **1.x** (current) — **PHP attributes only** (`#[Transactional]`). Depends on `ray/di` ^2.16+, which dropped `doctrine/annotations`. Supports Aura.Sql 5 (PHP 8.1–8.3) and Aura.Sql 6 (PHP 8.4+, covering the PDO BC break introduced in PHP 8.4).

Composer resolves the matching Aura.Sql major automatically from your PHP version, so you normally don't need to think about it — the decisive question is annotations vs attributes.

To pin to the maintenance line, use a tilde or wildcard constraint — `^1.13` would also match 1.14+ and pull you onto the 1.x line:

```
{
    "require": {
        "ray/aura-sql-module": "~1.13.1"
    }
}
```

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

[](#installation)

```
composer require ray/aura-sql-module
```

Getting started
---------------

[](#getting-started)

### Module install

[](#module-install)

```
use Ray\Di\AbstractModule;
use Ray\AuraSqlModule\AuraSqlModule;
use Ray\AuraSqlModule\AuraSqlQueryModule;

class AppModule extends AbstractModule
{
    protected function configure()
    {
        $this->install(
            new AuraSqlModule(
                'mysql:host=localhost;dbname=test',
                'username',
                'password',
                'slave1,slave2,slave3', // optional slave server list
                $options,               // optional key=>value array of driver-specific connection options
                $queries                // Queries to execute after the connection.
            )
        );
    }
}
```

Use AuraSqlEnvModule to get the value from the environment variable each time at runtime, instead of specifying the value directly.

```
$this->install(
    new AuraSqlEnvModule(
        'PDO_DSN',             // getenv('PDO_DSN')
        'PDO_USER',            // getenv('PDO_USER')
        'PDO_PASSWORD',        // getenv('PDO_PASSWORD')
        'PDO_SLAVE',           // getenv('PDO_SLAVE')
        $options,              // optional key=>value array of driver-specific connection options
        $queries               // Queries to execute after the connection.
    )
);
```

Replication
-----------

[](#replication)

Installing `AuraSqlReplicationModule` using a `connection locator` for master/slave connections.

```
use Ray\Di\AbstractModule;
use Ray\AuraSqlModule\AuraSqlModule;
use Aura\Sql\ConnectionLocator;
use Aura\Sql\Connection;

class AppModule extends AbstractModule
{
    protected function configure()
    {
        $locator = new ConnectionLocator;
        $locator->setWrite('master', new Connection('mysql:host=localhost;dbname=master', 'id', 'pass'));
        $locator->setRead('slave1',  new Connection('mysql:host=localhost;dbname=slave1', 'id', 'pass'));
        $locator->setRead('slave2',  new Connection('mysql:host=localhost;dbname=slave2', 'id', 'pass'));
        $this->install(new AuraSqlReplicationModule($locator));
    }
}
```

You will now have a slave db connection when using HTTP GET, or a master db connection in other HTTP methods.

Multiple DB
-----------

[](#multiple-db)

You may want to inject different connection destinations on the same DB interface with `#[Named($qualifier)]` attribute. Two modules are provided. `NamedPdoModule` is for non replication use. and `AuraSqlReplicationModule` is for replication use.

```
#[Inject]
public function setLoggerDb(#[Named('log_db')] ExtendedPdoInterface $pdo)
{
    // ...
}
```

### with no replication

[](#with-no-replication)

Use `NamedPdoModule ` to inject different named `Pdo` instance for **non** Replication use. For instance, This module install `log_db` named `Pdo` instance.

```
class AppModule extends AbstractModule
{
    protected function configure()
    {
        $this->install(new NamedPdoModule('log_db', 'mysql:host=localhost;dbname=log', 'username', 'password'));
    }
}
```

Or

```
class AppModule extends AbstractModule
{
    protected function configure()
    {
        $this->install(new NamedPdoEnvModule('log_db', 'LOG_DSN', 'LOG_USERNAME', 'LOG_PASSWORD'));
    }
}
```

### with replication

[](#with-replication)

You can set `$qualifier` in 2nd parameter of AuraSqlReplicationModule.

```
class AppModule extends AbstractModule
{
    protected function configure()
    {
        $this->install(new AuraSqlReplicationModule($locator, 'log_db'));
    }
}
```

Transaction
-----------

[](#transaction)

Any method marked with `#[Transactional]` will have a transaction started before, and ended after it is called.

```
use Ray\AuraSqlModule\Annotation\WriteConnection; // important
use Ray\AuraSqlModule\Annotation\Transactional;   // important

class User
{
    public $pdo;

    #[WriteConnection, Transactional]
    public function write()
    {
         // $this->pdo->rollback(); when exception thrown.
    }
}
```

Query Builder
-------------

[](#query-builder)

[Aura.SqlQuery](https://github.com/auraphp/Aura.SqlQuery) provides query builders for MySQL, Postgres, SQLite, and Microsoft SQL Server. Following four interfaces are bound and can be injected via constructor:

- `Aura\SqlQuery\Common\SelectInterface`
- `Aura\SqlQuery\Common\InsertInterface`
- `Aura\SqlQuery\Common\UpdateInterface`
- `Aura\SqlQuery\Common\DeleteInterface`

```
use Aura\SqlQuery\Common\SelectInterface;
use Aura\Sql\ExtendedPdoInterface;

class UserRepository
{
    public function __construct(
        private readonly SelectInterface $select,
        private readonly ExtendedPdoInterface $pdo
    ) {}

    public function findById(int $id): array
    {
        $statement = $this->select
            ->distinct()                    // SELECT DISTINCT
            ->cols([                        // select these columns
                'id',                       // column name
                'name AS namecol',          // one way of aliasing
                'col_name' => 'col_alias',  // another way of aliasing
                'COUNT(foo) AS foo_count'   // embed calculations directly
            ])
            ->from('users AS u')            // FROM these tables
            ->where('id = :id')
            ->getStatement();

        return $this->pdo->fetchAssoc($statement, ['id' => $id]);
    }
}
```

### Multiple Query Builders

[](#multiple-query-builders)

```
use Aura\SqlQuery\Common\SelectInterface;
use Aura\SqlQuery\Common\InsertInterface;
use Aura\SqlQuery\Common\UpdateInterface;
use Aura\Sql\ExtendedPdoInterface;

class UserService
{
    public function __construct(
        private readonly SelectInterface $select,
        private readonly InsertInterface $insert,
        private readonly UpdateInterface $update,
        private readonly ExtendedPdoInterface $pdo
    ) {}

    public function createUser(array $userData): int
    {
        $statement = $this->insert
            ->into('users')
            ->cols($userData)
            ->getStatement();

        $this->pdo->perform($statement, $this->insert->getBindValues());

        return (int) $this->pdo->lastInsertId();
    }

    public function updateUser(int $id, array $userData): bool
    {
        $statement = $this->update
            ->table('users')
            ->cols($userData)
            ->where('id = :id')
            ->bindValue('id', $id)
            ->getStatement();

        return $this->pdo->perform($statement, $this->update->getBindValues());
    }
}
```

Pagination
----------

[](#pagination)

Pagination service is provided for both `ExtendedPdo` raw sql and `Select` query builder.

**ExtendedPdo**

```
use Ray\AuraSqlModule\Pagerfanta\AuraSqlPagerFactoryInterface;
use Aura\Sql\ExtendedPdoInterface;

class UserListService
{
    public function __construct(
        private readonly AuraSqlPagerFactoryInterface $pagerFactory,
        private readonly ExtendedPdoInterface $pdo
    ) {}

    public function getUserList(int $page): Page
    {
        $sql = 'SELECT * FROM users WHERE active = :active';
        $params = ['active' => 1];
        $pager = $this->pagerFactory->newInstance($this->pdo, $sql, $params, 10, '/?page={page}&category=users');

        return $pager[$page];
    }
}
```

**Select query builder**

```
use Ray\AuraSqlModule\Pagerfanta\AuraSqlQueryPagerFactoryInterface;
use Aura\SqlQuery\Common\SelectInterface;
use Aura\Sql\ExtendedPdoInterface;

class ProductListService
{
    public function __construct(
        private readonly AuraSqlQueryPagerFactoryInterface $queryPagerFactory,
        private readonly SelectInterface $select,
        private readonly ExtendedPdoInterface $pdo
    ) {}

    public function getProductList(int $page, string $category): Page
    {
        $select = $this->select
            ->from('products')
            ->where('category = :category')
            ->bindValue('category', $category);

        $pager = $this->queryPagerFactory->newInstance($this->pdo, $select, 10, '/?page={page}&category=' . $category);

        return $pager[$page];
    }
}
```

An array access with page number returns `Page` value object.

```
/* @var Pager \Ray\AuraSqlModule\Pagerfanta\Page */

// $page->data // sliced data
// $page->current;
// $page->total
// $page->hasNext
// $page->hasPrevious
// $page->maxPerPage;
// (string) $page // pager html
```

It is iterable.

```
foreach ($page as $item) {
    // ...
}
```

### View

[](#view)

The view template can be changed with binding. See more at [Pagerfanta](https://github.com/whiteoctober/Pagerfanta#views).

```
use Pagerfanta\View\Template\TemplateInterface;
use Pagerfanta\View\Template\TwitterBootstrap3Template;
use Ray\AuraSqlModule\Annotation\PagerViewOption;

$this->bind(TemplateInterface::class)->to(TwitterBootstrap3Template::class);
$this->bind()->annotatedWith(PagerViewOption::class)->toInstance($pagerViewOption);
```

Profile
-------

[](#profile)

To log SQL execution, install `AuraSqlProfileModule`. It will be logged by a logger bound to the [PSR-3](https://www.php-fig.org/psr/psr-3/) logger. This example binds a minimal function logger created in an anonymous class.

```
class DevModule extends AbstractModule
{
    protected function configure()
    {
        // ...
        $this->install(new AuraSqlProfileModule());
        $this->bind(LoggerInterface::class)->toInstance(
            new class extends AbstractLogger {
                /** @inheritDoc */
                public function log($level, $message, array $context = [])
                {
                    $replace = [];
                    foreach ($context as $key => $val) {
                        if (! is_array($val) && (! is_object($val) || method_exists($val, '__toString'))) {
                            $replace['{' . $key . '}'] = $val;
                        }
                    }

                    error_log(strtr($message, $replace));
                }
            }
        );
    }
}
```

###  Health Score

64

—

FairBetter than 99% of packages

Maintenance82

Actively maintained with recent releases

Popularity46

Moderate usage in the ecosystem

Community30

Small or concentrated contributor base

Maturity85

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 95.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 ~76 days

Recently: every ~39 days

Total

55

Last Release

80d ago

PHP version history (9 changes)1.2.0PHP >=5.5.0

1.5.0PHP ~5.6|~7.0

1.6.4PHP >=7.0.0

1.8.0PHP >=7.2

1.9.0PHP ^7.3 || ^8.0

1.11.0PHP ^7.4 || ^8.0

1.14.0PHP ^8.4

1.13.4PHP ^8.0

1.17.0PHP ^8.1

### Community

Maintainers

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

---

Top Contributors

[![koriym](https://avatars.githubusercontent.com/u/529021?v=4)](https://github.com/koriym "koriym (534 commits)")[![jingu](https://avatars.githubusercontent.com/u/892913?v=4)](https://github.com/jingu "jingu (5 commits)")[![yutakachiba](https://avatars.githubusercontent.com/u/5999747?v=4)](https://github.com/yutakachiba "yutakachiba (3 commits)")[![fiahfy](https://avatars.githubusercontent.com/u/7123916?v=4)](https://github.com/fiahfy "fiahfy (3 commits)")[![piotzkhider](https://avatars.githubusercontent.com/u/7950487?v=4)](https://github.com/piotzkhider "piotzkhider (3 commits)")[![kuma-guy](https://avatars.githubusercontent.com/u/7978290?v=4)](https://github.com/kuma-guy "kuma-guy (2 commits)")[![apple-x-co](https://avatars.githubusercontent.com/u/8497012?v=4)](https://github.com/apple-x-co "apple-x-co (2 commits)")[![inaka-phper](https://avatars.githubusercontent.com/u/13147509?v=4)](https://github.com/inaka-phper "inaka-phper (2 commits)")[![exsuzukishuhei](https://avatars.githubusercontent.com/u/3086888?v=4)](https://github.com/exsuzukishuhei "exsuzukishuhei (1 commits)")[![momospnr](https://avatars.githubusercontent.com/u/1066913?v=4)](https://github.com/momospnr "momospnr (1 commits)")[![MugeSo](https://avatars.githubusercontent.com/u/250446?v=4)](https://github.com/MugeSo "MugeSo (1 commits)")

---

Tags

auradatabaseray-modulesqlpdoAura SqlRay module

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/ray-aura-sql-module/health.svg)

```
[![Health](https://phpackages.com/badges/ray-aura-sql-module/health.svg)](https://phpackages.com/packages/ray-aura-sql-module)
```

###  Alternatives

[doctrine/dbal

Powerful PHP database abstraction layer (DBAL) with many features for database schema introspection and management.

9.7k605.0M6.8k](/packages/doctrine-dbal)[kimai/kimai

Kimai - Time Tracking

4.8k9.0k1](/packages/kimai-kimai)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.9M738](/packages/sylius-sylius)[friendsofsymfony/elastica-bundle

Elasticsearch PHP integration for your Symfony project using Elastica

1.3k17.9M50](/packages/friendsofsymfony-elastica-bundle)[ray/media-query

PHP interface-based SQL framework

11254.8k4](/packages/ray-media-query)[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k38.9k](/packages/matomo-matomo)

PHPackages © 2026

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