Goat Query Laravel Package

Getting Started

The package is a standalone, PDO-based query builder. It is not a Laravel package — there is no service provider, facade, config file, or Eloquent integration. Treat it as an ordinary Composer dependency that you wire up yourself.

Minimal steps:

1. composer require makinacorpus/goat-query (verify the exact vendor/package name and current PHP constraint; the repo is the source of truth since it has essentially no dependents).

2. Read the repository README.md and docs/ first — that is where the query-builder and type-converter APIs are actually documented. Do not assume an API shape from the package name.

3. Instantiate its session/runner over a raw \PDO handle. The most practical connection source inside a Laravel app is Laravel's own PDO:

   $pdo = DB::connection()->getPdo();   // reuse Laravel's PDO
   // wrap $pdo in the GOAT session/runner per the package docs
   

4. Run a first select through the builder (not raw SQL) so you exercise both the query object and the PHP↔SQL type converter in one go — insert a value with a PHP type (bool, DateTime, array) and read it back.

First use case: a reporting or ETL-style query against an existing schema, where you want explicit, type-aware escaping of PHP values into SQL without pulling in Eloquent models. That is where the "PHP to SQL and SQL to PHP type converter" actually earns its keep.

Implementation Patterns

Wrap it in a container singleton. Since there is no provider, bind the GOAT session in a ServiceProvider so you control the PDO lifecycle and can mock it in tests:

$this->app->singleton(GoatSession::class, fn ($app) =>
    new GoatSession($app->make('db')->connection()->getPdo())
);

Use it for the query builder, not for ORM-style work. The natural pattern is fluent select / insert / update / delete construction with placeholders and the type converter handling value formatting. Keep models in Eloquent; use GOAT only for the queries where its conversion is the point.

Lean on the type converter as a standalone helper. You can call conversion in both directions — PHP value → SQL literal, and SQL row value → PHP type — without using the builder at all. That is often the most useful day-to-day leverage: normalizing DateTime objects, booleans, nulls, and JSON-ish payloads consistently before they hit a raw statement.

Batch and bulk operations. Prefer its insert-batch / multi-row facilities over Laravel's insert() when you need per-value type conversion; that avoids manual array mapping in seeders and import jobs.

Transactions: manage them explicitly on the underlying PDO (beginTransaction / commit / rollBack), or wrap the call in Laravel's DB::transaction() and pass the same PDO in, so both layers share one transaction. Never open a second, independent connection for GOAT — split connections are the fastest way to deadlock yourself.

Keep it in its own lane. Assign GOAT to a couple of well-defined services (imports, reporting, type-sensitive pipelines) rather than letting it leak across the codebase. If a query is trivial, use DB::table(...) and stay idiomatic.

Gotchas and Tips

• License is GPL-2.0. This is the single biggest blocker for most Laravel work. GPL-2.0 is copyleft; distributing a closed-source product that links it is legally uncomfortable. Get sign-off before adopting, or isolate it in a separate process/service.
• No framework glue. No facade, no provider, no toSql()-style logging hooked into Telescope, no query-log integration. If you need observability, log the generated SQL/bindings yourself.
• Two connections, one database. Reusing Laravel's PDO keeps transactions coherent, but any code path that constructs its own PDO will silently break atomicity. Audit the construction site and forbid ad-hoc new PDO in app code.
• Type converter ≠ Eloquent casts. Datetimes (timezone handling), booleans (SQLite/MySQL variants), and arrays will not necessarily round-trip the way Laravel's cast system does. Write a round-trip test for every type you rely on rather than assuming.
• Placeholder syntax may differ from Laravel's ? / :name conventions. Confirm against the docs; a wrong convention fails silently or throws opaquely.
• Maintenance risk. 2 stars, 0 dependents, a single maintainer. Budget for vendoring or, at worst, forking. Pin the exact version and don't expect upstream fixes.
• Debugging tip. Build small queries and print the generated SQL plus bindings before execution during development; the failure messages are not as friendly as Laravel's.
• Extension point is the type converter. The one genuinely worthwhile place to customize: register converters for your domain types (e.g., a value object or an enum-like class) so they serialize deterministically. That is the only integration seam worth leaning on.
• Verdict for day-to-day Laravel: keep Laravel's query builder and Eloquent as your default. Reach for GOAT only where its bidirectional type conversion solves a concrete problem (import pipelines, cross-database reporting, legacy schemas) — and only after the GPL question is settled.