From f38be747d132d754801c46ee3df15f8c27a03762 Mon Sep 17 00:00:00 2001
From: Andrew Dolgov <noreply@fakecake.org>
Date: Mon, 1 Mar 2021 18:36:47 +0300
Subject: initial for idiorm

---
 vendor/j4mie/idiorm/docs/configuration.rst | 378 +++++++++++++++++++++++++++++
 1 file changed, 378 insertions(+)
 create mode 100644 vendor/j4mie/idiorm/docs/configuration.rst

(limited to 'vendor/j4mie/idiorm/docs/configuration.rst')

diff --git a/vendor/j4mie/idiorm/docs/configuration.rst b/vendor/j4mie/idiorm/docs/configuration.rst
new file mode 100644
index 000000000..fb90dfa0f
--- /dev/null
+++ b/vendor/j4mie/idiorm/docs/configuration.rst
@@ -0,0 +1,378 @@
+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:
+
+.. code-block:: php
+
+    <?php
+    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`_.
+
+.. 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');
+
+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.
+
+.. code-block:: php
+
+    <?php
+    ORM::configure('setting_name', 'value_for_setting');
+
+A shortcut is provided to allow passing multiple key/value pairs at
+once.
+
+.. code-block:: php
+
+    <?php
+    ORM::configure(array(
+        'setting_name_1' => 'value_for_setting_1', 
+        'setting_name_2' => 'value_for_setting_2', 
+        'etc' => 'etc'
+    ));
+
+Use the ``get_config`` method to read current settings.
+
+.. code-block:: php
+
+    <?php
+    $isLoggingEnabled = ORM::get_config('logging');
+    ORM::configure('logging', false);
+    // some crazy loop we don't want to log
+    ORM::configure('logging', $isLoggingEnabled);
+
+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:
+
+.. code-block:: php
+
+    <?php
+    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:
+
+.. code-block:: php
+
+    <?php
+    ORM::configure(array(
+        'connection_string' => 'mysql:host=localhost;dbname=my_database', 
+        'username' => 'database_user', 
+        'password' => 'top_secret'
+    ));
+
+Result sets
+^^^^^^^^^^^
+
+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
+
+    <?php
+    ORM::configure('return_result_sets', true); // returns result sets
+
+
+.. note::
+
+   It is recommended that you setup your projects to use result sets as they
+   are more flexible.
+
+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:
+
+.. code-block:: php
+
+    <?php
+    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:
+
+.. code-block:: php
+
+    <?php
+    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 set attribute documentation`_.
+
+PDO object access
+^^^^^^^^^^^^^^^^^
+
+Should it ever be necessary, the PDO object used by Idiorm may be
+accessed directly through ``ORM::get_db()``, or set directly via
+``ORM::set_db()``. This should be an unusual occurance.
+
+After a statement has been executed by any means, such as ``::save()``
+or ``::raw_execute()``, the ``PDOStatement`` instance used may be
+accessed via ``ORM::get_last_statement()``. This may be useful in order
+to access ``PDOStatement::errorCode()``, if PDO exceptions are turned
+off, or to access the ``PDOStatement::rowCount()`` method, which returns
+differing results based on the underlying database. For more
+information, see the `PDOStatement 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:
+
+.. code-block:: php
+
+    <?php
+    ORM::configure('id_column', 'primary_key');
+
+You can specify a compound primary key using an array:
+
+.. code-block:: php
+
+    <?php
+    ORM::configure('id_column', array('pk_1', 'pk_2'));
+
+Note: If you use a auto-increment column in the compound primary key then it
+should be the first one defined into the array.
+
+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:
+
+.. code-block:: php
+
+    <?php
+    ORM::configure('id_column_overrides', array(
+        'person' => 'person_id',
+        'role' => 'role_id',
+    ));
+
+As with ``id_column`` setting, you can specify a compound primary key
+using an array.
+
+Limit clause style
+^^^^^^^^^^^^^^^^^^
+
+Setting: ``limit_clause_style``
+
+You can specify the limit clause style in the configuration. This is to facilitate
+a MS SQL style limit clause that uses the ``TOP`` syntax.
+
+Acceptable values are ``ORM::LIMIT_STYLE_TOP_N`` and ``ORM::LIMIT_STYLE_LIMIT``.
+
+.. note::
+
+    If the PDO driver you are using is one of sqlsrv, dblib or mssql then Idiorm
+    will automatically select the ``ORM::LIMIT_STYLE_TOP_N`` for you unless you
+    override the setting.
+
+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.
+
+.. note::
+
+    The code that does the query log is an approximation of that provided by PDO/the
+    database (see the Idiorm source code for detail). The actual query isn't even available
+    to idiorm to log as the database/PDO handles the binding outside of idiorm's reach and
+    doesn't pass it back.
+
+    This means that you might come across some inconsistencies between what is logged and
+    what is actually run. In these case you'll need to look at the query log provided by
+    your database vendor (eg. MySQL).
+
+Query logger
+^^^^^^^^^^^^
+
+Setting: ``logger``
+
+.. note::
+
+    You must enable ``logging`` for this setting to have any effect.
+
+It is possible to supply a ``callable`` to this configuration setting, which will
+be executed for every query that idiorm executes. In PHP a ``callable`` is anything
+that can be executed as if it were a function. Most commonly this will take the
+form of a anonymous function.
+
+This setting is useful if you wish to log queries with an external library as it
+allows you too whatever you would like from inside the callback function.
+
+.. code-block:: php
+
+    <?php
+    ORM::configure('logger', function($log_string, $query_time) {
+        echo $log_string . ' in ' . $query_time;
+    });
+
+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).
+
+.. code-block:: php
+
+    <?php
+    ORM::configure('caching', true);
+    
+    
+Setting: ``caching_auto_clear``
+
+Idiorm's cache is never cleared by default. If you wish to automatically clear it on save, set ``caching_auto_clear`` to ``true``
+
+.. code-block:: php
+
+    <?php
+    ORM::configure('caching_auto_clear', true);
+
+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.
+
+Custom caching
+''''''''''''''
+
+If you wish to use custom caching functions, you can set them from the configure options. 
+
+.. code-block:: php
+
+    <?php
+    $my_cache = array();
+    ORM::configure('cache_query_result', function ($cache_key, $value, $table_name, $connection_name) use (&$my_cache) {
+        $my_cache[$cache_key] = $value;
+    });
+    ORM::configure('check_query_cache', function ($cache_key, $table_name, $connection_name) use (&$my_cache) {
+        if(isset($my_cache[$cache_key])){
+           return $my_cache[$cache_key];
+        } else {
+        return false;
+        }
+    });
+    ORM::configure('clear_cache', function ($table_name, $connection_name) use (&$my_cache) {
+         $my_cache = array();
+    });
+
+    ORM::configure('create_cache_key', function ($query, $parameters, $table_name, $connection_name) {
+        $parameter_string = join(',', $parameters);
+        $key = $query . ':' . $parameter_string;
+        $my_key = 'my-prefix'.crc32($key);
+        return $my_key;
+    });
+
+
+.. _PDO documentation: http://php.net/manual/en/pdo.construct.php
+.. _the PDO documentation: http://php.net/manual/en/pdo.construct.php
+.. _the PDO set attribute documentation: http://php.net/manual/en/pdo.setattribute.php
+.. _PDOStatement documentation: http://php.net/manual/en/class.pdostatement.php
+.. _Memcached: http://www.memcached.org/
-- 
cgit v1.2.3