---
title: "PHP"
description: "PHP, Agnesoft Graph Database"
---

import { Callout, Steps } from "nextra/components";

# PHP

The php agdb API client is generated with [openapi-generator](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/php.md). 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](/docs/guides/how-to-run-server) to learn how to run the server.

Looking for... [how to run a server?](/docs/guides/how-to-run-server) | [another language?](/api-docs/openapi) | [embedded db guide?](/docs/guides/quickstart)

## Usage

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

<Steps>
### Install PHP

https://www.php.net/manual/en/install.php

### Install Composer

https://getcomposer.org/download/

### Create your project

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

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

### Add `agnesoft/agdb_api` as a dependency

```bash
composer install agnesoft/agdb_api
```

<Callout>
    Consider using other dev packages such as `phpunit/phpunit` and
    `phpstan/phpstan`.
</Callout>

### Create your main script

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

```php
<?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:

```php
// 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`):

```php
// 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.

<Callout type="info">
    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.
</Callout>

```php
// 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:

```php
// 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

<Callout type="warning">
    Make sure the agdb_server is running at `localhost:3000`.
</Callout>

<Callout>
    If you are running this from the examples you may need to call `composer
    install` first.
</Callout>

```bash
php src/index.php
```

### Full program

https://github.com/agnesoft/agdb/tree/main/examples/server_client_php

</Steps>
