From 22da342f3777418aec2b3d2c3e1f9d71c080cbf6 Mon Sep 17 00:00:00 2001
From: Benjamin Braatz <benjamin.braatz@screwerk.com>
Date: Wed, 24 Jul 2024 16:54:56 +0200
Subject: [PATCH] Add documentation

---
 doc/index.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 doc/index.md

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).
-- 
2.34.1