Simple Pdo Query Builder Laravel Package

Getting Started

Before writing any code, read the repository in this order: README.md (usage examples and constructor signature), composer.json (required PHP version and PSR-4 namespace), then src/ (usually one or two small classes — the whole library is likely a few hundred lines). Because there is no Laravel service provider, no facade, and no config file, "getting started" is really just: install it, hand it a PDO instance, and call builder methods.

Minimal flow:

1. composer require megawilddaddy/simple-pdo-query-builder
2. Create a PDO connection yourself (DSN, user, password) — the package does not manage connections.
3. Instantiate the builder with that PDO object.
4. Build a query (select/insert/update/delete) and bind values.
5. execute() / fetch the result and handle PDOException yourself.

First realistic use case for a Laravel developer: a non-Laravel context — a CLI script, a queue worker in a legacy codebase, a small microservice, or a tool that talks to a second database where you deliberately don't want to boot Illuminate. Inside a normal Laravel app, DB::table(...) already covers this ground with better ergonomics, so the honest first use case is "I'm outside the framework but still want small, readable PDO queries."

Confirm the exact method names (select, where, get, first, insert, etc.) against the source before committing to them — with a 2022 last release and zero dependents, the README is the only contract you have.

Implementation Patterns

Wrap it, don't sprinkle it. The most important pattern is to hide the builder behind your own tiny repository/interface. That gives you a seam to swap in Laravel's DB facade later and keeps the unmaintained dependency confined to one or two files.

interface UserReader {
    public function findByEmail(string $email): ?array;
}

final class PdoUserReader implements UserReader {
    public function __construct(private \PDO $pdo) {}

    public function findByEmail(string $email): ?array {
        // use the package's builder API here
        // always bind $email, never interpolate
    }
}

Connection management stays yours. Use a singleton or DI container binding for the PDO instance so you're not reconnecting per query. In Laravel, register it in a service provider:

$this->app->singleton(UserReader::class, fn () => new PdoUserReader(
    new \PDO(config('services.legacy.dsn'), config('services.legacy.user'), config('services.legacy.pass'), [
        \PDO::ATTR_ERRMODE => \PDO::ERRMODE_EXCEPTION,
        \PDO::ATTR_DEFAULT_FETCH_MODE => \PDO::FETCH_ASSOC,
        \PDO::ATTR_EMULATE_PREPARES => false,
    ])
));

Typical query workflow: build → bind → execute → map. Since the library is low-level, expect to do result mapping (arrays to DTOs) yourself. Keep a thin hydrate() helper per repository rather than scattering FETCH_* logic.

Transactions are manual. Wrap multi-statement writes in $pdo->beginTransaction() / commit() / rollBack() with a try/catch. The builder won't do this for you.

Read-only external DBs are the sweet spot: point it at a reporting replica or a vendor database, keep the builder isolated, and never let it write. This is where "low-level queries with ease" actually pays off versus dragging Eloquent's model assumptions into a schema you don't own.

Testing: use SQLite in-memory (new PDO('sqlite::memory:')) for fast integration tests, or mock your UserReader interface for unit tests. Don't mock PDO itself — it's painful and brittle.

Gotchas and Tips

• It's unmaintained (last release Jan 2022, 0 stars, 0 dependents). Treat it as vendored code you own. Pin the version, and be prepared to fork. No security advisories, no PHP 8.3/8.4 guarantees, no community to ask.
• No Laravel integration. No service provider, facade, config, or auto-discovery. Any "Laravel usage" is glue you write yourself.
• SQL injection is on you. The builder helps compose SQL, but any raw fragment or identifier (table/column names, ORDER BY) that you interpolate is unescaped. Bind values; whitelist identifiers against a fixed allow-list.
• Identifier quoting differs by driver (backticks vs double quotes). Verify how the builder quotes tables/columns on MySQL vs Postgres vs SQLite before trusting it across databases.
• Error handling is raw PDOException. Set ATTR_ERRMODE => ERRMODE_EXCEPTION explicitly and translate exceptions at your repository boundary into domain exceptions — don't let PDO errors leak into controllers.
• No query logging or profiling. If you want visibility (Laravel devs are used to DB::listen), add a small wrapper that times and logs around execute().
• Check the constructor contract first. Whether it takes a PDO, a DSN string, or a config array determines your whole wiring story; the README/source is the only source of truth.
• Extension points are minimal by design. The realistic extension point is your wrapper class, not the library. Keep the surface area small and the dependency easy to rip out.
• When to skip it entirely: if you're in a Laravel app with a first-party database, use DB::table() — it's maintained, tested, has logging, transactions, and better binding. This package only earns its place when you're outside the framework or deliberately avoiding Illuminate.