README

Talk to an embedded graph database with PHP.

This project is in the early stages of development! Feel free to play, but bear in mind that there are a lot of missing features!

This package provides a driver for the SQLite-based graph database GraphQLite. If you came here looking for something to handle the GraphQL protocol, you're in the wrong place: try Packagist!

Installation

composer require kynx/gqlite

GraphQLite provides an SQLLite extension that must be available locally. There are a few ways to install it.

Via a Package Manager

brew install graphqlite       # macOS/Linux (Homebrew)
pip install graphqlite        # Python

Make a note of the path it's installed graphqlite.(dylib|so|dll) to - you will need this later.

Download a Release Binary

Binary builds are available from the GraphQLite GitHub repository: https://github.com/colliery-io/graphqlite/releases/latest. Download the dylib, so or dll file suitable for your platform.

Build from Source

See the From Source instructions in the GraphQLite documentation.

Usage

This library provides convenience methods to make managing the nodes and edges of your graph simple and type-safe. It also allows you to query the GraphQLite database using the Cypher language:

use Kynx\GqLite\Graph;
use Kynx\GqLite\ValueObject\Edge;
use Kynx\GqLite\ValueObject\Node;

// replace with path to GraphQLite extension installed above
$extensionPath = getenv('GRAPHQLITE_EXTENSION_PATH');

// Get a connection to an in-memory graph database
$graph = Graph::connect($extensionPath, ':memory:');

// Add some nodes and edges
$graph->nodes->upsert(new Node("alice", ["name" => "Alice", "age" => 30], "Person"));
$graph->nodes->upsert(new Node("bob", ["name" => "Bob", "age" => 25], "Person"));
$graph->edges->upsert(new Edge("alice", "bob", "KNOWS", ["since" => 2020]));

// Query with Cypher
$results = $graph->query('MATCH (a:Person)-[:KNOWS]->(b) RETURN a.name AS a, b.name AS b');
foreach ($results as $row) {
    echo $row['a'] . ' knows ' . $row['b'] . "\n";
}

// outputs:
// Alice knows Bob

To learn more about Cypher, see the Neo4J manual. GraphQLite supports a subset of the language.

To learn more about GraphQLite, see the excellent documentation.

Nodes and Edges

The Graph object has three entrypoints:

Entrypoint	Description
`Graph::nodes`	CRUD operations on nodes
`Graph::edges`	CRUD operations on edges
`Graph::query()`	Execute raw Cypher queries

The CRUD operations consume and return Node and Edge value objects.

A Node has an ID, an associative array of properties and one or more labels. Properties are where you store data associated with the node. Labels are like tags, and are used to query the database for specific nodes.

An Edge connects two nodes. It has a source ID, a target ID, a relation type and an associative array of properties. As with node labels, the relation type is used query the database for specific types of relations.

Queries

The Graph::query() method returns a Result object. Iterating that will give you an associate array. For example, MATCH (n {id: 'alice'}) RETURN n will give you a structure like:

{
  "n": {
    "id": 1,
    "labels": ["Person"], 
    "properties": {
      "id": "alice",
      "name": "Alice",
      "age": 30
    }
  }
}

Note there are two IDs! The first is the identifier generated by SQLite for the node, the second is the one you assigned.

For Cypher queries, only the second is of any use. To avoid confusion we recommend mapping the results to Node and Edge objects. The Usage example above could be re-written:

$results = $graph->query('MATCH (a:Person)-[:KNOWS]->(b) RETURN a, b');
foreach ($results as $row) {
    $a = Node::fromArray($row['a']);
    $b = Node::fromArray($row['b']);
    
    echo $a->id . ' knows ' . $b->id . "\n";
}

// Outputs:
// alice knows bob

See static-analysis.php in the examples directory for the full code, with type-safety thrown in.

Parameters

Just as with SQL, do not pass user input directly into the query. Instead use placeholders and parameters to ensure they are sanitized. Cypher uses the dollar sign to denote a placeholder:

$results = $graph->query('MATCH (a {name: $name})-[:KNOWS]->(b) RETURN a, b', ['name' => $_GET['name']]);

Make sure your query is single-quoted so PHP variables are not expanded!

kynx / gqlite

Maintainers

Details