Fixing CS fixer

Author: TheCelavi

Pipfile

@@ -11,4 +11,4 @@ python-dotenv = "*"
 [dev-packages]
 
 [requires]
-python_version = "3.9"
+python_version = ">=3.9"

Pipfile.lock

@@ -1,30 +1,28 @@
 # DoctrineDbalExecutorResult
 
-Bundle, by default, provides you with support for executing SQL statements
-against a relational database via Doctrine Dbal.
+Bundle, by default, provides you with support for executing SQL statements against a relational database via Doctrine
+Dbal.
 
 Result set is provided as instance of
-`RunOpenCode\Bundle\QueryResourcesLoader\Executor\DoctrineDbalExecutorResult`,
-which is wrapper of Doctrine's Dbal `Doctrine\DBAL\Driver\Statement` implementation
-with additional, useful, utility methods that can improve your productivity
-when working with SQL queries 
-(see `RunOpenCode\Bundle\QueryResourcesLoader\Contract\ExecutionResultInterface`):
+`RunOpenCode\Bundle\QueryResourcesLoader\Executor\Dbal\DoctrineDbalExecutionResult`, which is wrapper of Doctrine's Dbal
+`Doctrine\DBAL\Driver\Result` implementation with additional, useful, utility methods that can improve your productivity
+when working with SQL queries.
+
+See [ExecutionResultInterface.php](../src/RunOpenCode/Bundle/QueryResourcesLoader/Contract/ExecutionResultInterface.php)
+and [DoctrineDbalExecutionResult.php](../src/RunOpenCode/Bundle/QueryResourcesLoader/Executor/Dbal/DoctrineDbalExecutionResult.php)
+for more details.
 
 - `getSingleScalarResult()` - Get single scalar result.
-- `getSingleScalarResultOrDefault()` - Get single scalar result or  default
-value if there are no results of executed SELECT statement.
-- `getSingleScalarResultOrNull()` - Get single scalar result or NULL value
-if there are no results of executed SELECT statement.
+- `getSingleScalarResultOrDefault()` - Get single scalar result or default value if there are no results of executed
+  SELECT statement.
+- `getSingleScalarResultOrNull()` - Get single scalar result or NULL value if there are no results of executed SELECT
+  statement.
 - `getScalarResult()` - Get collection of scalar values.
-- `getScalarResultOrDefault()` - Get collection of scalar vales,
-or default value if collection is empty.
-- `getScalarResultOrNull()` - Get collection of scalar vales, or NULL value
-if collection is empty.
+- `getScalarResultOrDefault()` - Get collection of scalar vales, or default value if collection is empty.
+- `getScalarResultOrNull()` - Get collection of scalar vales, or NULL value if collection is empty.
 - `getSingleResult()` - Get single (first) row result from result set.
-- `getSingleResultOrDefault()` - Get single (first) row result from result set
- or default value if result set is empty.
-- `getSingleResultOrNull()` - Get single (first) row result from result set
-or NULL value if result set is empty.
+- `getSingleResultOrDefault()` - Get single (first) row result from result set or default value if result set is empty.
+- `getSingleResultOrNull()` - Get single (first) row result from result set or NULL value if result set is empty.
 
 Note that `ExecutionResultInterface` implements `\Traversable` and `\Countable`.
 

docs/doctrine-dbal-executor-result.md

@@ -11,12 +11,12 @@ each other.
 
 ## Why `dmaicher/doctrine-test-bundle` does not work with queries having transaction statements in it?
 
-First, it is not recommended to have `BEGIN TRANSACTION`, `COMMIT` statements in your queries at all, if you need to
+First, it is not recommended to have `START TRANSACTION`, `COMMIT` statements in your queries at all, if you need to
 have them, you can use `transactional()` method of `ExecutorInterface`.
 
-That being said, `dmaicher/doctrine-test-bundle`
-tracks transactions of `Connection` object. If you use `BEGIN TRANSACTION` statement in your
-query, `dmaicher/doctrine-test-bundle` is not able to roll back them, because those are not explicitly tracked
-by `Connection` object.
+That being said, `dmaicher/doctrine-test-bundle`tracks transactions of `Connection` object. If you use
+`START TRANSACTION` statement in your query, `dmaicher/doctrine-test-bundle` is not able to roll back them, because
+those are not explicitly tracked by `Connection` object.
+
 
 [FAQ](faq.md) | [Table of contents](index.md)

docs/faq.md

@@ -1,74 +1,71 @@
 # Introduction
 
-For reporting libraries/modules within typical PHP application 
-(if stored procedures or views are not used) usual 
-practice is to hold database query within repository classes, or other class
-services.
+For, in example, reporting libraries/modules within typical PHP application (if stored procedures or views are not used)
+usual practice is to hold database query within repository classes, or other class services.
 
 Typical example would look like in pseudocode given below:
 
-    final class MyReportingRepository 
+```php
+declare(strict_types=1);
+
+use Doctrine\DBAL\Connection;
+
+final readonly class MyReportingRepository 
+{
+    public function __construct(private Connection $db) {}
+
+    public function getInvoicingReportData($year): iterable
     {
-        private $db;
-    
-        public function getInvocingReportData($year): iterable
-        {
-            $sql = 'SELECT 
-                
-                field_1.T as f1,
-                field_2.T as f2,
-                
-                ...
-                
-                field_57.X as f57,
-                
-                ...
-                
-                field_n.N as fn
-                
-                FROM 
-                
-                table_name T
-                
-                INNER JOIN table_name_2 T2 ON (T.id = T2.t1_id)
-                
-                INNER JOIN table_name_3 T3 ON (T2.id = T3.t2_id)
-                
-                ....
-                
-                [More joins]
-                
-                WHERE
-                
-                T.year = :year
-                
-                [A lot of where statements and so on...]                                           
-            ';
+        $sql = 'SELECT 
+            
+            field_1.T as f1,
+            field_2.T as f2,
+            
+            ...
+            
+            field_57.X as f57,
+            
+            ...
+            
+            field_n.N as fn
+            
+            FROM 
 
-            $this->db->execute($sql, array( 
-                'year' => $year 
-            ));            
-        }
+            table_name T
+            
+            INNER JOIN table_name_2 T2 ON (T.id = T2.t1_id)
+            
+            INNER JOIN table_name_3 T3 ON (T2.id = T3.t2_id)
+            
+            ....
+            
+            [More joins]
+            
+            WHERE
+            
+            T.year = :year
+            
+            [A lot of where statements and so on...]                                           
+        ';
+        
+        $this->db->execute($sql, array( 
+            'year' => $year 
+        ));            
     }
+}
+```
 
+Having in mind example given above, here is a short list of identified issues with this kind of approach:
 
-Having in mind example given above, here is a short list of identified 
-issues with this kind of approach:
-
-- Method size can easily go over 30 lines of code, which is against good
-coding practice.
-- Consequently, class size can easily go over few hundred lines of code, 
-also against good coding practice.
-- Using RAD tools with some kind of SQL builder which have syntax checker,
-autocomplete and testing and executing playground is impossible to use while
-building a query statement.
-- Mixing of query statements with application code seams wrong, almost like
-mixing HTML and PHP together. 
-- You cannot just send your code to DB expert to help you optimise/write
-some complex query if he is not familiar with PHP and Symfony, he will not
-be able to work on a query without your assistance. 
+- Method size can easily go over 30 lines of code, which is against good coding practice.
+- Consequently, class size can easily go over few hundred lines of code, also against good coding practice.
+- Using RAD tools with some kind of SQL builder which have syntax checker, autocomplete and testing and executing
+  playground is impossible to use while building a query statement.
+- Mixing of query statements with application code seams wrong, almost like mixing HTML and PHP together.
+- You cannot just send your code to DB expert to help you optimise/write some complex query if he is not familiar with
+  PHP and Symfony, he will not be able to work on a query without your assistance.
 
-Naturally, query code should residue in separated files and included in
-project with some kind of inclusion statement or service call.
+Naturally, query code should residue in separated files and included in project with some kind of inclusion statement or
+service call.
 
 [Table of contents](index.md) | [Proposed solution >>](proposed-solution.md)

docs/introduction.md

@@ -1,73 +1,60 @@
 # Proposed solution
 
-Solution is inspired by Symfony's way of loading templates into a controller
-and rendering response.
+Solution is inspired by Symfony's way of loading templates into a controller and rendering response.
 
-Symfony proposes convention where template code is separated (as per MVC)
-from application logic and held in `templates` (or `Resources/views`) directory.
-Required rendering logic can be coded in templates by using very powerful templating 
-language Twig. Rendering of templates is executed via dedicated service,
-while templates are identified via path or bundle resource locator syntax 
-(e.g. `@BundleName::template.html.twig`).
+Symfony proposes convention where template code is separated (as per MVC) from application logic and held in
+`templates` (or `Resources/views`) directory. Required rendering logic can be coded in templates by using very powerful
+templating language Twig. Rendering of templates is executed via dedicated service, while templates are identified via
+path or bundle resource locator syntax(e.g. `@BundleName::template.html.twig`).
 
-Inspired with that convention, this bundle proposes similar approach (if 
-not the same approach):
+Inspired with that convention, this bundle proposes similar approach:
 
-- Your queries are held in separate files in your bundles, in `query` or 
-`Resources/query` directories (or any other per your desire). 
+- Your queries are held in separate files in `query` directory of your application (or `Resources/query` directories for
+  bundles, or any other per your desire).
 - Queries are files where only query code should exist.
-- Complex queries with some kind of query building logic can use Twig as 
-pre-processing script language.
-- You can use a dedicated service `runopencode.query_loader` to load query from 
-its location by using service locator (which is bad practice) or inject the instance
-of `RunOpenCode\Bundle\QueryResourcesLoader\Contract\ManagerInterface` into your class 
-and let dependency injection do its magic (recommended).
+- Complex queries with some kind of query building logic can use Twig as pre-processing script language.
+- You can use a dedicated service `RunOpenCode\Bundle\QueryResourcesLoader\Contract\QueryResourcesLoaderInterface` to
+  load query from its location and execute it.
 
 ## Example
 
-In image below, a real-world example of directory structure of project
-reporting bundle which uses this bundle is presented:
+In image below, a real-world example of directory structure of project reporting bundle which uses this bundle is
+presented:
 
 ![Project structure with query files](img/file_structure.jpg "Real world example of this bundle usage")
 
-In that matter, in order to execute the query stored within one of those files,
-following code can be used for data source/repository class:
+**NOTE**: _This image is from project using Symfony 3, that is how old this bundle is, but it is still actively
+maintained, battle tested and used in production for latest Symfony version._
 
-    // file: ReportingBundle/Repository/ReportingDataSource.php
-    
-    namespace MyApp\ReportingBundle\Repository;
-    
-    use RunOpenCode\Bundle\QueryResourcesLoader\Contract\ManagerInterface;
-    
-    final class ReportingDataSource
+In that matter, in order to execute the query stored within one of those files, following code can be used for data
+source/repository class:
+
+```php
+declare(strict_types=1);
+
+namespace App\Reporting\Repository;
+
+use RunOpenCode\Bundle\QueryResourcesLoader\Contract\QueryResourcesLoaderInterface;
+use RunOpenCode\Bundle\QueryResourcesLoader\Executor\Dbal\DbalParameters;
+
+final readonly class ReportingDataSource
+{
+    public function __construct(private QueryResourcesLoaderInterface $loader) { }     
+
+    public function getLedgerData(Filters $filters): iterable
     {
-        private ManagerInterface $queryLoader;
-    
-        public function __construct(ManagerInterface $queryLoader)
-        {
-            $this->queryLoader = $queryLoader;
-        }
-    
-        public function getLedgerData(array $filters = []): iterable
-        {
-            return $this->queryLoader->execute('@MyAppReporting/common.ledger.sql', array(
-                'year' => !empty($filters['year']) ? $filters['year'] : date('Y')
-            ));
-        }
+        return $this->loader->execute('common.ledger.sql', DbalParameters::create()
+            ->dateTimeImmutable('from', $filters->getFrom())
+            ->dateTimeImmutable('to', $filters->getTo())
+            ->integer('account', $filters->getAccount())
+        );
     }
-    
-If you do not use autowiring, you should register your data source class within service
-container:
-
-    // file: ReportingBundle/Resources/config/services.yml
-    
-    services:
-    
-        MyApp\ReportingBundle\Repository\ReportingDataSource:
-            arguments: [ "@RunOpenCode\Bundle\QueryResourcesLoader\Contract\ManagerInterface" ]
-            
-Note how your code gets cleaner by just omitting query statements from 
-your PHP code.
-            
-            
+}
+```
+
+Note how your code gets cleaner by just omitting query statements from your PHP code.
+
+Do note that Doctrine query language for fetching entities is not powerful as raw SQL. However, with this bundle, you
+can easily leverage raw SQL queries to fetch identifiers of entities and then fetch entities with Doctrine.
+
 [<< Introduction](introduction.md) | [Table of contents](index.md) | [Twig support >>](twig-support.md)