From c820a4023a67030d29a98c198d60f043749cd121 Mon Sep 17 00:00:00 2001
From: Daniil Gentili <daniil@daniil.it>
Date: Sat, 29 Jun 2024 16:36:05 +0200
Subject: [PATCH] Improve readme

---
 README.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 136 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 79bebea..0b9d4f3 100644
--- a/README.md
+++ b/README.md
@@ -23,15 +23,147 @@ composer require danog/async-orm
 
 There are two main ways to use the ORM: through automatic ORM properties, which automatically connects appropriately marked `DbArray` properties to the specified database, or by manually instantiating a `DbArray` with a `DbArrayBuilder`.
 
-* [Automatic ORM properties example &raquo;](https://github.com/danog/AsyncOrm/blob/master/examples/1-automatic.php)
-* [Manual example &raquo;](https://github.com/danog/AsyncOrm/blob/master/examples/2-manual.php)
-
-The `DbArray` obtained through one of the methods above is an abstract array object that automatically stores and fetches elements of the specified [type &raquo;](#value-types), from the specified database.  
+The `DbArray` obtained through one of the methods below is an abstract array object that automatically stores and fetches elements of the specified [type &raquo;](#value-types), from the specified database.  
 
 `DbArray`s of type `ValueType::OBJECT` can contain objects extending `DbObject`.  
 
 Classes extending `DbObject` have a special `save` method that can be used to persist object changes to the database, as can be seen in the [example](https://github.com/danog/AsyncOrm/blob/master/examples/2-manual.php).  
 
+
+### Automatic ORM properties example
+
+```php
+<?php declare(strict_types=1);
+
+use Amp\Mysql\MysqlConfig;
+use Amp\Postgres\PostgresConfig;
+use Amp\Redis\RedisConfig;
+use danog\AsyncOrm\Annotations\OrmMappedArray;
+use danog\AsyncOrm\DbArray;
+use danog\AsyncOrm\DbAutoProperties;
+use danog\AsyncOrm\DbObject;
+use danog\AsyncOrm\KeyType;
+use danog\AsyncOrm\Settings;
+use danog\AsyncOrm\Settings\MysqlSettings;
+use danog\AsyncOrm\Settings\PostgresSettings;
+use danog\AsyncOrm\Settings\RedisSettings;
+use danog\AsyncOrm\ValueType;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+// Any of the following database backends can be used,
+// remove the ones you don't need.
+$settings = new MysqlSettings(
+    new MysqlConfig(
+        host: "/var/run/mysqld/mysqld.sock",
+        user: 'user',
+        password: 'password',
+        database: 'database'
+    ),
+    cacheTtl: 100
+);
+$settings = new PostgresSettings(
+    new PostgresConfig(
+        host: "127.0.0.1",
+        user: "user",
+        password: "password",
+        database: "database"
+    ),
+    cacheTtl: 100
+);
+$settings = new RedisSettings(
+    RedisConfig::fromUri("redis://127.0.0.1"),
+    cacheTtl: 100
+);
+
+/**
+ * An object stored in a database.
+ */
+class MyObject extends DbObject
+{
+    public function __construct(
+        private string $value
+    ) {
+    }
+    public function setValue(string $value): void
+    {
+        $this->value = $value;
+    }
+    public function getValue(): string
+    {
+        return $this->value;
+    }
+}
+
+/**
+ * Main class of your application.
+ */
+final class Application
+{
+    use DbAutoProperties;
+
+    /**
+     * This field is automatically connected to the database using the specified Settings.
+     *
+     * @var DbArray<string, MyObject>
+     */
+    #[OrmMappedArray(KeyType::STRING, ValueType::OBJECT)]
+    private DbArray $dbProperty1;
+
+    /**
+     * This field is automatically connected to the database using the specified Settings.
+     *
+     * @var DbArray<string, int>
+     */
+    #[OrmMappedArray(KeyType::STRING, ValueType::INT)]
+    private DbArray $dbProperty2;
+
+    public function __construct(
+        Settings $settings,
+        string $tablePrefix
+    ) {
+        $this->initDbProperties($settings, $tablePrefix);
+    }
+
+    public function businessLogic(): void
+    {
+        $this->dbProperty1['someOtherKey'] = new MyObject("initialValue");
+
+        // Can store integers, strings, arrays or objects depending on the specified ValueType
+        $this->dbProperty2['someKey'] = 123;
+        var_dump($this->dbProperty2['someKey']);
+    }
+
+    public function businessLogic2(string $value): void
+    {
+        $obj = $this->dbProperty1['someOtherKey'];
+        $obj->setValue($value);
+        $obj->save();
+    }
+
+    public function businessLogic3(): string
+    {
+        return $this->dbProperty1['someOtherKey']->getValue();
+    }
+
+    public function shutdown(): void
+    {
+        // Flush all database caches, saving all changes.
+        $this->saveDbProperties();
+    }
+}
+
+$app = new Application($settings, 'tablePrefix');
+$app->businessLogic();
+$app->businessLogic2("newValue");
+var_dump($app->businessLogic3());
+$app->shutdown();
+```
+
+### Manual ORM properties example
+
+See [here &raquo;](https://github.com/danog/AsyncOrm/blob/master/examples/2-manual.php)
+
 ### Settings
 
 As specified in the examples above, there are multiple settings classes that can be used to connect to a specific database type: