Pg Wrapper Laravel Package

Product Decisions This Supports

• Build vs. buy on Postgres type marshalling. Any PHP service that reads or writes Postgres array, enum, composite, range, hstore, json, geometric, or network types either writes its own conversion layer or adopts something like this. This package is the "buy" option: it replaces an in-house parser with a maintained, BSD-2 licensed library.
• Whether to use Postgres-native modelling instead of least-common-denominator schemas. Teams often flatten Postgres features into TEXT/JSON columns because PHP-side handling is painful. Low-friction type conversion makes native ENUM state machines, TSTZRANGE scheduling windows, composite address/money types, and array-valued tags cheap to adopt, which changes the data-model argument in design reviews.
• Roadmap gating for Postgres-heavy features. If the roadmap includes features that lean on ranges (availability windows, pricing tiers), arrays (tagging, feature flags per tenant), or enums (workflow states), this package is an enabling dependency that should be assessed before those epics are estimated, not discovered mid-sprint.
• Use cases where it earns its place: analytics/event ingestion writing array and JSONB payloads, scheduling and booking systems using range types, multi-tenant config with composite settings, geo/network data (CIDR, point, lseg), and any internal tooling where raw SQL plus typed results beats ORM abstraction.
• Architecture decision on the data-access layer. It is an OO wrapper over ext-pgsql, not PDO. Choosing it is implicitly a decision to bypass PDO — and therefore Eloquent's connection, transaction, and query-builder stack — for the queries that need it. That's a real architectural fork worth logging in an ADR.

When to Consider This Package

Adoption criteria — pursue a spike when most of these hold:

• You are committed to Postgres (12+; verify the package's current PHP/PG minimums against your runtime) and will not need MySQL/SQLite portability for the affected services.
• You have a concrete, painful type-mapping problem today: hand-rolled array parsing, stringly-typed enums, or range/JSON columns treated as opaque blobs.
• Your team is comfortable with raw SQL and can own a thin internal adapter around the library.
• The affected code paths can tolerate a separate connection from the ORM — or the work is greenfield/CLI/job-side, where dual connection stacks and split transactions are not a problem.
• You are willing to pin the version, vendor-lock the dependency, and budget a day or two of spike work to validate against your actual schema.

Look elsewhere when:

• You need first-class Eloquent/PDO integration, shared transactions, or query-builder composability — a PDO-compatible type layer or ORM extension is a better fit.
• Portability across database engines is a near-term requirement.
• The team cannot absorb maintenance risk: community signal is thin (≈22 stars, 0 dependents, single-maintainer profile). That is not disqualifying — well-maintained single-author PHP/Postgres libraries are common — but it means you are the ecosystem validation. Require an internal review of the test suite, release cadence, and issue responsiveness before relying on it in a revenue path.
• The need is narrow (e.g., only JSONB, which your framework already handles). The wrapper's value scales with how many complex types you actually touch; for one type, hand-rolled conversion may be cheaper than a dependency.
• You require commercial support or a vendor SLA.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a recurring engineering tax: every time we want to use a real Postgres feature — arrays, enums, ranges, composite types — someone writes and maintains conversion code, and it breaks in production. sad_spirit/pg_wrapper is a small, permissively licensed (BSD-2) library that already solves this, letting us model data natively in Postgres instead of flattening it into text and JSON columns. Expected benefit is reduced custom code and fewer data-shape bugs, at effectively zero licence cost. The trade-off is dependency risk: it is a low-adoption, single-maintainer project, so the recommendation is a short, time-boxed spike plus an internal wrapper class that isolates us from it — roughly two engineer-days of insurance against a rewrite we would otherwise own indefinitely.

For engineering (bullets):

• OO wrapper over ext-pgsql with a pluggable type-conversion layer: arrays, enums, composites, ranges, hstore, JSON, geometric and network types map to and from proper PHP values instead of strings.
• Removes bespoke parsing/serialisation and the off-by-one bugs that come with Postgres array literals and range bounds.
• Caveat: it is not PDO, so it will not sit underneath Eloquent. Plan for a second connection for the queries that need it, or confine it to jobs/CLI/read paths where transaction scope is not shared.
• Mitigations: pin the version, wrap it behind one internal TypeBridge/repository interface so the surface area is a handful of call sites, and add integration tests against the real schema in CI.
• Exit cost is low if isolated — that wrapper is the whole point: swapping the library later is a one-class change, not a codebase migration.