From 9eae36c1b04ca86a0d614e7dd96153bb3714c746 Mon Sep 17 00:00:00 2001
From: Joby Elliott <joby@byjoby.com>
Date: Sat, 12 Jan 2019 05:49:18 +0000
Subject: [PATCH] Update README.md

---
 README.md | 37 ++++++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 502bae9..70c74e2 100644
--- a/README.md
+++ b/README.md
@@ -20,16 +20,23 @@ In order to read/write objects from a database table, you'll need to configure a
 ```php
 // DriverFactory::factory() has the same arguments as PDO::__construct
 // You can also construct a driver directly, from a class in Drivers,
-// but for common databases DriverFactory::factory should pick the right class
+// but for common databases DriverFactory::factory should pick the right class.
+// Note: It's important to specify a character set, because malformed characters
+// completely break PHP's json_decode() function.
 $driver = \Destructr\DriverFactory::factory(
-  'mysql:host=127.0.0.1',
+  'mysql:host=127.0.0.1;charset=utf8',
   'username',
   'password'
 );
 // Driver is then used to construct a Factory
 $factory = new \Destructr\Factory(
-  $driver,      //driver is used to manage connection and generate queries
-  'dso_objects' //all of a Factory's data is stored in a single table
+  // a Driver is used to manage connection and generate queries
+  $driver,
+  // all of a Factory's data is stored in a single table, to split data between
+  // multiple tables, you'll need to create multiple Factories. Drivers can be
+  // reused across multiple Factories, and only a single connection will be
+  // used, if supported by the database.
+  'dso_objects'
 );
 ```
 
@@ -39,8 +46,13 @@ Next, you can use the factory to create a new record object.
 
 ```php
 // by default all objects are the DSO class, but factories can be made to use
-// other classes depending on what data objects are instantiated with
-$obj = $factory->create();
+// other classes depending on what data objects are instantiated with.
+// create() can be optionally given an array of initial data.
+$obj = $factory->create(['foo'=>'bar');
+
+// once created, an object can be worked with like a SelfReferencingFlatArray
+// see https://gitlab.com/byjoby/flatrr for more information about that
+$obj['bar.baz'] = 'buzz';
 
 // returns boolean indicating whether insertion succeeded
 // insert() must be called before update() will work
@@ -66,11 +78,22 @@ $obj->delete(true);
 
 ## Requirements
 
+### Suggested databases
+
+Currently, Destructr is best supported by MySQL 5.7, SQLite 3, and MariaDB >=10.2.
+
+If you only have access to a MySQL 5.6 server there is a driver available, but it's buggy and not as well tested.
+Given the choice, you should almost always choose SQLite over MySQL <=5.6.
+The SQLite driver is actually very fast in benchmarks, and performs very close to the same speed as MySQL 5.7 for simple queries or small databases with object counts on the order of a few thousand.
+For efficient indexing of non-standard JSON paths or large numbers of objects, MySQL 5.7 or MariaDB >=10.2 is highly recommended.
+
+### Theoretical minimum versions
+
 This system relies **heavily** on the JSON features of the underlying database.
 This means it cannot possibly run without a database that supports JSON features.
 Exact requirements are in flux during development, but basically if a database doesn't have JSON functions it's probably impossible for Destructr to ever work with it.
 
-In practice this means Destructr will **never** be able to run on less than the following versions of the following popular databases:
+In practice this means Destructr will **never** be able to run properly on less than the following versions of the following popular databases:
 
 * MySQL >=5.7
 * MariaDB >=10.2