Versaorm Php Laravel Package

Product Decisions This Supports

• Feature: AI/semantic retrieval without buying a vector database. The package is the cheapest credible path to pgvector similarity search inside an existing Laravel + PostgreSQL 16 stack. If a search, "related items," or RAG-style feature is on the roadmap, this lets you ship a vertical slice with zero new infrastructure spend and no second datastore to operate, secure, or back up. That is a real roadmap unlock, not a nice-to-have.
• Build vs buy — but frame the "buy" honestly. The true alternative is not Eloquent; it is DB::select() with hand-written SQL, which is already in the stack, already free, and already owned by your team. So the decision is "add a fifth dependency and a second PDO connection" versus "write ~40 lines of SQL per query." This package wins only when the query volume and complexity inside that one workload justify it. For a single aggregate endpoint, it does not.
• Use cases worth scoping now: vector similarity search on documents/embeddings; analytical read paths on a replica (revenue, cohorts, funnel arithmetic); admin CSV/report exports that would otherwise be raw SQL heredocs; an Artisan documents:reindex command that owns embedding writes and query rebuilds in one place; ingestion/staging tables Eloquent does not and should not own.
• Explicit non-decision: it does not replace Eloquent. No service provider, no facade, no DB driver, no model events, casts, factories, soft deletes, policies, or paginate(). Every Laravel convenience you rely on today would become a scoped engineering task. The product decision is coexistence, and that decision must be written down so nobody interprets adoption as a migration.
• TCO you must budget for, not discover: a second connection per request, hand-rolled pagination on every listing view, repository wrappers around every builder chain, and a team member who owns dependency triage and upgrade gates permanently. That is roughly a sprint of setup plus ongoing ~10% of one engineer's attention.
• Roadmap optionality has an exit door. Because usage is confined to a few repository classes, ripping it out for raw SQL or a managed vector DB is a contained refactor. That low switching cost is what makes a pilot defensible in front of a risk-averse steering committee.

When to Consider This Package

Adopt (as a timeboxed pilot, pinned to 2.0.1):

• You are on Laravel with PostgreSQL 16, pgvector is available or cheap to enable, and a retrieval or analytics feature is genuinely blocked today.
• The workload is narrow, read-mostly, and lives behind repository classes — not in hot CRUD paths or request-critical write flows.
• You have one senior engineer who can own changelog triage, write regression tests asserting non-null on every computed column, and gate upgrades behind your own integration tests.
• You can guarantee staging runs the production engine. The engine asymmetry here is severe: a binding defect crashed loudly on PostgreSQL and returned silent NULLs on SQLite and MySQL. Multi-engine CI is a testing convenience; it is not a safety net.
• You accept a hard bus-factor of roughly one maintainer, 5 stars, and 0 dependents, and your compliance posture permits an unproven third-party dependency in a non-critical path.

Look elsewhere:

• Any path where a silent NULL in a price, score, ranking, or aggregate would produce a wrong business number or a bad customer decision. In 2.0.0 that was the documented failure mode, and the headline pgvector feature shipped with all 13 of its tests skipped in both local and CI. That is a maturity signal, not a one-off.
• You need events, casts, factories, soft deletes, withCount, read/write splitting, multi-tenancy, or first-party package compatibility. All of it is absent by design and would be hand-rolled.
• MySQL or SQLite shops. The bug that motivated 2.0.1 was invisible on exactly those engines.
• Vector volume or latency SLOs pointing past the low millions — at that point a dedicated vector store is the right call and the "no new infra" advantage evaporates.
• Your need is only aggregates. Laravel's own query builder and DB::select already cover that without a dependency. Also check whether first-party Laravel Postgres/vector support or a better-maintained alternative covers the retrieval case before committing.
• Anything user-facing and latency-sensitive in the same request as Eloquent CRUD, unless you are comfortable with two PDO connections and Octane/long-lived-worker connection behaviour.

Recommendation: run a one-sprint, read-only spike against a restored production copy. Go/no-go on three gates — retrieval works on your real data, staging is engine-identical to production, and every computed column is asserted non-null in your own tests. No production writes through this package in phase one.

How to Pitch It (Stakeholders)

For executives: We can evaluate semantic search on the database we already run, for the cost of one engineer for one sprint and no new infrastructure, no vendor contract, no data-export or privacy review. The exposure is deliberately capped: read-only, behind a handful of wrapper classes, replaceable with plain SQL or a managed vector service in days if it disappoints. The realistic outcome is either a shipped feature at near-zero marginal infrastructure cost, or a cheap and well-documented "no."

For engineering: This is a standalone, PDO-backed ORM — not an Eloquent replacement, not a Laravel package. It ships no service provider or facade; we register it ourselves as a lazily-resolved singleton reading from the same .env, and we confine every ->table() chain to app/Queries/. It buys us fluent pgvector similarity search, selectRaw aggregate paths that read better than heredoc SQL, and a clean home for reindex commands and replica reads. In exchange we accept two connections, hand-rolled pagination, no casts/events/factories, and a hard rule that writes and transactions stay in Eloquent — you cannot straddle two connections inside a transaction.

The risk paragraph — say it out loud, don't bury it: the project is early. 5 stars, no dependents, one maintainer, and its most recent patch fixed a defect that returned silent NULLs rather than errors on two of three supported engines. Its vector support had never actually executed in CI before that release. PHPStan level 9 and a clean style check are genuine positives, but they did not catch it. We therefore pin the exact version, treat every changelog as a correctness note, own our own upgrade gate, and keep anything touching money, ranking, or pricing out of this package until it has a track record with us. If the spike passes, we revisit in a quarter with real usage data; if it fails, we have lost one sprint and learned something concrete about our own retrieval requirements.