PHP

The php agdb API client is generated with openapi-generator (opens in a new tab). The following is the quickstart guide for the agdb client in PHP (connecting to the server). It assumes an agdb_server is running locally. Please refer to the server guide to learn how to run the server.

Looking for... how to run a server? | another language? | embedded db guide?

Usage

The following is the from-scratch guide to use agdb-api php package.

Install PHP

https://www.php.net/manual/en/install.php (opens in a new tab)

Install Composer

https://getcomposer.org/download/ (opens in a new tab)

Create your project

Create your project's folder (e.g. my_agdb) and initialize the package:

mkdir my_agdb
cd my_agdb
composer init # follow the steps & prompts

Add `agnesoft/agdb_api` as a dependency

composer install agnesoft/agdb_api

💡

Consider using other dev packages such as phpunit/phpunit and phpstan/phpstan.

Create your main script

E.g. src/index.php and create a client to connect to the server:

<?php
// Needed to load the libraries installed by composer
require 'vendor/autoload.php';
 
use Agnesoft\AgdbApi\Api\AgdbApi;
use Agnesoft\AgdbApi\Model\DbType;
use Agnesoft\AgdbApi\Model\UserLogin;
use Agnesoft\AgdbApi\Model\UserCredentials;
use Agnesoft\AgdbApi\QueryBuilder;
use Agnesoft\AgdbApi\ComparisonBuilder;
 
// Default config will look for the server at http://localhost:3000
$config = Agnesoft\AgdbApi\Configuration::getDefaultConfiguration();
 
// Using GuzzleHttp client. You can use any other like Symfony.
$client = new AgdbApi(new GuzzleHttp\Client(), $config);
 
// Runs the status query against the database
// and throws if the server is not accessible.
$client->status(false);

Create a database user

To create a database user we use the default admin user:

// Login as server admin
$token = self::$client->userLogin(
    new UserLogin(["username" => "admin", "password" => "admin"])
);
$client->getConfig()->setAccessToken($token);
 
// Creat user "php_user1"
$client->adminUserAdd(
    "php_user1",
    new UserCredentials(["password" => "php_user1"])
);
 
// Login as "php_user1"
$token = self::$client->userLogin(
    new UserLogin([
        "username" => "php_user1",
        "password" => "php_user1",
    ])
);
$client->getConfig()->setAccessToken($token);

Create a database

To create a database we associate it with a user and give it a name and type (one of MAPPED, MEMORY, FILE):

// Creates memory mapped database "db1" for user "php_user1"
$client->dbAdd("php_user1", "db1", DbType::MAPPED);

Execute queries

To execute queries against the database we call dbExec with the user and their database.

Notice we are feeding results of the previous query to the next one with special alias ":0" and ":1" referencing first and second result respectively.

// Prepare the queries to be executed on the remote database.
$queries = [
    // :0: Inserts a root node aliased "users".
    QueryBuilder::insert()
        ->nodes()
        ->aliases(["users"])
        ->query(),
 
    // :1: Inserts more nodes with some data.
    QueryBuilder::insert()
        ->nodes()
        ->values([
            [
                "username" => "user1",
                "password" => "password123",
            ],
            [
                "username" => "user2",
                "password" => "password456",
            ],
        ])
        ->query(),
 
    // :2: Connect the root to the inserted nodes with edges referencing both from previous queries.
    QueryBuilder::insert()->edges()->from(":0")->to(":1")->query(),
 
    // :3: Find a node starting at the "users" node (could also be ":0" in this instance) with specific username.
    QueryBuilder::select()
        ->search()
        ->from("users")
        ->where()
        ->key("username")
        ->value(ComparisonBuilder::Equal("user1"))
        ->query()
];
 
// Execute queries.
$result = $client->dbExec("php_user1", "db1", $queries);

Print the the result

We print the result of the of the final query to the console:

// Print the result of the last query
printf($result[3]);
 
// {
//     "elements": [
//         {
//             "from": null,
//             "id": 3,
//             "to": null,
//             "values": [
//                 {
//                     "key": {
//                         "String": "username"
//                     },
//                     "value": {
//                         "String": "user1"
//                     }
//                 },
//                 {
//                     "key": {
//                         "String": "password"
//                     },
//                     "value": {
//                         "String": "password456"
//                     }
//                 }
//             ]
//         },
//     ],
//     "result": 1
// }

Run the program

⚠️

Make sure the agdb_server is running at localhost:3000.

💡

If you are running this from the examples you may need to call composer install first.

php src/index.php

Full program

https://github.com/agnesoft/agdb/tree/main/examples/server_client_php (opens in a new tab)

Rust Javasscipt/Typescript

PHP