Vendor lock

vendor/j4mie/paris/docs/configuration.rst

@@ -0,0 +1,123 @@
+Configuration
+=============
+
+Setup
+~~~~~
+
+Paris requires `Idiorm`_. Install Idiorm and Paris somewhere in your
+project directory, and ``require`` both.
+
+.. code-block:: php
+
+    <?php
+    require_once 'your/path/to/idiorm.php';
+    require_once 'your/path/to/paris.php';
+
+Then, you need to tell Idiorm how to connect to your database. **For
+full details of how to do this, see `Idiorm's documentation`_.**
+
+Briefly, you need to pass a *Data Source Name* connection string to the
+``configure`` method of the ORM class.
+
+.. code-block:: php
+
+    <?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:
+
+.. code-block:: php
+
+    <?php
+    ORM::configure('mysql:host=localhost;dbname=my_database');
+    ORM::configure('username', 'database_user');
+    ORM::configure('password', 'top_secret');
+
+Model prefixing
+~~~~~~~~~~~~~~~
+
+Setting: ``Model::$auto_prefix_models``
+
+To save having type out model class name prefixes whenever code utilises ``Model::for_table()``
+it is possible to specify a prefix that will be prepended onto the class name.
+
+The model prefix is treated the same way as any other class name when Paris
+attempts to convert it to a table name. This is documented in the :doc:`Models`
+section of the documentation.
+
+Here is a namespaced example to make it clearer:
+
+.. code-block:: php
+
+    <?php
+    Model::$auto_prefix_models = '\\Tests\\';
+    Model::factory('Simple')->find_many(); // SQL executed: SELECT * FROM `tests_simple`
+    Model::factory('SimpleUser')->find_many(); // SQL executed: SELECT * FROM `tests_simple_user`
+
+Model prefixes are only compatible with the ``Model::factory()`` methods described above.
+Where the shorter ``SimpleUser::find_many()`` style syntax is used, the addition of a
+Model prefix will cause ``Class not found`` errors.
+
+.. note::
+
+    Model class property ``$_table`` sets an explicit table name, ignoring the
+    ``$auto_prefix_models`` property in your individual model classes. See documentation in
+    the :doc:`Models` section of the documentation.
+
+Model prefixing
+~~~~~~~~~~~~~~~
+
+Setting: ``Model::$short_table_names``
+
+Set as ``true`` to disregard namespace information when computing table names
+from class names.
+
+By default the class ``\Models\CarTyre`` expects the table name ``models_car_tyre``.
+With ``Model::$short_table_names = true`` the class ``\Models\CarTyre`` expects the
+table name ``car_tyre``.
+
+.. code-block:: php
+
+    <?php
+
+    Model::$short_table_names = true;
+    Model::factory('CarTyre')->find_many(); // SQL executed: SELECT * FROM `car_tyre`
+
+    namespace Models {
+        class CarTyre extends Model {
+
+        }
+    }
+
+Further Configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+The only other configuration options provided by Paris itself are the
+``$_table`` and ``$_id_column`` static properties on model classes. To
+configure the database connection, you should use Idiorm’s configuration
+system via the ``ORM::configure`` method.
+
+If you are using multiple connections, the optional `$_connection_key` static property may also be used to provide a default string key indicating which database connection in `ORM` should be used.
+
+**See `Idiorm's documentation`_ for full details.**
+
+Query logging
+~~~~~~~~~~~~~
+
+Idiorm can log all queries it executes. To enable query logging, set the
+``logging`` option to ``true`` (it is ``false`` by default).
+
+.. code-block:: php
+
+    <?php
+    ORM::configure('logging', true);
+
+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.
+
+.. _Idiorm's documentation: http://github.com/j4mie/idiorm/
+.. _Idiorm: http://github.com/j4mie/idiorm/