wikibase-solutions/php-cypher-dsl
A fluent PHP DSL for building Cypher queries for Neo4j. Construct expressive, type-safe graph queries programmatically with an intuitive API, reducing string concatenation and making complex queries easier to read, maintain, and test. Ideal for PHP and Laravel apps working with graph databases.
Architecture fit. php-cypher-dsl is a query-construction library, not a database client. It sits at the "build" layer: your application expresses a graph query as a fluent PHP object graph, and the DSL renders Cypher text that you hand to a driver (e.g., laudis/neo4j-php-client, graphaware/neo4j-php-client) for execution. That is a good architectural seam: it is stateless, has no connection pool, no async runtime, and no opinion on transport. For a PHP/Laravel service that already talks to Neo4j, Memgraph, or RedisGraph, it can be adopted locally without reshaping the surrounding architecture. The value it creates is the same value any query builder creates over string concatenation: composability, reduced stringly-typed code, easier unit testing of query shape, and fewer hand-rolled escaping mistakes.
Integration feasibility. Composer-installable, MIT-licensed, no transitive runtime risk beyond its own dependencies. The integration surface is narrow — construct a query, render it, pass the string plus a parameter map to the driver — so the blast radius of removing it later is small. The real feasibility question is not "can we install it" but "does its Cypher dialect match our target engine." A builder encodes a dialect; if the target is Neo4j 5.x with newer constructs (subqueries, CALL {}, MERGE semantics, UNWIND/FOREACH, APOC-generated patterns), capability coverage must be confirmed rather than assumed. The 19-star, 0-dependent profile means we would be an early adopter, not a follower of a proven path.
Technical risk.
Key questions for the vendor/maintainer. Which PHP versions are supported? What is the release cadence and latest commit date? Which Cypher/engine versions are explicitly targeted? Does it enforce parameterized values, and can it enforce them? Is there a published test suite covering generated output? Is there any stated support or deprecation policy? Does it support MERGE, UNWIND, subqueries, and procedure calls — or only the basic MATCH/WHERE/RETURN grammar? These are the questions that convert "19 stars" into an actual risk-adjusted judgment.
Stack fit. Straightforward for any Composer-managed PHP 8.x application, including Laravel. It composes naturally with a clean repository layer: repositories own the driver and the parameter map, the DSL owns query shape, controllers and jobs never see Cypher strings. That separation is the leverage point — it lets the TPM standardize how graph queries are written and reviewed across teams without standardizing on a database driver.
Migration path. Do not start with a big-bang rewrite. Sequence it as: (1) pick one non-critical read path, (2) implement it twice — raw Cypher and DSL — and diff the rendered output and execution plans, (3) adopt for new code first while legacy raw strings stay put, (4) backfill only where the DSL demonstrably reduces defects or code volume. The narrow, string-in/string-out interface means partial adoption is safe; there is no all-or-nothing cutover.
Compatibility. Pin the package version and pin the target database version in CI. Add a golden-file test that renders each DSL-built query and asserts the exact Cypher against a known dialect. Run those against a real database container in CI so dialect drift is caught as a test failure rather than a production incident. If a construct is missing, keep an escape hatch: allow raw Cypher fragments inside the builder rather than forcing awkward workarounds, and track those escape hatches as tech debt.
Sequencing. Evaluation spike (1–2 days) → dialect compatibility proof on our actual engine → security review of parameter handling → pilot on one team's read path → publish internal usage guidance and a supported-subset list → expand. Define an explicit exit criterion up front (e.g., "if the package is unmaintained for 12 months or blocks a required construct for more than a sprint, we fork or revert to a thin in-house builder").
Maintenance. This is the dominant cost. With a single publisher and sparse activity, we should assume eventual fork ownership. Budget for it now: vendor it via a Composer path/VCS repository or an internal fork, and treat upstream as an optional source of patches. Keep our fork's diff small so re-syncing remains cheap.
Support. Community-only. There is no commercial SLA, no security advisory process we can rely on, and no expectation of timely fixes. For an internal tool this is acceptable; for anything customer-facing or regulated, it means we own the security posture — including tracking Cypher injection issues ourselves. MIT means legal review is trivial, which is a genuine advantage.
Scaling. The library itself is not a scaling bottleneck: rendering a string is O(query size) and happens per request, and connection pooling, retries, and timeouts remain the driver's and the database's responsibility. The scaling risk is indirect — a builder can make it easy to emit expensive Cypher (unbounded traversals, missing LIMIT, cartesian products) at high volume. Pair adoption with query-plan review and slow-query monitoring on the graph side; the DSL should not be treated as a performance guardrail.
Failure modes.
Ramp-up. Low. The API surface is small and the underlying language is a known quantity, so a developer fluent in Cypher should be productive in under a day and a team standardized on it within a sprint. The training investment that matters is not the DSL but Cypher itself and query-plan literacy — without that, the builder hides the cost of bad queries. Pair the rollout with a short internal guide covering the supported subset, parameterization rules, and the raw-fragment escape hatch.
TPM bottom line. This is a cheap, low-coupling utility that improves query-construction hygiene and testability in a PHP graph application. The opportunity score and adoption metrics correctly say "tactical, not strategic": adopt it as an internal convenience behind a repository layer, with a fork contingency and dialect regression tests already in place, rather than treating it as a platform dependency.
How can I help you explore Laravel packages today?