Bringing Neo4j into Laravel

Graph Database Power Without Leaving the Laravel Ecosystem

Laravel developers are used to working with Eloquent, the Query Builder, database connections, and familiar application patterns. But what happens when the data your application needs is not just about records, but about the relationships between them?

Think about a recommendation engine, a social network, a fraud detection system, a knowledge graph, or an application where users, products, transactions, and organizations are deeply connected. This is where Neo4j becomes interesting.

Neo4j is a graph database designed to represent and query connected data. And a team working on the PHP and Laravel ecosystem, we wanted to make integrating it into Laravel applications feel more natural.

That is why we maintain Neo4j Laravel, an open-source package that brings Neo4j integration into the Laravel database ecosystem.

GitHub – neo4j-php/neo4j-laravel

The goal: make graph data feel familiar to Laravel developers

Introducing another database into a Laravel project should not mean abandoning the development patterns you already know.

With Neo4j Laravel, you can connect to Neo4j through Laravel’s database layer and execute Cypher queries using the familiar DB facade:

use Illuminate\Support\Facades\DB;

$movies = DB::connection('neo4j')->select(
    <<<'CYPHER'
        MATCH (m:Movie {title: $title})
        RETURN m
    CYPHER,
    ['title' => 'The Matrix']
);Code language: PHP (php)

Notice what this gives you: an explicitly named Neo4j connection, parameterized queries, and a familiar Laravel API.

You can continue using SQL databases for the parts of your application that fit a relational model, while using Neo4j for data where connections are central to the problem.

Eloquent support, not just a database connection

A database integration becomes much more useful when it fits into the way Laravel applications are actually built.

Neo4j Laravel supports Eloquent-style models through its HasNeo4jConnection concern. You can define a model and use familiar operations to retrieve, create, update, and delete graph-backed data.

use Illuminate\Database\Eloquent\Model;
use Neo4j\Neo4jLaravel\Concerns\HasNeo4jConnection;

class User extends Model
{
    use HasNeo4jConnection;

    protected $fillable = ['name', 'email'];
}Code language: PHP (php)

Then work with it using familiar syntax:

$user = User::where('name', 'Zaeem')->first();

$user = User::create([
    'name' => 'Zaeem',
    'email' => '[email protected]',
]);

$user->update(['name' => 'Zaeem Ansari']);Code language: PHP (php)

The package also provides a dedicated Neo4jModel for applications that prefer an explicit model class for graph-backed data.

The idea is straightforward: you should not have to learn an entirely different application-development workflow just to start working with a graph database.

Where graph databases become really interesting: relationships

Consider a movie application. A relational database can represent movies, actors, and their associations using tables and joins. Neo4j lets you represent these connections directly as graph relationships:

MATCH (person:Person)-[:ACTED_IN]->(movie:Movie)
WHERE person.name = $name
RETURN movieCode language: PHP (php)

This becomes particularly useful when you want to explore connected data, such as finding movies that share actors or discovering relationships across multiple steps.

Neo4j Laravel includes relationship-oriented query capabilities, including matchRelationship(), so graph patterns can be expressed through its Query Builder and supported Eloquent relationship APIs.

For example:

$actors = DB::connection('neo4j')
    ->table('Person')
    ->matchRelationship('ACTED_IN>', 'Movie', 'role', 'film')
    ->where('film.title', 'The Matrix')
    ->get();Code language: PHP (php)

For Eloquent models, graph relationships can also support operations such as lazy loading, eager loading, attaching, syncing, detaching, and creating related nodes.

This is an important distinction: the package is not limited to sending raw Cypher strings to Neo4j. It aims to make graph operations fit more naturally into Laravel’s smooth existing development experience.

More than basic CRUD

A useful database integration has to address the everyday details of application development, too.

Neo4j Laravel includes capabilities such as:

• Transactions: manage related database operations within a transaction.
• Parameterized queries: pass values separately from Cypher statements.
• Pagination: use supported Laravel pagination APIs with Cypher-backed queries.
• Relationship operations: create and manage graph connections through supported query and model APIs.
• Soft deletes: use Laravel’s SoftDeletes behavior on supported Neo4j models.
• Connection configuration: configure authentication, SSL, connection pooling, and timeouts.
• Query logging: send query logs through Laravel’s logging system.
• Laravel Debugbar integration: inspect captured Cypher queries in the shared Queries tab when the supported integration is installed and configured.

These details matter because adopting a database is not just about making the first query work. It is about making the integration useful throughout the development and debugging lifecycle.

You do not necessarily need to replace MySQL or PostgreSQL

One thing worth clarifying: adopting Neo4j does not automatically mean replacing your existing database.

For many Laravel applications, a sensible starting point is to keep MySQL, PostgreSQL, or SQLite as the primary database and configure Neo4j as a secondary connection for graph-oriented data.

That lets you choose the database based on the problem you are solving.

A relational database may remain the right choice for conventional business records, while Neo4j can handle use cases where traversing relationships is central to the application.

The package’s current documentation also notes limitations around using Neo4j as the default connection for Laravel features that depend on the conventional database and Eloquent authentication setup. It is worth reviewing those considerations before choosing your database architecture.

Built for the PHP and Laravel community

We see Neo4j Laravel as part of a broader effort to make graph database development more accessible to PHP developers.

The goal is not to hide Neo4j or pretend that graph databases work exactly like relational databases. It is to provide a Laravel-friendly integration while preserving access to the capabilities that make Neo4j valuable.

There is still room to grow, and real-world feedback from Laravel developers is an important part of making the integration more useful.

If you are building applications involving recommendations, interconnected entities, dependency networks, knowledge graphs, or other relationship-heavy data, we would encourage you to take a look.

Please share any feedback or issues you find on the repository.

Explore the repository:

GitHub – neo4j-php/neo4j-laravel

---

Bringing Neo4j into Laravel was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.