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(3mo ago)22432.5k—8.7%4MITPHPPHP ^8.1CI passing

Since Aug 25Pushed 3mo 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 1mo 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

Maintenance79

Regular maintenance activity

Popularity47

Moderate usage in the ecosystem

Community19

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 54.5% 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

114d 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 (45 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

[scienta/doctrine-json-functions

A set of extensions to Doctrine that add support for json query functions.

58723.9M36](/packages/scienta-doctrine-json-functions)[damienharper/auditor-bundle

Integrate auditor library in your Symfony projects.

4542.8M](/packages/damienharper-auditor-bundle)[sonata-project/entity-audit-bundle

Audit for Doctrine Entities

644989.8k1](/packages/sonata-project-entity-audit-bundle)[pixelfederation/doctrine-resettable-em-bundle

Symfony bundle for decorating default entity managers using a resettable decorator.

20113.5k](/packages/pixelfederation-doctrine-resettable-em-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.

1022.4k](/packages/rcsofttech-audit-trail-bundle)[ahmed-bhs/doctrine-doctor

Runtime analysis tool for Doctrine ORM integrated into Symfony Web Profiler. Unlike static linters, it analyzes actual query execution at runtime to detect performance bottlenecks, security vulnerabilities, and best practice violations during development with real execution context and data.

813.1k](/packages/ahmed-bhs-doctrine-doctor)

PHPackages © 2026

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