Working on documentation

Author: TheCelavi

docs/source/components/index.rst

@@ -18,3 +18,4 @@ Table of Contents
    :titlesonly:
 
    metadata/index
+   query/index

docs/source/components/query/history.rst

@@ -0,0 +1,50 @@
+=======
+History
+=======
+
+.. _runopencode/query-resources-loader-bundle: https://github.com/RunOpenCode/query-resources-loader-bundle/blob/master/docs/introduction.md
+.. _Twig: https://twig.symfony.com
+
+To fully leverage raw SQL queries and statements in PHP projects, more then a 
+decade ago `runopencode/query-resources-loader-bundle`_ was created. General 
+idea was to separate PHP code from SQL code and to easily load and execute 
+queries and statements.
+
+For dynamic queries, `Twig`_ is used as a template which enables integrating 
+business logic into a final query.
+
+During years and years of improvements of the original bundle, some commonly 
+requested features were lacking. Major rewrite occurred in version 8 where 
+middleware arhitecture was introduced. However, bundle API was lacking and PHP
+improved on itself so requirement for full rewrite was more then obvious.
+
+A goals of the rewrite of the original library
+----------------------------------------------
+
+* **Removal of the vendor lock-in** by implementing framework as framework 
+  agnostic library and providing Symfony bundle separately. Since general idea
+  of the library is valid outside of Symfony's ecosystem as well, separating
+  library from Symfony would allow library to be used in other frameworks as 
+  well as in plain PHP projects.
+* **Improvement of API** by keeping public API footprint extremely small (i.e.
+  only query/statement is required argument for executor, 
+  ``$executor->query('@app/query.sql')``), while through utilization of variadic
+  arguments every aspect of execution could be configured as needed.
+* **Separation of query and statement calls** as they produce different types of
+  results.
+* **Support for common middlewares out-of-the-box**, such as:
+   * **Caching** of query results with support for static and dynamic tags.
+   * Redirecting execution to **read replica** with fallback strategy support.
+   * **Retrying** failed queries and statements due to deadlocks.
+   * **Type-casting** of records to targeted PHP types.
+   * **Logging of slow queries** based on developer defined criteria on query 
+     level.
+   * Improvement of **error handling** and exception model as well.
+   * Providing better **developer experience** by monitoring and notifying about 
+     errors in execution logic and misconfigurations.
+* Decoupling configuration of executor adapter from configuration of transaction 
+  scope.
+
+Bundle ``runopencode/query-resources-loader-bundle`` lacked support for 
+profiling, which is crucial for getting insight into execution process, 
+especially when it comes to middleware based arhitecture.

docs/source/components/query/index.rst

@@ -0,0 +1,115 @@
+===============
+Query component
+===============
+
+Mixing PHP and SQL code does not seams right. Object oriented approach of 
+building queries is appropriate for simpler queries, however, when things get
+complicated debugging and optimization makes things hard.
+
+.. _Twig: https://twig.symfony.com
+
+This library enables you to execute queries from their own separate SQL files. 
+With the help of `Twig`_ building complex query is a breeze.
+
+ORM's are not silver bullet, some use cases are better handled by executing raw
+SQL. The very purpose of this library is to make utilisation of raw SQLs within
+PHP project easy and maintainable, where applicable.
+
+Features
+--------
+
+* **Store all your queries in separate** files (``*.sql``, ``*.sql.twig``, 
+  etc.), in your project directory or any other directory or directories that 
+  you want to use.
+* **Execute queries with one line of code** simply by invoking 
+  ``$executor->query('@app/my_query.sql.twig')``.
+* **Full integration with Doctrine Dbal** out of the box, while other adapters 
+  may be added with ease too.
+* **Build complex queries using Twig** based on passed variables and parameters 
+  and control structures supported by Twig.
+* **Full support for transactions** and distributed transactions as well. 
+  Doctrine Dbal adapter supports specifying isolation level for individual 
+  transaction, query and statement.
+* **Caching** supported out of the box with possibility to tag cache items based
+  on returned resultset.
+* **Use database replica** on demand, per example, for queries which generate 
+  various reports. Disable replica in development/test environment.
+* **Middleware driven arhitecture** allows you to extend behaviour of this
+  library and control how your queries are processed and executed.
+* **Symfony ready** via dedicated bundle.
+
+Table of Contents
+-----------------
+
+.. toctree::
+   :maxdepth: 1
+
+   motivation
+   history
+
+Quick example
+-------------
+
+A simple example of using this library for executing a query is given code 
+example below.
+
+.. code-block:: php
+   :linenos:
+
+   <?php 
+
+   namespace App\User\Repository;
+   
+   use RunOpenCode\Component\Query\Cache\CacheIdentity;
+   use RunOpenCode\Component\Query\Contract\ExecutorInterface;
+   use RunOpenCode\Component\Query\Doctrine\Dbal\Options;
+   use RunOpenCode\Component\Query\Doctrine\Parameters\Named;
+   use RunOpenCode\Component\Query\Replica\FallbackStrategy;
+   use RunOpenCode\Component\Query\Replica\Replica;
+
+   final readonly class UserRepository
+   {
+       public function __construct(private ExecutorInterface $executor)
+       {
+           /* noop */
+       }
+   
+       public function getReport(Criteria $criteria): iterable
+       {
+           return $this->executor->query(
+               '@user/list_users.sql.twig',
+               Options::readCommitted(),
+               new Named()
+                   ->string('first_name', $criteria->firstName)
+                   ->string('last_name', $criteria->lastName)
+                   ->boolean('active', $criteria->active)
+                   ->integer('limit', $criteria->limit)
+                   ->integer('offset', $criteria->offset),
+               CacheIdentity::static(
+                   key: $criteria->getCacheKey(),
+                   tags: $criteria->getCacheTags(),
+                   ttl: 3600,
+               ),
+               new Replica(
+                   connection: 'reporting_database',
+                   fallback: FallbackStrategy::Primary,
+               )
+           );
+       }
+   }
+
+In example above, we are executing query defined in ``@user/list_users.sql.twig``
+file. We are setting connection isolation level to ``READ_COMMITED`` and passing
+named parameters to the query.
+
+We want to utilize cache for result set, therefore, we are providing cache 
+identity to executor with cache key and cache tags built inside criteria object.
+Query will be executed if result set is not already in cache.
+
+Instead of using primary connection, we would like to use read replica. However,
+if replica fails, we will fallback to primary connection and try again.
+
+
+
+
+