PHPackages                             makinacorpus/goat-query - 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. makinacorpus/goat-query

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

makinacorpus/goat-query
=======================

Goat SQL query builder built over a PHP to SQL and SQL to PHP type converter

3.0.14(3y ago)211.6k↓50%[24 issues](https://github.com/pounard/goat-query/issues)10GPL-2.0-or-laterPHPPHP >=7.4

Since Nov 19Pushed 2y agoCompare

[ Source](https://github.com/pounard/goat-query)[ Packagist](https://packagist.org/packages/makinacorpus/goat-query)[ Docs](http://github.com/pounard/goat-query)[ RSS](/packages/makinacorpus-goat-query/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (7)Versions (105)Used By (10)

Goat query builder
==================

[](#goat-query-builder)

This is an SQL query builder built over a PHP to SQL and SQL to PHP type converter.

Working with `PDO` and `ext-pgsql`, with officially supported drivers:

- MySQL 5.7 using `PDO`,
- MySQL 8.x using `PDO`,
- PostgreSQL >= 9.5 (until latest) using `PDO`,
- PostgreSQL >= 9.5 (until latest) using `ext-pgsql` *(recommended driver)*,
- SQLite >= 3 using `PDO` *(experimental)*,
- With a few hacks, any RDBMS speaking `SQL-92` standard using `PDO`.

Documentation is in the `./docs/` folder, generated using Sphinx.

Quickstart
==========

[](#quickstart)

Install it:

```
composer require makinacorpus/goat-query
```

Create a connexion:

```
$driver = \Goat\Driver\DriverFactory::fromUri('pgsql://username:password@hostname:5432/database?option1=value1&option2=value2');
```

Or create a connexion the verbose way:

```
$driver = new \Goat\Driver\ExtPgSQLDriver();
$driver->setConfiguration(
    \Goat\Driver\Configuration::fromString(
        'pgsql://username:password@hostname:5432/database?option1=value1&option2=value2'
    )
);
```

Please note that options given will be treated differently depending upon driver.

Then use it:

```
$runner = $driver->getRunner();
$platform = $runner->getPlatform();
$queryBuilder = $runner->getQueryBuilder();

if ($platform->supportsReturning()) {
    $result = $queryBuilder
        ->insertValues('users')
        ->columns(['id', 'name'])
        ->values([1, 'Jean'])
        ->values([1, 'Robert'])
        ->returning('*')
        ->setOption('class', \App\Domain\Model\User::class)
        ->execute()
    ;
} else {
    $queryBuilder
        ->insertValues('users')
        ->columns(['id', 'name'])
        ->values([1, 'Jean'])
        ->values([2, 'Robert'])
        ->execute()
    ;

    $result = $queryBuilder
        ->select('users')
        ->where('id', [1, 2])
        ->setOption('class', \App\Domain\Model\User::class)
        ->execute()
}

foreach ($result as $user) {
   \assert($user instanceof \App\Domain\Model\User);

    echo "Hello, ", $user->getName(), " !\n";
}
```

For advanced documentation, please see the `./docs/` folder.

Roadmap
=======

[](#roadmap)

- 2.0 - bumps requirement to PHP 7.4,
- 2.1 - includes MERGE query support, functional testing, driver and platform segregation, as well as many fixes, and deprecated some 1.x methods,
- 3.0 - is a major overhaul of sql writer, converter context, and query builder,
- 3.0 - brings an experimental version of schema introspector and console tool,
- 3.1 - will be a features with many shortcuts and sugar candy additions,
- 4.0 - will stabilize schema introspector and console tool.

Driver organisation
===================

[](#driver-organisation)

`Driver` instance is responsible of (in order):

- connecting to the database,
- send configuration,
- inspect backend variant and version to build platform.

It gets connexion option and configures it, then creates the platform.

`Platform` contains SQL version-specific code, such as query formatter, schema introspector, and other things the user cannot configure, and which may vary depending upon the SQL server version. It handles everything the user cannot have hands onto, but SQL server has.

`Runner` is the only runtime object the user needs:

- public facade for executing SQL queries,
- holds the converter (which can be injected and may contain user code),
- creates and holds the query builder,
- manages transactions.

It contains user configuration and runtime. The runner knows nothing about SQL itself, it just holds a connexion, send requests, and handles iterators and transactions.

In other words:

- drivers connects,
- platform handles SQL dialect,
- runner executes,
- a single runner implementation can use different plaform implementations, real reason why both implementations are actually separate.

Framework integration
=====================

[](#framework-integration)

- Symfony bundle in

Upgrade
=======

[](#upgrade)

Upgrade from 2.x to 3.x
-----------------------

[](#upgrade-from-2x-to-3x)

- 3.x deprecated all `\Goat\Query\Expression*` classes. Their backward compatible equivalent still exists, in order to make your code resilient, please use their new implementations in `\Goat\Query\Expression\*Expression`.
- 3.x ships a complete `\Goat\Driver\Query\SqlWriter` interface and implementations rewrite. New code is faster, easier to read and has much less dependencies, driver developers or users using it directly must adapt their code.
- 3.x removes the `\Goat\Query\ArgumentBag`, `\Goat\Query\ArgumentList`, `\Goat\Query\Value`, `\Goat\Query\ValueRepresentation` classes and interfaces, people using those must adapt their code.
- 3.x changes the `\Goat\Converter\ValueConverterInterface` contracts slightly, you need to adapt your existing custom value converters,
- 3.x completely changes date handling, for most people, it should go unnoticed and fix many bugs,
- Generally speaking, this will be the last version providing backward compatible deprecated code, following deprecation notices and the `@deprecated`PHP documentation annotaton to fix your existing code.
- For most users, upgrade will be transparent and will not cause any trouble.

Upgrade from 1.x to 2.x
-----------------------

[](#upgrade-from-1x-to-2x)

- 2.x introduced a single user facing change: the Symfony bundle was originally provided by the [makinacorpus/goat](https://packagist.org/packages/makinacorpus/goat)package, it is now bundled as the standalone [makinacorpus/goat-query-bundle](https://packagist.org/packages/makinacorpus/goat-query-bundle)package.
- 2.x changed internal runners implementation and introduces a new `\Goat\Driver\` namespace, which focuses on low-level driver implementations, driver developpers will need to convert their code to the new API.

This also introduce a dependency conflict between `makinacorpus/goat` version prior to `3.0.0` version, if you were using it, you need to upgrade.

Query builder, database runner and result iterator end-user API did not change.

History
=======

[](#history)

Originating and extracted from

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance0

Infrequent updates — may be unmaintained

Popularity26

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity78

Established project with proven stability

 Bus Factor1

Top contributor holds 100% 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 ~15 days

Recently: every ~30 days

Total

101

Last Release

1183d ago

Major Versions

1.0.11 → 2.0.42020-11-17

2.1.7 → 3.0.0-alpha12020-12-01

1.0.12 → 3.0.0-alpha52021-06-01

1.0.13 → 3.0.0-alpha72021-06-18

2.1.x-dev → 3.0.0-alpha132021-07-30

PHP version history (2 changes)1.0.0-alpha1PHP >=7.2

2.0.0-alpha6PHP >=7.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/d21b98752b406528da88850922b1061f39bf72eb2126b413d5c12e275811a40b?d=identicon)[Makina Corpus](/maintainers/Makina%20Corpus)

---

Top Contributors

[![pounard](https://avatars.githubusercontent.com/u/341855?v=4)](https://github.com/pounard "pounard (264 commits)")

---

Tags

symfonydatabaseormmysqlpostgresqlpdo

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/makinacorpus-goat-query/health.svg)

```
[![Health](https://phpackages.com/badges/makinacorpus-goat-query/health.svg)](https://phpackages.com/packages/makinacorpus-goat-query)
```

###  Alternatives

[doctrine/dbal

Powerful PHP database abstraction layer (DBAL) with many features for database schema introspection and management.

9.7k578.4M5.6k](/packages/doctrine-dbal)[cycle/database

DBAL, schema introspection, migration and pagination

64690.9k31](/packages/cycle-database)[tommyknocker/pdo-database-class

Framework-agnostic PHP database library with unified API for MySQL, MariaDB, PostgreSQL, SQLite, MSSQL, and Oracle. Query Builder, caching, sharding, window functions, CTEs, JSON, migrations, ActiveRecord, CLI tools, AI-powered analysis. Zero external dependencies.

845.7k](/packages/tommyknocker-pdo-database-class)[ramadan/easy-model

A Laravel package for enjoyably managing database queries.

101.6k](/packages/ramadan-easy-model)

PHPackages © 2026

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