{"id":16031734,"url":"https://github.com/clancats/hydrahon","last_synced_at":"2025-05-16T16:07:38.966Z","repository":{"id":32870634,"uuid":"36464666","full_name":"ClanCats/Hydrahon","owner":"ClanCats","description":"🐉 Fast \u0026 standalone PHP MySQL Query Builder library.","archived":false,"fork":false,"pushed_at":"2025-05-15T16:47:15.000Z","size":300,"stargazers_count":279,"open_issues_count":22,"forks_count":55,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-05-16T16:07:00.458Z","etag":null,"topics":["mysql","pdo","php","query-builder"],"latest_commit_sha":null,"homepage":"https://clancats.io/hydrahon/master/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ClanCats.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2015-05-28T20:36:12.000Z","updated_at":"2025-05-15T16:47:19.000Z","dependencies_parsed_at":"2025-05-16T16:07:05.499Z","dependency_job_id":null,"html_url":"https://github.com/ClanCats/Hydrahon","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClanCats%2FHydrahon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClanCats%2FHydrahon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClanCats%2FHydrahon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClanCats%2FHydrahon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClanCats","download_url":"https://codeload.github.com/ClanCats/Hydrahon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254564127,"owners_count":22092122,"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":["mysql","pdo","php","query-builder"],"created_at":"2024-10-08T21:05:12.914Z","updated_at":"2025-05-16T16:07:38.930Z","avatar_url":"https://github.com/ClanCats.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003ca href=\"http://clancats.io/hydrahon/master/\" target=\"_blank\"\u003e\n    \u003cimg width=\"100px\" src=\"https://user-images.githubusercontent.com/956212/28079683-a2d93bf8-6669-11e7-920e-5779b665a909.png\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n# Hydrahon\n\nHydrahon is a **standalone** database / SQL query builder written in PHP. It was built to enhance existing frameworks, libraries and applications that handle the database connection on their own. It **does not** come with a **PDO** or **mysqli** wrapper. The naming is heavily inspired by Eloquent and the Kohana Framework Database component.\n\n**What does that mean \"Standalone query builder\"?**\n\nHydrahon only generates a query **string** and an array of parameters. On its own, it is not able to execute a query.\n\n[![Build Status](https://travis-ci.org/ClanCats/Hydrahon.svg?branch=master)](https://travis-ci.org/ClanCats/Hydrahon)\n[![Packagist](https://img.shields.io/packagist/dt/clancats/hydrahon.svg)](https://packagist.org/packages/clancats/hydrahon)\n[![Packagist](https://img.shields.io/packagist/l/clancats/hydrahon.svg)](https://github.com/ClanCats/Hydrahon/blob/master/LICENSE)\n[![GitHub release](https://img.shields.io/github/release/clancats/hydrahon.svg)](https://github.com/ClanCats/Hydrahon/releases)\n\n## Status\n\n* The Hydrahon **MySQL** query builder is stable and used in production.\n* The Hydrahon **AQL** (Arango Query Language) query builder is currently in development.\n* A builder for Elasticsearch is on my mind but not in development.\n\n## Installation\n\nHydrahon follows `PSR-4` autoloading and can be installed using composer:\n\n```\n$ composer require clancats/hydrahon\n```\n## Documentation 💡\n\nThe full documentation can be found on [clancats.io](http://clancats.io/hydrahon/master/)\n\n## Quick Start (MySQL) ⚡️\n\nHydrahon is designed to be a pretty generic query builder. So for this quick start, we stick with SQL.\n\n### Create a builder\n\nAgain this library is **not** built as a full database abstraction or ORM, it is only and will always be only a query builder. This means we need to implement the database connection and fetching by ourselves. The Hydrahon constructor therefore requires you to provide a callback function that does this, and returns the results.\n\nIn this example, we are going to use [PDO](http://php.net/manual/en/book.pdo.php)\n\n```php \n$connection = new PDO('mysql:host=localhost;dbname=my_database;charset=utf8', 'username', 'password');\n\n// create a new mysql query builder\n$h = new \\ClanCats\\Hydrahon\\Builder('mysql', function($query, $queryString, $queryParameters) use($connection)\n{\n    $statement = $connection-\u003eprepare($queryString);\n    $statement-\u003eexecute($queryParameters);\n\n    // when the query is fetchable return all results and let hydrahon do the rest\n    // (there's no results to be fetched for an update-query for example)\n    if ($query instanceof \\ClanCats\\Hydrahon\\Query\\Sql\\FetchableInterface)\n    {\n        return $statement-\u003efetchAll(\\PDO::FETCH_ASSOC);\n    }\n    // when the query is a instance of a insert return the last inserted id  \n    elseif($query instanceof \\ClanCats\\Hydrahon\\Query\\Sql\\Insert)\n    {\n        return $connection-\u003elastInsertId();\n    }\n    // when the query is not a instance of insert or fetchable then\n    // return the number os rows affected\n    else \n    {\n        return $statement-\u003erowCount();\n    }\t\n});\n```\n\nAnd we are ready and set. The variable `$h` contains now a MySQL query builder.\n\n### Setup a simple table\n\nTo continue with our examples, we need to create a simple MySQL table.\n\n```sql\nCREATE TABLE `people` (\n  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,\n  `name` varchar(255) DEFAULT '',\n  `age` int(11) DEFAULT NULL,\n  PRIMARY KEY (`id`)\n) ENGINE=InnoDB DEFAULT CHARSET=utf8;\n```\n\n### Inserting\n\nCurrently, we do not have any data, to fix this let's go and insert some.\n\n```php\n// In our example we are going to execute multiple operations on the same table, \n// so instead of loading the table over and over again, we store it in a variable.\n$people = $h-\u003etable('people');\n\n$people-\u003einsert(\n[\n    ['name' =\u003e 'Ray', 'age' =\u003e 25],\n    ['name' =\u003e 'John',  'age' =\u003e 30],\n    ['name' =\u003e 'Ali', 'age' =\u003e 22],\n])-\u003eexecute();\n```\n\nWill execute the following query:\n\n```sql\ninsert into `people` (`age`, `name`) values (?, ?), (?, ?), (?, ?)\n```\n\nAs you can see Hydrahon automatically escapes the parameters. \n\nHowever, because we are humans that get confused when there are hundreds of thousands of questions marks, I will continue to always display the runnable query:\n\n```sql\ninsert into `people` (`age`, `name`) values (25, Ray), (30, John), (22, Ali)\n```\n\n### Updating\n\nAh snap, time runs so fast, \"Ray\" is actually already 26.\n\n```php\n$people-\u003eupdate()\n    -\u003eset('age', 26)\n    -\u003ewhere('name', 'Ray')\n-\u003eexecute();\n```\n\nGenerating:\n\n```sql\nupdate `people` set `age` = 26 where `name` = 'Ray'\n```\n\nCurrently, you might think: \"Well isn't it much simpler to just write the SQL query? I mean the PHP code is even longer...\". \n\nYou have to understand that these are some very very basic examples the Hydrahon query builder starts to shine when things get more complex. However, a \"Quick Start\" is just the wrong place for complicated stuff, so throw an eye on the [full documentation](http://clancats.io/hydrahon/master/).\n\n### Deleting \n\nDammit John, I hate you...\n\n```php\n$people-\u003edelete()\n    -\u003ewhere('name', 'John')\n-\u003eexecute();\n```\n\nGenerating:\n\n```sql\ndelete from `people` where `name` = 'John'\n```\n\n### Selecting\n\nAnd finally, fetch the data.\n\n```php\n$people-\u003eselect()-\u003eget();\n```\n\nGenerating:\n\n```sql\nselect * from `people`\n```\n\nResult:\n\n```json\n[\n  {\n    \"id\": \"1\",\n    \"name\": \"Ray\",\n    \"age\": \"26\"\n  },\n  {\n    \"id\": \"3\",\n    \"name\": \"Ali\",\n    \"age\": \"22\"\n  }\n]\n```\n\nNotice that we use `-\u003eget()` to actually fetch data, while we used `-\u003eexecute()` for our previous queries (updates, inserts and deletes). See the full documentation for more information about the Hydrahon [runners methods](https://clancats.io/hydrahon/master/sql-query-builder/select/runner-methods).\n\n### Where conditions\n\nFor the next few examples, lets assume a larger dataset so that the queries make sense.\n\nChaining where conditions:\n\n```php\n// select * from `people` where `age` = 21 and `name` like 'J%'\n$people-\u003eselect()\n    -\u003ewhere('age', 21)\n    -\u003ewhere('name', 'like', 'J%')\n    -\u003eget();\n```\n\nNotice how omitting the operator in the first condition `-\u003ewhere('age', 21)` makes Hydrahon default to `=`.\n\nBy default all where conditions are defined with the `and` operator.\n\nDifferent where operators:\n\n```php\n// select * from `people` where `name` like 'J%' or `name` like 'I%'\n$people-\u003eselect()\n    -\u003ewhere('name', 'like', 'J%')\n    -\u003eorWhere('name', 'like', 'I%')\n    -\u003eget();\n```\n\nPlease check the [relevant section in the full documentation](https://clancats.io/hydrahon/master/sql-query-builder/select/basics) for more where-functions, like\n- `whereIn()`\n- `whereNotIn()`\n- `whereNull()`\n- `whereNotNull()`\n\n#### Where scopes\n\nAllowing you to group conditions:\n\n```php\n// select * from `people` where ( `age` \u003e 21 and `age` \u003c 99 ) or `group` = admin\n$people-\u003eselect()\n    -\u003ewhere(function($q) \n    {\n        $q-\u003ewhere('age', '\u003e', 21);\n        $q-\u003ewhere('age', '\u003c', 99);\n    })\n    -\u003eorWhere('group', 'admin')\n    -\u003eget();\n```\n\n### Joins\n\nJoining tables:\n\n```php\n// select \n//     `people`.`name`, `groups`.`name` as `group_name` \n// from `people` \n// left join `groups` on `groups`.`id` = `people`.`group_id`\n$people-\u003eselect('people.name, groups.name as group_name')\n    -\u003ejoin('groups', 'groups.id', '=', 'people.group_id')\n    -\u003eget();\n```\n\n### Grouping\n\nGrouping data:\n\n```php\n// select * from `people` group by `age`\n$people-\u003eselect()-\u003egroupBy('age')-\u003eget();\n```\n\n### Ordering\n\nOrdering data:\n\n```php\n// select * from `people` order by `age` desc\n$people-\u003eselect()-\u003eorderBy('age', 'desc')-\u003eget();\n\n// select * from `people` order by `age` desc, `name` asc\n$people-\u003eselect()-\u003eorderBy(['age' =\u003e 'desc', 'name' =\u003e 'asc'])-\u003eget();\n```\n\n### Limiting data\n\nLimit and offset:\n\n```php\n// select * from `people` limit 0, 10\n$people-\u003eselect()-\u003elimit(10)-\u003eget();\n\n// select * from `people` limit 100, 10\n$people-\u003eselect()-\u003elimit(100, 10)-\u003eget();\n\n// select * from `people` limit 100, 10\n$people-\u003eselect()-\u003elimit(10)-\u003eoffset(100)-\u003eget();\n\n// select * from `people` limit 150, 30\n$people-\u003eselect()-\u003epage(5, 30)-\u003eget();\n```\n\n**Small reminder this is the quick start, check out the full docs.**\n\n## Credits\n\n- [Mario Döring](https://github.com/mario-deluna)\n- [All Contributors](https://github.com/ClanCats/Hydrahon/contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](https://github.com/ClanCats/Hydrahon/blob/master/LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclancats%2Fhydrahon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclancats%2Fhydrahon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclancats%2Fhydrahon/lists"}