Move config, installation & philosophy into Sphinx

4 files changed, 269 insertions, 0 deletions

diff --git a/docs/configuration.rst b/docs/configuration.rst
new file mode 100644
index 0000000..03e1d38
--- /dev/null
+++ b/docs/configuration.rst
@@ -0,0 +1,212 @@
+Configuration
+=============
+
+The first thing you need to know about Idiorm is that *you don’t need to
+define any model classes to use it*. With almost every other ORM, the
+first thing to do is set up your models and map them to database tables
+(through configuration variables, XML files or similar). With Idiorm,
+you can start using the ORM straight away.
+
+Setup
+~~~~~
+
+First, ``require`` the Idiorm source file:
+
+::
+
+    require_once 'idiorm.php';
+
+Then, pass a *Data Source Name* connection string to the ``configure``
+method of the ORM class. This is used by PDO to connect to your
+database. For more information, see the `PDO documentation`_.
+
+::
+
+    ORM::configure('sqlite:./example.db');
+
+You may also need to pass a username and password to your database
+driver, using the ``username`` and ``password`` configuration options.
+For example, if you are using MySQL:
+
+::
+
+    ORM::configure('mysql:host=localhost;dbname=my_database');
+    ORM::configure('username', 'database_user');
+    ORM::configure('password', 'top_secret');
+
+Also see “Configuration” section below.
+
+Configuration
+~~~~~~~~~~~~~
+
+Other than setting the DSN string for the database connection (see
+above), the ``configure`` method can be used to set some other simple
+options on the ORM class. Modifying settings involves passing a
+key/value pair to the ``configure`` method, representing the setting you
+wish to modify and the value you wish to set it to.
+
+::
+
+    ORM::configure('setting_name', 'value_for_setting');
+
+A shortcut is provided to allow passing multiple key/value pairs at
+once.
+
+::
+
+    ORM::configure(array(
+        'setting_name_1' => 'value_for_setting_1', 
+        'setting_name_2' => 'value_for_setting_2', 
+        'etc' => 'etc'
+    ));
+
+Database authentication details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Settings: ``username`` and ``password``
+
+Some database adapters (such as MySQL) require a username and password
+to be supplied separately to the DSN string. These settings allow you to
+provide these values. A typical MySQL connection setup might look like
+this:
+
+::
+
+    ORM::configure('mysql:host=localhost;dbname=my_database');
+    ORM::configure('username', 'database_user');
+    ORM::configure('password', 'top_secret');
+
+Or you can combine the connection setup into a single line using the
+configuration array shortcut:
+
+::
+
+    ORM::configure(array(
+        'mysql:host=localhost;dbname=my_database', 
+        'username' => 'database_user', 
+        'password' => 'top_secret'
+    ));
+
+PDO Driver Options
+^^^^^^^^^^^^^^^^^^
+
+Setting: ``driver_options``
+
+Some database adapters require (or allow) an array of driver-specific
+configuration options. This setting allows you to pass these options
+through to the PDO constructor. For more information, see `the PDO
+documentation`_. For example, to force the MySQL driver to use UTF-8 for
+the connection:
+
+::
+
+    ORM::configure('driver_options', array(PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8'));
+
+PDO Error Mode
+^^^^^^^^^^^^^^
+
+Setting: ``error_mode``
+
+This can be used to set the ``PDO::ATTR_ERRMODE`` setting on the
+database connection class used by Idiorm. It should be passed one of the
+class constants defined by PDO. For example:
+
+::
+
+    ORM::configure('error_mode', PDO::ERRMODE_WARNING);
+
+The default setting is ``PDO::ERRMODE_EXCEPTION``. For full details of
+the error modes available, see `the PDO documentation`_.
+
+Identifier quote character
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Setting: ``identifier_quote_character``
+
+Set the character used to quote identifiers (eg table name, column
+name). If this is not set, it will be autodetected based on the database
+driver being used by PDO.
+
+ID Column
+^^^^^^^^^
+
+By default, the ORM assumes that all your tables have a primary key
+column called ``id``. There are two ways to override this: for all
+tables in the database, or on a per-table basis.
+
+Setting: ``id_column``
+
+This setting is used to configure the name of the primary key column for
+all tables. If your ID column is called ``primary_key``, use:
+
+::
+
+    ORM::configure('id_column', 'primary_key');
+
+Setting: ``id_column_overrides``
+
+This setting is used to specify the primary key column name for each
+table separately. It takes an associative array mapping table names to
+column names. If, for example, your ID column names include the name of
+the table, you can use the following configuration:
+
+::
+
+    ORM::configure('id_column_overrides', array(
+        'person' => 'person_id',
+        'role' => 'role_id',
+    ));
+
+Query logging
+^^^^^^^^^^^^^
+
+Setting: ``logging``
+
+Idiorm can log all queries it executes. To enable query logging, set the
+``logging`` option to ``true`` (it is ``false`` by default).
+
+When query logging is enabled, you can use two static methods to access
+the log. ``ORM::get_last_query()`` returns the most recent query
+executed. ``ORM::get_query_log()`` returns an array of all queries
+executed.
+
+Query caching
+^^^^^^^^^^^^^
+
+Setting: ``caching``
+
+Idiorm can cache the queries it executes during a request. To enable
+query caching, set the ``caching`` option to ``true`` (it is ``false``
+by default).
+
+When query caching is enabled, Idiorm will cache the results of every
+``SELECT`` query it executes. If Idiorm encounters a query that has
+already been run, it will fetch the results directly from its cache and
+not perform a database query.
+
+Warnings and gotchas
+''''''''''''''''''''
+
+-  Note that this is an in-memory cache that only persists data for the
+   duration of a single request. This is *not* a replacement for a
+   persistent cache such as `Memcached`_.
+
+-  Idiorm’s cache is very simple, and does not attempt to invalidate
+   itself when data changes. This means that if you run a query to
+   retrieve some data, modify and save it, and then run the same query
+   again, the results will be stale (ie, they will not reflect your
+   modifications). This could potentially cause subtle bugs in your
+   application. If you have caching enabled and you are experiencing odd
+   behaviour, disable it and try again. If you do need to perform such
+   operations but still wish to use the cache, you can call the
+   ``ORM::clear_cache()`` to clear all existing cached queries.
+
+-  Enabling the cache will increase the memory usage of your
+   application, as all database rows that are fetched during each
+   request are held in memory. If you are working with large quantities
+   of data, you may wish to disable the cache.
+
+.. _PDO documentation: http://php.net/manual/en/pdo.construct.php
+.. _the PDO documentation: http://www.php.net/manual/en/pdo.construct.php
+.. _the PDO documentation: http://uk2.php.net/manual/en/pdo.setattribute.php
+.. _Memcached: http://www.memcached.org/
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 87a6b27..7ab5e63 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,6 +11,10 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   philosophy
+   installation
+   configuration
+
 
 
 Indices and tables
diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 0000000..255ea62
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,19 @@
+Installation
+============
+
+Packagist
+~~~~~~~~~
+
+This library is available through Packagist with the vendor and package
+identifier of ``j4mie/idiorm``
+
+Please see the `Packagist documentation`_ for further information.
+
+Download
+~~~~~~~~
+
+You can clone the git repository, download idiorm.php or a release tag
+and then drop the idiorm.php file in the vendors/3rd party/libs
+directory of your project.
+
+.. _Packagist documentation: http://packagist.org/
\ No newline at end of file
diff --git a/docs/philosophy.rst b/docs/philosophy.rst
new file mode 100644
index 0000000..a11d421
--- /dev/null
+++ b/docs/philosophy.rst
@@ -0,0 +1,34 @@
+Philosophy
+==========
+
+The `Pareto Principle`_ states that *roughly 80% of the effects come
+from 20% of the causes.* In software development terms, this could be
+translated into something along the lines of *80% of the results come
+from 20% of the complexity*. In other words, you can get pretty far by
+being pretty stupid.
+
+**Idiorm is deliberately simple**. Where other ORMs consist of dozens of
+classes with complex inheritance hierarchies, Idiorm has only one class,
+``ORM``, which functions as both a fluent ``SELECT`` query API and a
+simple CRUD model class. If my hunch is correct, this should be quite
+enough for many real-world applications. Let’s face it: most of us
+aren’t building Facebook. We’re working on small-to-medium-sized
+projects, where the emphasis is on simplicity and rapid development
+rather than infinite flexibility and features.
+
+You might think of **Idiorm** as a *micro-ORM*. It could, perhaps, be
+“the tie to go along with `Slim`_\ ’s tux” (to borrow a turn of phrase
+from `DocumentCloud`_). Or it could be an effective bit of spring
+cleaning for one of those horrendous SQL-littered legacy PHP apps you
+have to support.
+
+**Idiorm** might also provide a good base upon which to build
+higher-level, more complex database abstractions. For example, `Paris`_
+is an implementation of the `Active Record pattern`_ built on top of
+Idiorm.
+
+.. _Pareto Principle: http://en.wikipedia.org/wiki/Pareto_principle
+.. _Slim: http://github.com/codeguy/slim/
+.. _DocumentCloud: http://github.com/documentcloud/underscore
+.. _Paris: http://github.com/j4mie/paris
+.. _Active Record pattern: http://martinfowler.com/eaaCatalog/activeRecord.html
\ No newline at end of file