Initial commit

Author: janedbal

.editorconfig

@@ -0,0 +1,8 @@
+[*]
+charset = utf-8
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+

.github/workflows/checks.yml

@@ -0,0 +1,13 @@
+name: Checks
+on: [push, pull_request]
+jobs:
+    checks:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v2
+            -
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: '7.1'
+            - run: composer install --no-progress --prefer-dist
+            - run: composer check

.gitignore

@@ -0,0 +1,5 @@
+/vendor
+/cache
+/.idea
+/phpstan.neon
+/composer.lock

README.md

@@ -0,0 +1,113 @@
+## 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:
+
+```sh
+composer require shipmonk/doctrine-mysql-index-hints
+```
+
+### Simple usage:
+
+```php
+$result = $em->createQueryBuilder()
+    ->select('u.id')
+    ->from(User::class, 'u')
+    ->andWhere('u.id = 1')
+    ->getQuery()
+    ->setHint(Query::HINT_CUSTOM_OUTPUT_WALKER, UseIndexSqlWalker::class)
+    ->setHint(UseIndexSqlWalker::class, [IndexHint::force(User::IDX_FOO, User::TABLE_NAME)])
+    ->getResult();
+```
+
+Which produces following SQL:
+
+```mysql
+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):
+
+```php
+/**
+ * @ORM\Table(
+ *     name=User::TABLE_NAME
+ *     indexes={
+ *          @ORM\Index(name=User::IDX_FOO, columns={"id"}),
+ *     }
+ * )
+ *  )
+ * @ORM\Entity
+ */
+class User
+{
+    public const TABLE_NAME = 'user';
+    public const IDX_FOO = 'IDX_FOO';
+
+    // ...
+}
+```
+
+### 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.
+
+```php
+->from(User::class, 'u')
+->join('u.account', 'a')
+->getQuery()
+->setHint(Query::HINT_CUSTOM_OUTPUT_WALKER, UseIndexSqlWalker::class)
+->setHint(UseIndexSqlWalker::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:
+
+```mysql
+FROM user u0_
+JOIN account a1_ IGNORE INDEX (IDX_3, IDX_4) USE INDEX (IDX_1, IDX_2) ON (...)
+```
+
+### 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.
+
+```php
+->from(User::class, 'u')
+->join('u.account', 'a1')
+->join('u.anotherAccount', 'a2')
+->getQuery()
+->setHint(Query::HINT_CUSTOM_OUTPUT_WALKER, UseIndexSqlWalker::class)
+->setHint(UseIndexSqlWalker::class, [
+    IndexHint::use(Account::IDX_1, Account::TABLE_NAME, 'a1'), // alias needed
+])
+```
+
+Produces this SQL:
+
+```mysql
+FROM user u0_
+JOIN account a1_ USE INDEX (IDX_1) ON (...)
+JOIN account a2_ ON (...)
+```
+
+### Advanced usage notes
+- 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
+
+

composer.json

@@ -0,0 +1,34 @@
+{
+    "name": "shipmonk/doctrine-mysql-index-hints",
+    "description": "Custom SQL walker for Doctrine allowing usage of MySQL index hints without need of native queries",
+    "license": ["MIT"],
+    "require": {
+        "php": ">=7.1.0",
+        "doctrine/orm": ">=2.5.0",
+        "nette/utils": ">=2.4.0"
+    },
+    "require-dev": {
+        "editorconfig-checker/editorconfig-checker": "^10.2",
+        "phpstan/phpstan": "^0.12.94",
+        "phpstan/phpstan-phpunit": "^0.12.22",
+        "phpstan/phpstan-strict-rules": "^0.12.10",
+        "phpunit/phpunit": "^9.5",
+        "slevomat/coding-standard": "^7.0"
+    },
+    "config": {
+        "sort-packages": true
+    },
+    "autoload": {
+        "psr-4": {
+            "ShipMonk\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "ShipMonk\\": "tests/"
+        }
+    },
+    "scripts": {
+        "check": "ec && phpcs && phpstan analyse -vvv && phpunit -vvv tests"
+    }
+}