{"id":18929476,"url":"https://github.com/thecodingmachine/magic-query","last_synced_at":"2025-08-20T08:33:10.982Z","repository":{"id":35251994,"uuid":"39511733","full_name":"thecodingmachine/magic-query","owner":"thecodingmachine","description":"A very clever library to use SQL prepared statement with a variable number of parameters... and much more!","archived":false,"fork":false,"pushed_at":"2024-06-08T14:58:17.000Z","size":606,"stargazers_count":22,"open_issues_count":9,"forks_count":14,"subscribers_count":11,"default_branch":"1.5","last_synced_at":"2024-12-18T00:45:00.071Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://mouf-php.com/packages/mouf/magic-query/README.md","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thecodingmachine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-07-22T14:44:15.000Z","updated_at":"2024-06-14T20:06:13.000Z","dependencies_parsed_at":"2024-06-08T15:58:16.845Z","dependency_job_id":"c3540755-19c0-4c3c-aaa0-4edcaeaff88b","html_url":"https://github.com/thecodingmachine/magic-query","commit_stats":{"total_commits":187,"total_committers":18,"mean_commits":10.38888888888889,"dds":0.2994652406417112,"last_synced_commit":"677c031c64cf9221deb3a5599c891af0a1e6ae86"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fmagic-query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fmagic-query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fmagic-query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fmagic-query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thecodingmachine","download_url":"https://codeload.github.com/thecodingmachine/magic-query/tar.gz/refs/heads/1.5","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230408171,"owners_count":18220974,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T11:32:55.855Z","updated_at":"2024-12-19T09:07:49.949Z","avatar_url":"https://github.com/thecodingmachine.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Latest Stable Version](https://poser.pugx.org/mouf/magic-query/v/stable)](https://packagist.org/packages/mouf/magic-query)\n[![Latest Unstable Version](https://poser.pugx.org/mouf/magic-query/v/unstable)](https://packagist.org/packages/mouf/magic-query)\n[![License](https://poser.pugx.org/mouf/magic-query/license)](https://packagist.org/packages/mouf/magic-query)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/thecodingmachine/magic-query/badges/quality-score.png?b=1.2)](https://scrutinizer-ci.com/g/thecodingmachine/magic-query/?branch=1.2)\n[![Build Status](https://travis-ci.org/thecodingmachine/magic-query.svg?branch=1.2)](https://travis-ci.org/thecodingmachine/magic-query)\n[![Coverage Status](https://coveralls.io/repos/thecodingmachine/magic-query/badge.svg?branch=1.2)](https://coveralls.io/r/thecodingmachine/magic-query?branch=1.2)\n\nWhat is Magic-query?\n====================\n\nMagic-query is a PHP library that helps you work with complex SQL queries.\n\nIt comes with 3 great features:\n\n- [**MagicParameters**: it helps you work with SQL queries that require a variable number of parameters.](#parameters)\n- [**MagicJoin**: it writes JOINs for you!](#joins)\n- [**MagicTwig**: use Twig templating in your SQL queries](#twig)\n\nInstallation\n------------\n\nSimply use the composer package:\n\n```json\n{\n\t\"require\": {\n\t\t\"mouf/magic-query\": \"^1.2\"\n\t},\n\t\"minimum-stability\": \"dev\",\n\t\"prefer-stable\": true\n}\n```\n\n\u003ca name=\"parameters\"\u003e\u003c/a\u003e\nAutomatically discard unused parameters with MagicParameters\n------------------------------------------------------------\n\nJust write the query with all possible parameters.\n\n```php\nuse Mouf\\Database\\MagicQuery;\n\n$sql = \"SELECT * FROM users WHERE name LIKE :name AND country LIKE :country\";\n\n// Get a MagicQuery object.\n$magicQuery = new MagicQuery();\n\n// Let's pass only the \"name\" parameter\n$result = $magicQuery-\u003ebuild($sql, [ \"name\" =\u003e \"%John%\" ]);\n// $result = SELECT * FROM users WHERE name LIKE '%John%'\n// Did you notice how the bit about the country simply vanished?\n\n// Let's pass no parameter at all!\n$result2 = $magicQuery-\u003ebuild($sql, []);\n// $result2 = SELECT * FROM users\n// The whole WHERE condition disappeared because it is not needed anymore!\n```\n\nCurious to know how this work? \u003ca class=\"btn btn-primary btn-large\" href=\"doc/discard_unused_parameters.md\"\u003eCheck out the parameters guide!\u003c/a\u003e\n\n\u003ca name=\"joins\"\u003e\u003c/a\u003e\nAutomatically guess JOINs with MagicJoin!\n-----------------------------------------\n\nFed up of writing joins in SQL? Let MagicQuery do the work for you!\n\nSeriously? Yes! All you have to do is:\n\n- Pass a **[Doctrine DBAL connection](http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/)** to MagicQuery's constructor. MagicQuery will analyze your schema.\n- In your SQL query, replace the tables with `magicjoin(start_table)`\n- For each column of your query, use the complete name ([table_name].[column_name] instead of [column_name] alone)\n\nLet's assume your database schema is:\n\n![Sample database schema](doc/images/schema1.png)\n\nUsing MagicJoin, you can write this SQL query:\n \n```sql\nSELECT users.* FROM MAGICJOIN(users) WHERE groups.name = 'Admins' AND country.name='France';\n```\n\nand it will automatically be transformed into this:\n\n```sql\nSELECT users.* FROM users \n\tLEFT JOIN users_groups ON users.user_id = users_groups.user_id\n \tLEFT JOIN groups ON groups.group_id = users_groups.group_id\n \tLEFT JOIN country ON country.country_id = users.country_id\nWHERE groups.name = 'Admins' AND country.name='France';\n```\n\nAnd the code is so simple!\n\n```php\nuse Mouf\\Database\\MagicQuery;\n\n$sql = \"SELECT users.* FROM MAGICJOIN(users) WHERE groups.name = 'Admins' AND country.name='France'\";\n\n// Get a MagicQuery object.\n// $conn is a Doctrine DBAL connection.\n$magicQuery = new MagicQuery($conn);\n\n$completeSql = $magicQuery-\u003ebuild($sql);\n// $completeSql contains the complete SQL request, with all joins.\n```\n\nWant to know more? \u003ca class=\"btn btn-primary btn-large\" href=\"doc/magic_join.md\"\u003eCheck out the MagicJoin guide!\u003c/a\u003e\n\n\u003ca name=\"twig\"\u003e\u003c/a\u003e\nUse Twig templating in your SQL queries!\n----------------------------------------\n\nDiscarding unused parameters and auto-joining keys is not enough? You have very specific needs? Say hello to \nTwig integration!\n\nUsing Twig integration, you can directly add Twig conditions right into your SQL.\n\n```php\nuse Mouf\\Database\\MagicQuery;\n\n$sql = \"SELECT users.* FROM users {% if isAdmin %} WHERE users.admin = 1 {% endif %}\";\n\n$magicQuery = new MagicQuery();\n// By default, Twig integration is disabled. You need to enable it.\n$magicQuery-\u003esetEnableTwig(true);\n\n$completeSql = $magicQuery-\u003ebuild($sql, ['isAdmin' =\u003e true]);\n// Parameters are passed to the Twig SQL query, and the SQL query is returned.\n```\n\n\u003cdiv class=\"alert alert-info\"\u003e\u003cstrong\u003eHeads up!\u003c/strong\u003e The Twig integration cannot be used to insert parameters\ninto the SQL query. You should use classic SQL parameters for this. This means that instead if writing \n\u003ccode\u003e{{ id }}\u003c/code\u003e, you should write \u003ccode\u003e:id\u003c/code\u003e.\u003c/div\u003e\n\nWant to know more? \u003ca class=\"btn btn-primary btn-large\" href=\"doc/magic_twig.md\"\u003eCheck out the MagicTwig guide!\u003c/a\u003e\n\nIs it a MySQL only tool?\n------------------------\n\nNo. By default, your SQL is parsed and then rewritten using the MySQL dialect, but you use any kind of dialect \nknown by [Doctrine DBAL](http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/). Magic-query optionally uses Doctrine DBAL. You can pass a `Connection` object\nas the first parameter of the `MagicQuery` constructor. Magic-query will then use the matching dialect. \n\nFor instance:\n\n```php\n$config = new \\Doctrine\\DBAL\\Configuration();\n$connectionParams = array(\n    'url' =\u003e 'sqlite:///somedb.sqlite',\n);\n$conn = \\Doctrine\\DBAL\\DriverManager::getConnection($connectionParams, $config);\n\n$magicQuery = new \\Mouf\\Database\\MagicQuery($conn);\n```\n\nAlso, if you have no connection to your database configured but you want to generate SQL in some specific dialect, you can\ninstead set the DBAL database platform used:\n\n```php\n$magicQuery-\u003esetOutputDialect(new \\Doctrine\\DBAL\\Platforms\\PostgreSqlPlatform());\n$magicQuery = new \\Mouf\\Database\\MagicQuery();\n```\n\n\nWhat about performances?\n------------------------\n\nMagicQuery does a lot to your query. It will parse it, render it internally as a tree of SQL nodes, etc...\nThis processing is time consuming. So you should definitely consider using a cache system. MagicQuery is compatible\nwith Doctrine Cache. You simply have to pass a Doctrine Cache instance has the second parameter of the constructor.\n \n```php\nuse Mouf\\Database\\MagicQuery;\nuse Doctrine\\Common\\Cache\\ApcCache;\n\n// $conn is a Doctrine connection\n$magicQuery = new MagicQuery($conn, new ApcCache());\n```\n\nAny problem?\n------------\n\nWith MagicQuery, a lot happens to your SQL query. In particular, it is parsed using a modified version\nof the php-sql-parser library. If you face any issues with a complex query, it is likely there is a bug\nin the parser. Please open [an issue on Github](https://github.com/thecodingmachine/magic-query/issues) and we'll try to fix it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecodingmachine%2Fmagic-query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthecodingmachine%2Fmagic-query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecodingmachine%2Fmagic-query/lists"}