makinacorpus / goat-query
Goat SQL query builder built over a PHP to SQL and SQL to PHP type converter
Installs: 10 988
Dependents: 9
Suggesters: 3
Security: 0
Stars: 2
Watchers: 1
Forks: 0
Open Issues: 24
Requires
- php: >=7.4
- makinacorpus/profiling: ^1.1.0 || ^2.0.1
- psr/log: ^1.1 || ^2
- symfony/polyfill-php80: ^1.24
Requires (Dev)
- makinacorpus/generated-hydrator-bundle: ^2.0.0
- phpbench/phpbench: ^1.0
- phpunit/phpunit: 9.*
- ramsey/uuid: ^3.8 || ^4
Suggests
- ramsey/uuid: For UUID database column type support
- symfony/console: For using the provided console tool
- dev-master
- 3.0.x-dev
- 3.0.14
- 3.0.13
- 3.0.12
- 3.0.11
- 3.0.10
- 3.0.9
- 3.0.8
- 3.0.7
- 3.0.6
- 3.0.5
- 3.0.4
- 3.0.3
- 3.0.2
- 3.0.1
- 3.0.0
- 3.0.0-alpha14
- 3.0.0-alpha13
- 3.0.0-alpha12
- 3.0.0-alpha11
- 3.0.0-alpha10
- 3.0.0-alpha9
- 3.0.0-alpha8
- 3.0.0-alpha7
- 3.0.0-alpha6
- 3.0.0-alpha5
- 3.0.0-alpha4
- 3.0.0-alpha3
- 3.0.0-alpha2
- 3.0.0-alpha1
- 2.1.x-dev
- 2.1.8
- 2.1.7
- 2.1.6
- 2.1.5
- 2.1.4
- 2.1.3
- 2.1.2
- 2.1.1
- 2.1.0
- 2.0.x-dev
- 2.0.5
- 2.0.4
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 2.0.0-alpha7
- 2.0.0-alpha6
- 2.0.0-alpha5
- 2.0.0-alpha4
- 2.0.0-alpha3
- 2.0.0-alpha2
- 2.0.0-alpha1
- 1.0.x-dev
- 1.0.13
- 1.0.12
- 1.0.11
- 1.0.10
- 1.0.9
- 1.0.8
- 1.0.7
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- 1.0.0-alpha32
- 1.0.0-alpha31
- 1.0.0-alpha30
- 1.0.0-alpha29
- 1.0.0-alpha28
- 1.0.0-alpha27
- 1.0.0-alpha26
- 1.0.0-alpha25
- 1.0.0-alpha24
- 1.0.0-alpha23
- 1.0.0-alpha22
- 1.0.0-alpha21
- 1.0.0-alpha20
- 1.0.0-alpha19
- 1.0.0-alpha18
- 1.0.0-alpha17
- 1.0.0-alpha16
- 1.0.0-alpha15
- 1.0.0-alpha14
- 1.0.0-alpha13
- 1.0.0-alpha12
- 1.0.0-alpha11
- 1.0.0-alpha10
- 1.0.0-alpha9
- 1.0.0-alpha8
- 1.0.0-alpha7
- 1.0.0-alpha6
- 1.0.0-alpha5
- 1.0.0-alpha4
- 1.0.0-alpha3
- 1.0.0-alpha2
- 1.0.0-alpha1
- dev-converter-rework
- dev-converter-refactor
- dev-binary
This package is not auto-updated.
Last update: 2024-09-05 21:44:37 UTC
README
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 usingPDO
.
Documentation is in the ./docs/
folder, generated using Sphinx.
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
- 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
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
- Symfony bundle in https://github.com/pounard/goat-query-bundle
Upgrade
Upgrade from 2.x to 3.x
-
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
-
2.x introduced a single user facing change: the Symfony bundle was originally provided by the makinacorpus/goat package, it is now bundled as the standalone 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
Originating and extracted from https://github.com/pounard/goat