PHPackages                             shipmonk/doctrine-mysql-index-hints - 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. shipmonk/doctrine-mysql-index-hints

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

shipmonk/doctrine-mysql-index-hints
===================================

Custom SQL walker for Doctrine allowing usage of MySQL index hints without need of native queries

3.1.2(5mo ago)24559.9k↓52.6%3MITPHPPHP ^8.1CI passing

Since Aug 25Pushed 2mo ago5 watchersCompare

[ Source](https://github.com/shipmonk-rnd/doctrine-mysql-index-hints)[ Packagist](https://packagist.org/packages/shipmonk/doctrine-mysql-index-hints)[ RSS](/packages/shipmonk-doctrine-mysql-index-hints/feed)WikiDiscussions master Synced 3d ago

READMEChangelog (7)Dependencies (15)Versions (11)Used By (0)

MySQL index hints for Doctrine
------------------------------

[](#mysql-index-hints-for-doctrine)

This library provides a simple way to incorporate [MySQL's index hints](https://dev.mysql.com/doc/refman/8.0/en/index-hints.html)into SELECT queries written in [Doctrine Query Language](https://www.doctrine-project.org/projects/doctrine-orm/en/2.9/reference/dql-doctrine-query-language.html)via [custom SqlWalker](https://www.doctrine-project.org/projects/doctrine-orm/en/2.9/cookbook/dql-custom-walkers.html#modify-the-output-walker-to-generate-vendor-specific-sql). No need for native queries anymore.

### Installation:

[](#installation)

```
composer require shipmonk/doctrine-mysql-index-hints
```

### Simple usage:

[](#simple-usage)

```
$result = $em->createQueryBuilder()
    ->select('u.id')
    ->from(User::class, 'u')
    ->andWhere('u.id = 1')
    ->getQuery()
    ->setHint(Query::HINT_CUSTOM_OUTPUT_WALKER, HintDrivenSqlWalker::class)
    ->setHint(UseIndexHintHandler::class, [IndexHint::force(User::IDX_FOO, User::TABLE_NAME)])
    ->getResult();
```

Which produces following SQL:

```
SELECT u0_.id AS id_0
FROM user u0_ FORCE INDEX (IDX_FOO)
WHERE u0_.id = 1
```

See the used entity (it makes sense to put table names and index names into public constants to bind it together and reference it easily):

```
#[ORM\Table(name: self::TABLE_NAME)]
#[ORM\Index(name: self::IDX_FOO, columns: ['id'])]
#[ORM\Entity]
class User
{
    public const TABLE_NAME = 'user';
    public const IDX_FOO = 'IDX_FOO';

    // ...
}
```

### Combining multiple hints:

[](#combining-multiple-hints)

You might need to give MySQL a list of possible indexes or hint it not to use some indices. As you can see, hinting joined tables is equally simple.

```
->from(User::class, 'u')
->join('u.account', 'a')
->getQuery()
->setHint(Query::HINT_CUSTOM_OUTPUT_WALKER, HintDrivenSqlWalker::class)
->setHint(UseIndexHintHandler::class, [
    IndexHint::use(Account::IDX_1, Account::TABLE_NAME),
    IndexHint::use(Account::IDX_2, Account::TABLE_NAME),
    IndexHint::ignore(Account::IDX_3, Account::TABLE_NAME),
    IndexHint::ignore(Account::IDX_4, Account::TABLE_NAME),
])
```

Produces this SQL:

```
FROM user u0_
JOIN account a1_ IGNORE INDEX (IDX_3, IDX_4) USE INDEX (IDX_1, IDX_2) ON (...)
```

### Hinting table joined multiple times:

[](#hinting-table-joined-multiple-times)

You might need to hint only specific join of certain table. Just add which DQL alias specifies it as third argument.

```
->from(User::class, 'u')
->join('u.account', 'a1')
->join('u.anotherAccount', 'a2')
->getQuery()
->setHint(Query::HINT_CUSTOM_OUTPUT_WALKER, HintDrivenSqlWalker::class)
->setHint(UseIndexHintHandler::class, [
    IndexHint::use(Account::IDX_1, Account::TABLE_NAME, 'a1'), // alias needed
])
```

Produces this SQL:

```
FROM user u0_
JOIN account a1_ USE INDEX (IDX_1) ON (...)
JOIN account a2_ ON (...)
```

### Advanced usage notes

[](#advanced-usage-notes)

- Subselects are also supported
- It works even for tables that are not present in the DQL, but are present in SQL!
    - For example parent table from [class table inheritance](https://www.doctrine-project.org/projects/doctrine-orm/en/2.9/reference/inheritance-mapping.html#class-table-inheritance) when selecting children
- Any invalid usage is checked in runtime
    - Table name existence is checked, so you just cannot swap `tableName` and `indexName` parameters by accident or use non-existing DQL alias
    - Forgotten hint or invalid arguments are also checked
    - Since those checks cannot be caught by any static analysis tool, it is recommended to have a test for every query

### Combining with optimizer hints:

[](#combining-with-optimizer-hints)

Since 3.0.0, you can combine this library with [shipmonk/doctrine-mysql-optimizer-hints](https://github.com/shipmonk-rnd/doctrine-mysql-optimizer-hints):

```
$result = $em->createQueryBuilder()
    ->select('u.id')
    ->from(User::class, 'u')
    ->andWhere('u.id = 1')
    ->getQuery()
    ->setHint(Query::HINT_CUSTOM_OUTPUT_WALKER, HintDrivenSqlWalker::class)
    ->setHint(OptimizerHintsHintHandler::class, ['MAX_EXECUTION_TIME(1000)'])
    ->setHint(UseIndexHintHandler::class, [IndexHint::force(User::IDX_FOO, User::TABLE_NAME)])
    ->getResult();
```

###  Health Score

57

—

FairBetter than 98% of packages

Maintenance78

Regular maintenance activity

Popularity48

Moderate usage in the ecosystem

Community19

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 54.1% 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 ~230 days

Recently: every ~272 days

Total

8

Last Release

160d ago

Major Versions

1.0.0 → 2.0.02021-09-13

v1.x-dev → 2.1.02023-01-30

2.1.0 → 3.0.02024-01-25

PHP version history (4 changes)1.0.0PHP >=7.1.0

2.0.0PHP >=7.4.0

2.1.0PHP ^7.4 || ^8.0

3.1.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/5b545e3f9d982d538f11bc42b3dc2d186f706cef92c8bc8bc8f8788b08186ea5?d=identicon)[janedbal](/maintainers/janedbal)

![](https://www.gravatar.com/avatar/7a4170ebe9281cb76be91fe00f8eee307beb3e0744dfd40ba89d9c856372c7eb?d=identicon)[shipmonk](/maintainers/shipmonk)

---

Top Contributors

[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (60 commits)")[![janedbal](https://avatars.githubusercontent.com/u/1993453?v=4)](https://github.com/janedbal "janedbal (46 commits)")[![olsavmic](https://avatars.githubusercontent.com/u/3778875?v=4)](https://github.com/olsavmic "olsavmic (1 commits)")[![paranoiq](https://avatars.githubusercontent.com/u/146912?v=4)](https://github.com/paranoiq "paranoiq (1 commits)")[![someson](https://avatars.githubusercontent.com/u/3097223?v=4)](https://github.com/someson "someson (1 commits)")[![JanTvrdik](https://avatars.githubusercontent.com/u/175109?v=4)](https://github.com/JanTvrdik "JanTvrdik (1 commits)")[![gharlan](https://avatars.githubusercontent.com/u/330436?v=4)](https://github.com/gharlan "gharlan (1 commits)")

---

Tags

doctrinemysqloptimization

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/shipmonk-doctrine-mysql-index-hints/health.svg)

```
[![Health](https://phpackages.com/badges/shipmonk-doctrine-mysql-index-hints/health.svg)](https://phpackages.com/packages/shipmonk-doctrine-mysql-index-hints)
```

###  Alternatives

[easycorp/easyadmin-bundle

Admin generator for Symfony applications

4.3k17.9M388](/packages/easycorp-easyadmin-bundle)[rcsofttech/audit-trail-bundle

Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking.

1189.8k](/packages/rcsofttech-audit-trail-bundle)[kimai/kimai

Kimai - Time Tracking

4.8k9.0k1](/packages/kimai-kimai)[2lenet/crudit-bundle

The easy like Crud'it Bundle.

1616.4k14](/packages/2lenet-crudit-bundle)

PHPackages © 2026

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