Neo4J Bundle Laravel Package

Technical Evaluation

Architecture fit — fundamental mismatch. Despite the framing of this evaluation, mspa/neo4j-bundle is not a Laravel package; it is a Symfony bundle. It ships a Bundle subclass, DI service definitions, and a Symfony Configuration tree that expects to be registered in config/bundles.php and compiled by Symfony's Kernel. Laravel has no bundle system — its service container, config repository, and bootstrapping lifecycle are structurally different. There is no neo4j-bundle service provider, facade, or config/neo4j.php publish path. Treating this as a drop-in Laravel dependency is not feasible; any use requires porting the wiring.

Integration feasibility — moderate, via extraction rather than installation. The bundle is thin glue. Its real value is whichever PHP driver it wraps (typically graphaware/neo4j-php-client for Bolt/HTTP). A Laravel integration would more sensibly depend on that driver directly and reimplement ~150 lines of container binding: a singleton client, config, and a facade. The bundle itself contributes little that cannot be rebuilt in an afternoon.

Technical risk — high, driven by adoption signals. 0 stars, 0 dependents, and a 0.03 composite score indicate effectively zero production usage and no ecosystem validation. Specific concerns:

Key questions to resolve before any commitment:

1. Which underlying Neo4j client and version does it require, and is that library maintained?
2. What are the composer.json PHP/Symfony constraints, and do they resolve against our Laravel version's Symfony component pins?
3. Does it support Bolt (binary, pooled) or only HTTP? This drives latency and throughput materially.
4. Is there any commit activity in the last 12 months? If not, we are adopting a fork.
5. What transaction/session semantics does it expose — implicit sessions per call, or a managed lifecycle suitable for long-running workers?
6. Any authentication/Kerberos/TLS configuration surface, and does it meet our security baseline?

Recommendation at evaluation stage: do not adopt the bundle. Adopt the underlying driver and own the integration layer.

Integration Approach

Stack fit — poor as packaged, acceptable as a pattern. A Laravel application already carries Symfony components (via illuminate/*), so the bundle's transitive dependencies are not fatal — but installing a Symfony bundle into Laravel yields no functioning registration. The correct target is: graphaware/neo4j-php-client (or laudis/neo4j-php-client, its maintained successor) + a Laravel service provider.

Migration path:

1. Fork or vendor the bundle into app/Neo4j or a private Composer package. Use it as reference implementation, not a runtime dependency.
2. Reimplement as a Laravel package with the standard shape: Neo4jServiceProvider, Neo4j facade, config/neo4j.php (host, port, scheme, auth, database, pool size, timeout), and a Neo4jManager singleton resolving a driver instance.
3. Abstract behind a repository port — define GraphRepository interfaces in the domain layer so the driver is swappable and testable with an in-memory fake.
4. Bind lifecycle hooks — app()->terminating() to close the driver; explicit session cleanup for queue workers and Octane.

Compatibility sequencing:

• Phase 0 (spike, ~1 day): confirm the driver package resolves against our PHP/Laravel constraints; verify Bolt connectivity to our Neo4j version; measure p50/p95 query latency from the app tier.
• Phase 1 (foundation): ship the provider, config, facade, and a health check endpoint. No domain code yet.
• Phase 2 (bounded context): integrate a single, well-isolated graph use case — recommendations, permissions resolution, or fraud ring detection — behind the repository port. Do not co-mingle relational and graph writes in one transaction; there is no distributed transaction here.
• Phase 3 (hardening): retry/backoff, circuit breaker, query timeouts, observability spans.
• Phase 4 (optional): only if the graph use case proves out, promote to an internal shared package.

Constraint to note: every Symfony→Laravel port must replace Symfony\Component\Config\Definition validation with Laravel's config() + a validator, and replace EventDispatcher wiring with Laravel events. Budget for this — it is the actual work.

Operational Impact

Maintenance — we own it. With zero dependents and a single maintainer, upstream is unlikely to respond to issues or merge PRs. Assume the fork becomes the source of truth within one quarter. Budget ~10–15% of one engineer's time for the first two quarters, tapering to reactive maintenance. Pin exact versions and vendor the code into our monorepo or private registry so an upstream deletion cannot break builds.

Support — none external. No community, no Stack Overflow corpus, no Slack. Internal runbooks and a documented upgrade procedure for Neo4j major versions are mandatory. Second-engineer onboarding is the real support cost.

Scaling — dominated by Neo4j, not by this code. The bundle is not the bottleneck; the cluster and query patterns are. Operational specifics:

• Connection pooling: ensure the driver reuses connections across requests; a per-request driver instantiation will exhaust connections under load.
• Long-lived processes: queue workers and Octane hold connections open. Without an idle timeout and reconnect logic, workers will surface stale-connection errors after Neo4j failover. This is the single most common production failure in PHP graph integrations.
• Read/write routing: if using a causal cluster, verify the driver supports routing (neo4j:// scheme) and read-your-own-writes bookmarks. The bundle may not expose this.
• Query cost: graph traversals can be unbounded. Enforce LIMIT, statement timeouts, and per-tenant query budgets at the application layer since the driver will not.

Failure modes to instrument for:

Ramp-up — asymmetric. API surface is small; a mid-level engineer wires the provider in a day. The hidden cost is graph data modeling, Cypher proficiency, and Neo4j operational knowledge — none of which this package provides. If the team lacks graph experience, add 3–4 weeks of enablement before Phase 2, and consider a Neo4j-certified contractor for the initial schema and index design.

Bottom line for a TPM: the package is a useful reference and a poor dependency. Its 0.03 score is an accurate signal. Fund a one-week spike to evaluate the underlying driver against a real Neo4j instance; approve production use only after Phase 1 lands with health checks, connection lifecycle handling, and an owned fork under our control.