summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorSimon Holywell <[email protected]>2013-02-28 13:55:55 +0000
committerSimon Holywell <[email protected]>2013-02-28 13:55:55 +0000
commit05fb43ccadf57af00cb07192d3b2aec71ef0d952 (patch)
tree54fb114af458243fd3c38de30268ebf854310081 /docs
parentfa66a543d442893b16045fec1238fdb4745ee36a (diff)
Attempt to get syntax highlighting working
Diffstat (limited to 'docs')
-rw-r--r--docs/configuration.rst24
-rw-r--r--docs/connections.rst4
-rw-r--r--docs/models.rst18
-rw-r--r--docs/querying.rst88
-rw-r--r--docs/transactions.rst2
5 files changed, 68 insertions, 68 deletions
diff --git a/docs/configuration.rst b/docs/configuration.rst
index d464032..70f99b3 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -12,7 +12,7 @@ Setup
First, ``require`` the Idiorm source file:
-::
+.. code-block:: php
require_once 'idiorm.php';
@@ -20,7 +20,7 @@ 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`_.
-::
+.. code-block:: php
ORM::configure('sqlite:./example.db');
@@ -28,7 +28,7 @@ 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:
-::
+.. code-block:: php
ORM::configure('mysql:host=localhost;dbname=my_database');
ORM::configure('username', 'database_user');
@@ -45,14 +45,14 @@ 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.
-::
+.. code-block:: php
ORM::configure('setting_name', 'value_for_setting');
A shortcut is provided to allow passing multiple key/value pairs at
once.
-::
+.. code-block:: php
ORM::configure(array(
'setting_name_1' => 'value_for_setting_1',
@@ -70,7 +70,7 @@ 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:
-::
+.. code-block:: php
ORM::configure('mysql:host=localhost;dbname=my_database');
ORM::configure('username', 'database_user');
@@ -79,7 +79,7 @@ this:
Or you can combine the connection setup into a single line using the
configuration array shortcut:
-::
+.. code-block:: php
ORM::configure(array(
'mysql:host=localhost;dbname=my_database',
@@ -95,7 +95,7 @@ Setting: ``return_result_sets``
Collections of results can be returned as an array (default) or as a result set.
See the `find_result_set()` documentation for more information.
-::
+.. code-block:: php
ORM::configure('return_result_sets', true); // returns result sets
@@ -116,7 +116,7 @@ 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:
-::
+.. code-block:: php
ORM::configure('driver_options', array(PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8'));
@@ -129,7 +129,7 @@ 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:
-::
+.. code-block:: php
ORM::configure('error_mode', PDO::ERRMODE_WARNING);
@@ -172,7 +172,7 @@ 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:
-::
+.. code-block:: php
ORM::configure('id_column', 'primary_key');
@@ -183,7 +183,7 @@ 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:
-::
+.. code-block:: php
ORM::configure('id_column_overrides', array(
'person' => 'person_id',
diff --git a/docs/connections.rst b/docs/connections.rst
index d34d6a7..9a3a67a 100644
--- a/docs/connections.rst
+++ b/docs/connections.rst
@@ -10,7 +10,7 @@ provided, it defaults to ``ORM::DEFAULT_CONNECTION``.
When chaining, once ``for_table()`` has been used in the chain, remaining
calls in the chain use the correct connection.
-::
+.. code-block:: php
// Default connection
ORM::configure('sqlite:./example.db');
@@ -49,7 +49,7 @@ fallback to the default connection when no connection name is passed.
Instead, passing no connection name (or ``null``) returns the most recent
query on *any* connection.
-::
+.. code-block:: php
// Using default connection, explicitly
$person = ORM::for_table('person')->find_one(5);
diff --git a/docs/models.rst b/docs/models.rst
index f8246fa..dbb4695 100644
--- a/docs/models.rst
+++ b/docs/models.rst
@@ -9,7 +9,7 @@ access properties on those objects (the values stored in the columns in
its corresponding table) in two ways: by using the ``get`` method, or
simply by accessing the property on the object directly:
-::
+.. code-block:: php
$person = ORM::for_table('person')->find_one(5);
@@ -25,7 +25,7 @@ The ``as_array`` method takes column names as optional arguments. If one
or more of these arguments is supplied, only matching column names will
be returned.
-::
+.. code-block:: php
$person = ORM::for_table('person')->create();
@@ -49,7 +49,7 @@ either by using the ``set`` method or by setting the value of the
property directly. By using the ``set`` method it is also possible to
update multiple properties at once, by passing in an associative array:
-::
+.. code-block:: php
$person = ORM::for_table('person')->find_one(5);
@@ -72,7 +72,7 @@ Properties containing expressions
It is possible to set properties on the model that contain database
expressions using the ``set_expr`` method.
-::
+.. code-block:: php
$person = ORM::for_table('person')->find_one(5);
$person->set('name', 'Bob Smith');
@@ -90,7 +90,7 @@ Creating new records
To add a new record, you need to first create an "empty" object
instance. You then set values on the object as normal, and save it.
-::
+.. code-block:: php
$person = ORM::for_table('person')->create();
@@ -109,7 +109,7 @@ Properties containing expressions
It is possible to set properties on the model that contain database
expressions using the ``set_expr`` method.
-::
+.. code-block:: php
$person = ORM::for_table('person')->create();
$person->set('name', 'Bob Smith');
@@ -127,7 +127,7 @@ Checking whether a property has been modified
To check whether a property has been changed since the object was
created (or last saved), call the ``is_dirty`` method:
-::
+.. code-block:: php
$name_has_changed = $person->is_dirty('name'); // Returns true or false
@@ -137,14 +137,14 @@ Deleting records
To delete an object from the database, simply call its ``delete``
method.
-::
+.. code-block:: php
$person = ORM::for_table('person')->find_one(5);
$person->delete();
To delete more than one object from the database, build a query:
-::
+.. code-block:: php
$person = ORM::for_table('person')
->where_equal('zipcode', 55555)
diff --git a/docs/querying.rst b/docs/querying.rst
index 41b6485..41c38d6 100644
--- a/docs/querying.rst
+++ b/docs/querying.rst
@@ -37,7 +37,7 @@ requested, or ``false`` if no matching record was found.
To find a single record where the ``name`` column has the value "Fred
Bloggs":
-::
+.. code-block:: php
$person = ORM::for_table('person')->where('name', 'Fred Bloggs')->find_one();
@@ -47,7 +47,7 @@ This roughly translates into the following SQL:
To find a single record by ID, you can pass the ID directly to the
``find_one`` method:
-::
+.. code-block:: php
$person = ORM::for_table('person')->find_one(5);
@@ -65,13 +65,13 @@ were found, an empty array will be returned.
To find all records in the table:
-::
+.. code-block:: php
$people = ORM::for_table('person')->find_many();
To find all records where the ``gender`` is ``female``:
-::
+.. code-block:: php
$females = ORM::for_table('person')->where('gender', 'female')->find_many();
@@ -94,7 +94,7 @@ set of results.
So for example instead of running this:
-::
+.. code-block:: php
$people = ORM::for_table('person')->find_many();
foreach ($people as $person) {
@@ -104,7 +104,7 @@ So for example instead of running this:
You can simple do this instead:
-::
+.. code-block:: php
ORM::for_table('person')->find_result_set()
->set('age', 50)
@@ -116,13 +116,13 @@ To do this substitute any call to ``find_many()`` with
A result set will also behave like an array so you can `count()` it and `foreach`
over it just like an array.
-::
+.. code-block:: php
foreach(ORM::for_table('person')->find_result_set() as $record) {
echo $person->name;
}
-::
+.. code-block:: php
echo count(ORM::for_table('person')->find_result_set());
@@ -138,7 +138,7 @@ You can also find many records as an associative array instead of Idiorm
instances. To do this substitute any call to ``find_many()`` with
``find_array()``.
-::
+.. code-block:: php
$females = ORM::for_table('person')->where('gender', 'female')->find_array();
@@ -152,7 +152,7 @@ Counting results
To return a count of the number of rows that would be returned by a
query, call the ``count()`` method.
-::
+.. code-block:: php
$number_of_people = ORM::for_table('person')->count();
@@ -221,13 +221,13 @@ String comparision: ``where_like`` and ``where_not_like``
To add a ``WHERE ... LIKE`` clause, use:
-::
+.. code-block:: php
$people = ORM::for_table('person')->where_like('name', '%fred%')->find_many();
Similarly, to add a ``WHERE ... NOT LIKE`` clause, use:
-::
+.. code-block:: php
$people = ORM::for_table('person')->where_not_like('name', '%bob%')->find_many();
@@ -240,7 +240,7 @@ To add a ``WHERE ... IN ()`` or ``WHERE ... NOT IN ()`` clause, use the
Both methods accept two arguments. The first is the column name to
compare against. The second is an *array* of possible values.
-::
+.. code-block:: php
$people = ORM::for_table('person')->where_in('name', array('Fred', 'Joe', 'John'))->find_many();
@@ -269,7 +269,7 @@ methods as well as methods such as ``offset``, ``limit`` and
``order_by_*``. The contents of the string you supply will be connected
with preceding and following WHERE clauses with AND.
-::
+.. code-block:: php
$people = ORM::for_table('person')
->where('name', 'Fred')
@@ -298,7 +298,7 @@ these should **not** be passed directly from user input.*
The ``limit`` and ``offset`` methods map pretty closely to their SQL
equivalents.
-::
+.. code-block:: php
$people = ORM::for_table('person')->where('gender', 'female')->limit(5)->offset(10)->find_many();
@@ -312,7 +312,7 @@ Two methods are provided to add ``ORDER BY`` clauses to your query.
These are ``order_by_desc`` and ``order_by_asc``, each of which takes a
column name to sort by. The column names will be quoted.
-::
+.. code-block:: php
$people = ORM::for_table('person')->order_by_asc('gender')->order_by_desc('name')->find_many();
@@ -320,7 +320,7 @@ If you want to order by something other than a column name, then use the
``order_by_expr`` method to add an unquoted SQL expression as an
``ORDER BY`` clause.
-::
+.. code-block:: php
$people = ORM::for_table('person')->order_by_expr('SOUNDEX(`name`)')->find_many();
@@ -334,13 +334,13 @@ To add a ``GROUP BY`` clause to your query, call the ``group_by``
method, passing in the column name. You can call this method multiple
times to add further columns.
-::
+.. code-block:: php
$people = ORM::for_table('person')->where('gender', 'female')->group_by('name')->find_many();
It is also possible to ``GROUP BY`` a database expression:
-::
+.. code-block:: php
$people = ORM::for_table('person')->where('gender', 'female')->group_by_expr("FROM_UNIXTIME(`time`, '%Y-%m')")->find_many();
@@ -355,7 +355,7 @@ Substitute ``where_`` for ``having_`` to make use of these functions.
For example:
-::
+.. code-block:: php
$people = ORM::for_table('person')->group_by('name')->having_not_like('name', '%bob%')->find_many();
@@ -365,13 +365,13 @@ Result columns
By default, all columns in the ``SELECT`` statement are returned from
your query. That is, calling:
-::
+.. code-block:: php
$people = ORM::for_table('person')->find_many();
Will result in the query:
-::
+.. code-block:: php
SELECT * FROM `person`;
@@ -380,39 +380,39 @@ Call ``select`` multiple times to specify columns to return or use
```select_many`` <#shortcuts-for-specifying-many-columns>`_ to specify
many columns at once.
-::
+.. code-block:: php
$people = ORM::for_table('person')->select('name')->select('age')->find_many();
Will result in the query:
-::
+.. code-block:: php
SELECT `name`, `age` FROM `person`;
Optionally, you may also supply a second argument to ``select`` to
specify an alias for the column:
-::
+.. code-block:: php
$people = ORM::for_table('person')->select('name', 'person_name')->find_many();
Will result in the query:
-::
+.. code-block:: php
SELECT `name` AS `person_name` FROM `person`;
Column names passed to ``select`` are quoted automatically, even if they
contain ``table.column``-style identifiers:
-::
+.. code-block:: php
$people = ORM::for_table('person')->select('person.name', 'person_name')->find_many();
Will result in the query:
-::
+.. code-block:: php
SELECT `person`.`name` AS `person_name` FROM `person`;
@@ -423,14 +423,14 @@ specify multiple expressions by calling ``select_expr`` multiple times
or use ```select_many_expr`` <#shortcuts-for-specifying-many-columns>`_
to specify many expressions at once.
-::
+.. code-block:: php
// NOTE: For illustrative purposes only. To perform a count query, use the count() method.
$people_count = ORM::for_table('person')->select_expr('COUNT(*)', 'count')->find_many();
Will result in the query:
-::
+.. code-block:: php
SELECT COUNT(*) AS `count` FROM `person`;
@@ -440,33 +440,33 @@ Shortcuts for specifying many columns
``select_many`` and ``select_many_expr`` are very similar, but they
allow you to specify more than one column at once. For example:
-::
+.. code-block:: php
$people = ORM::for_table('person')->select_many('name', 'age')->find_many();
Will result in the query:
-::
+.. code-block:: php
SELECT `name`, `age` FROM `person`;
To specify aliases you need to pass in an array (aliases are set as the
key in an associative array):
-::
+.. code-block:: php
$people = ORM::for_table('person')->select_many(array('first_name' => 'name', 'age'), 'height')->find_many();
Will result in the query:
-::
+.. code-block:: php
SELECT `name` AS `first_name`, `age`, `height` FROM `person`;
You can pass the the following styles into ``select_many`` and
``select_many_expr`` by mixing and matching arrays and parameters:
-::
+.. code-block:: php
select_many(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5')
select_many('column', 'column2', 'column3')
@@ -475,13 +475,13 @@ You can pass the the following styles into ``select_many`` and
All the select methods can also be chained with each other so you could
do the following to get a neat select query including an expression:
-::
+.. code-block:: php
$people = ORM::for_table('person')->select_many('name', 'age', 'height')->select_expr('NOW()', 'timestamp')->find_many();
Will result in the query:
-::
+.. code-block:: php
SELECT `name`, `age`, `height`, NOW() AS `timestamp` FROM `person`;
@@ -491,13 +491,13 @@ DISTINCT
To add a ``DISTINCT`` keyword before the list of result columns in your
query, add a call to ``distinct()`` to your query chain.
-::
+.. code-block:: php
$distinct_names = ORM::for_table('person')->distinct()->select('name')->find_many();
This will result in the query:
-::
+.. code-block:: php
SELECT DISTINCT `name` FROM `person`;
@@ -520,7 +520,7 @@ recommended way to specify the conditions is as an *array* containing
three components: the first column, the operator, and the second column.
The table and column names will be automatically quoted. For example:
-::
+.. code-block:: php
$results = ORM::for_table('person')->join('person_profile', array('person.id', '=', 'person_profile.person_id'))->find_many();
@@ -528,7 +528,7 @@ It is also possible to specify the condition as a string, which will be
inserted as-is into the query. However, in this case the column names
will **not** be escaped, and so this method should be used with caution.
-::
+.. code-block:: php
// Not recommended because the join condition will not be escaped.
$results = ORM::for_table('person')->join('person_profile', 'person.id = person_profile.person_id')->find_many();
@@ -540,7 +540,7 @@ it is best combined with the ``table_alias`` method, which will add an
alias to the *main* table associated with the ORM, and the ``select``
method to control which columns get returned.
-::
+.. code-block:: php
$results = ORM::for_table('person')
->table_alias('p1')
@@ -557,7 +557,7 @@ to ``COUNT`` (documented earlier).
To return a minimum value of column, call the ``min()`` method.
-::
+.. code-block:: php
$min = ORM::for_table('person')->min('height');
@@ -574,7 +574,7 @@ takes a string and optionally an array of parameters. The string can
contain placeholders, either in question mark or named placeholder
syntax, which will be used to bind the parameters to the query.
-::
+.. code-block:: php
$people = ORM::for_table('person')->raw_query('SELECT p.* FROM person p JOIN role r ON p.role_id = r.id WHERE r.name = :role', array('role' => 'janitor'))->find_many();
diff --git a/docs/transactions.rst b/docs/transactions.rst
index 03a1e92..c32594d 100644
--- a/docs/transactions.rst
+++ b/docs/transactions.rst
@@ -4,7 +4,7 @@ Transactions
Idiorm doesn’t supply any extra methods to deal with transactions, but
it’s very easy to use PDO’s built-in methods:
-::
+.. code-block:: php
// Start a transaction
ORM::get_db()->beginTransaction();