From: Benjamin Braatz <benjamin.braatz@screwerk.com>
Date: Wed, 24 Jul 2024 14:54:56 +0000 (+0200)
Subject: Add documentation
X-Git-Tag: v0.1.3
X-Git-Url: http://git.graph-it.com/?a=commitdiff_plain;h=refs%2Fheads%2Fmaster;p=graphit%2Fgraph-client.git

Add documentation
---

diff --git a/doc/index.md b/doc/index.md
new file mode 100644
index 0000000..260c389
--- /dev/null
+++ b/doc/index.md
@@ -0,0 +1,65 @@
+# PHP Graph Client
+This is the PHP client library for the [Graph](https://graph-it.com/).
+
+## Installation
+We use `composer` to manage PHP projects and `msgpack` is a dependency of
+the Graph API, so the minimal dependencies needed for a PHP Graph project
+are:
+```shellsession
+$ sudo apt install php-cli php-msgpack composer
+```
+
+Create your project directory, change into it and initialise composer:
+```shellsession
+$ mkdir example
+$ cd example/
+$ composer init
+```
+
+Define the Graph-IT composer repository as additional repository and
+install the `graphit/graph-client` package:
+```shellsession
+$ composer config repositories.graphit composer https://composer.graph-it.com/
+$ composer require graphit/graph-client
+```
+
+In order to use TLS connections to graphs, the certificate of the
+certificate authority and a client certificate chain including the private
+key has to be available.
+
+In our current graph installations the CA certificate is found in
+`/var/lib/graph/var/cert/cacrt/ca.crt.pem` and a chain file with a private
+key is found in `/var/lib/graph/var/cert/srv/local.srv.pem`:
+```shellsession
+$ mkdir etc
+$ scp graph.example.com:/var/lib/graph/var/cert/cacrt/ca.crt.pem etc/
+$ scp graph.example.com:/var/lib/graph/var/cert/srv/local.srv.pem etc/
+```
+
+## Example Script
+As an example, the following script can be put in the `bin/` subdirectory:
+```php
+#!/usr/bin/php
+<?php
+
+require __DIR__ . '/../vendor/autoload.php';
+use Graphit\Graph\Client\Connection;
+$options = [
+        'cafile' => __DIR__.'/../etc/ca.crt.pem',
+        'lofile' => __DIR__.'/../etc/local.srv.pem',
+];
+
+$gc = new Connection('tls://graph.example.com:4439', $options);
+$graphmodul_guid = $gc->attributsknoten('graphmodul_name', 'graph');
+echo "GUID of graph module graph: {$graphmodul_guid}\n";
+```
+
+## Optional: Psalm Linting
+To lint the script with psalm, we can do:
+```shellsession
+$ composer require --dev vimeo/psalm
+$ ./vendor/bin/psalm --init
+$ ./vendor/bin/psalm bin/
+```
+Also consider adding the `bin/` folder to `psalm.xml` (by default only the
+`src/` folder is added).