From a444f7141c2e235eb11ccf38806e8f24ef1f3051 Mon Sep 17 00:00:00 2001 From: Simon Holywell Date: Fri, 14 Dec 2012 15:15:34 +0000 Subject: Move config, installation & philosophy into Sphinx --- docs/configuration.rst | 212 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 docs/configuration.rst (limited to 'docs/configuration.rst') 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 -- cgit v1.2.3