Skip to content

Commit

Permalink
Move config, installation & philosophy into Sphinx
Browse files Browse the repository at this point in the history
  • Loading branch information
@treffynnon
treffynnon committed Dec 14, 2012
1 parent f3106ba commit a444f71
Show file tree
Hide file tree
Showing 5 changed files with 269 additions and 144 deletions.
144 changes: 0 additions & 144 deletions README.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,52 +72,6 @@ Changelog
* Initial release


Philosophy
----------

The [Pareto Principle](http://en.wikipedia.org/wiki/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](http://github.com/codeguy/slim/)'s tux" (to borrow a turn of phrase from [DocumentCloud](http://github.com/documentcloud/underscore)). 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](http://github.com/j4mie/paris) is an implementation of the [Active Record pattern](http://martinfowler.com/eaaCatalog/activeRecord.html) built on top of Idiorm.

Installation
------------

### Packagist ###

This library is available through Packagist with the vendor and package identifier of `j4mie/idiorm`

Please see the [Packagist documentation](http://packagist.org/) 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.

Let's See Some Code
-------------------

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](http://php.net/manual/en/pdo.construct.php).

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.

### Querying ###

Expand Down Expand Up @@ -525,102 +479,4 @@ Idiorm doesn't supply any extra methods to deal with transactions, but it's very

For more details, see [the PDO documentation on Transactions](http://www.php.net/manual/en/pdo.transactions.php).

### 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](http://www.php.net/manual/en/pdo.construct.php). 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](http://uk2.php.net/manual/en/pdo.setattribute.php).

#### 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](http://www.memcached.org/).

* 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.
212 changes: 212 additions & 0 deletions docs/configuration.rst
View file
Original file line number Diff line number Diff line change
@@ -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/
4 changes: 4 additions & 0 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ Contents:
.. toctree::
:maxdepth: 2

philosophy
installation
configuration



Indices and tables
Expand Down
Loading

0 comments on commit a444f71

Please sign in to comment.