allow to add columns to entity fetchers

Author: tflori

docs/entities.md

@@ -62,8 +62,7 @@ entities from the query.
 In fact `EntityFetcher` extends the `QueryBuilder` and for more information about building queries please have a look at
 the [QueryBuilder](querybuilder.md) documentation.
 
-Please note that the `EntityFetcher` does not allow fetching other columns than the columns from the main table of
-the class, is always distinct and restricts to change the fetch mode. Example usages:
+Example usages:
 
 ```php
 // fetch a user by $email
@@ -74,6 +73,20 @@ $articles = $entityManager->fetch(Article::class)
     ->all();
 ```
 
+Please note that it is not possible to remove the predefined modifier `DISTINCT` and the column selection `t0.*` (the
+entity table is aliased `t0`). However it is possible to add additional columns (for example aggregates from joined
+tables) but keep in mind that you then maybe also need to group by the primary key of `t0`. Also it will not be possible
+to update the entity in the DB with these extra columns.
+
+Example with aggregate column:
+```php
+$albums = $entityManager->fetch(Album::class)
+    ->joinRelated('images')
+    ->groupBy('t0.id')
+    ->column('COUNT(images.id)', [], 'imageCount')
+    ->all();
+```
+
 ### Set and get columns
 
 Every column is available by magic getter and using the column naming previously described in documentation about

src/EntityFetcher.php

@@ -214,13 +214,6 @@ public function columns(array $columns = null)
         return $this;
     }
 
-    /** @return $this
-     * @internal */
-    public function column($column, $args = [], $alias = '')
-    {
-        return $this;
-    }
-
     /** @return $this
      * @internal */
     public function setFetchMode($mode, $classNameObject = null, array $ctorargs = null)

tests/EntityFetcher/BasicTest.php

@@ -374,11 +374,20 @@ public function columnsCantBeChanged()
     {
         $fetcher = $this->em->fetch(ContactPhone::class);
         $fetcher->columns(['a', 'b']);
-        $fetcher->column('c');
 
         self::assertSame('SELECT DISTINCT t0.* FROM "contact_phone" AS t0', $fetcher->getQuery());
     }
 
+    /** @test */
+    public function columnsCanBeAdded()
+    {
+        $fetcher = $this->em->fetch(ContactPhone::class);
+        $fetcher->column('(a + b)', [], 'aPlusB');
+
+        self::assertSame('SELECT DISTINCT t0.*,("t0"."a" + "t0"."b") AS aPlusB ' .
+            'FROM "contact_phone" AS t0', $fetcher->getQuery());
+    }
+
     /** @test */
     public function fetchModeCantBeChanged()
     {