ResultIterator: Update doc

Author: homersimpsons

doc/advanced.md

@@ -59,6 +59,6 @@ there is no way to know if it more likely that he wanted users from the birth co
 
 This exception message is quite clear on the ambiguity.
 
-Solving ambiguities is always possible by [manually specifying joins](quickstart.html#joins-ans-filters) in your queries.
+Solving ambiguities is always possible by [manually specifying joins](quickstart.md#joins-ans-filters) in your queries.
 
 <div class="alert alert-warning">Note: If your data model has a lot of loops, you will likely face a lot of ambiguities. TDBM is very well suited for simple models. If your database model is complex enough to feature several of these loops, maybe TDBM is not the best tool for you. There are other great tools more suited for those use cases like <a href="http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/">Doctrine ORM</a> for instance.</div>

doc/generating_daos.md

@@ -44,13 +44,13 @@ The way you generate DAOs and beans **depends on the framework you use**.
 TDBM has a feature allowing you to access the database directly through the <code>TDBMService</code>, without generating DAOs or beans.
 This is mostly for testing purpose and is not recommended. Should you need it, you can check the <code>tests/TDBMServiceTest.php</code> file for usage samples.</div>
 
-The DAOs and beans structure
+The DAOs, beans, resultIterators structure
 ----------------------------
 
-For each table in your database, TDBM will generate a DAO and a bean. The DAO is the object you will use to
-query the database. Each row of the database will be mapped to a bean object.
+For each table in your database, TDBM will generate a DAO, a bean and a resultIterator. The DAO is the object you will use to
+query the database and will return a bean or a resultIterator. Each row of the database will be mapped to a bean object.
 
-Both DAOs and beans are divided in 2 parts. Let's assume you have a "users" table. TDBM will generate those classes for you:
+DAOs, beans and resultIterators are divided in 2 parts. Let's assume you have a "users" table. TDBM will generate those classes for you:
 
 
 - `AbstractUserDao`: the base class that contains methods to access the "users" table. It is generated by TDBM and you should
@@ -62,6 +62,10 @@ Both DAOs and beans are divided in 2 parts. Let's assume you have a "users" tabl
   never modify this class.
 - `User`: this class extends AbstractUser. If you have some custom getters and setters, you should implement them in this class. You can
   edit it as TDBM will never overwrite it.
+- `AbstractUserResultIterator`: the resultIterator representing a query on the "users" table. This class contains methods to specify you query.
+  It is generated by TDBM and you should never modify this class.
+- `UserResultIterator`: this class extends `AbstractUserResultIterator`. If you have some custom function to narrow down your queries you should implement them in this class. You can
+  edit it as TDBM will never overwrite it.
 
 Let's now have a closer look at the methods that are available in the "UserDao" class:
 

doc/graphqlite.md

@@ -186,7 +186,7 @@ class ProductController
 
     /**
      * @Query()
-     * @return Product[]
+     * @return ProductResultIterator
      */
     public function getProducts(Category $category): array
     {

doc/images/tdbm_generates_php_classes.png

@@ -89,7 +89,7 @@ class UserDao extends AbstractUserDao {
 	 * Returns the list of users starting with $firstLetter
 	 *
 	 * @param string $firstLetter
-	 * @return User[]
+	 * @return UserResultIterator
 	 */
 	public function getUsersByLetter($firstLetter) {
         $this->tdbmService->setLogLevel(LogLevel::DEBUG);

doc/miscellaneous.md

@@ -19,16 +19,28 @@ For this tutorial, let's assume a very classic database schema for handling user
 
 ![Database schema](images/schema1.png)
 
-DAOs and beans
+DAOs, Beans and ResultIterators
 --------------
 
-When you [installed TDBM](install.md), you spent some time configuring a connection to your database and then, you generated the DAOs and beans.
+When you [installed TDBM](install.md), you spent some time configuring a connection to your database and then, you generated the DAOs, beans and resultIterators.
 
-DAOs are "Data Access Objects". DAOs are classes that will help you access
-the objects in your database. There is roughly **one DAO per table in your database**. Each DAO will return "beans". Each row in your database
-will be represented by one instance of a bean.
+There will be roughly **one class (DAO, Bean, ResultIterator) per table**, in fact only ManyToMany link tables won't get their class.
 
-Each time your database model changes (if you add a new table, a new column, an index or a foreign key...), you will need to regenerate those DAOs and beans.
+Each time your database model changes (if you add a new table, a new column, an index or a foreign key...), you will need to regenerate those DAOs, beans and resultIterators.
+
+### DAOs
+
+DAOs are "Data Access Objects". DAOs are classes that will help you access the objects in your database.
+Each DAO will return a Bean or a ResultIterator (collection of Beans).
+
+### Beans
+
+Each row in your database will be represented by one instance of a bean.
+This instance will allow you to easily update your data using setters and getters strongly typed by TDBM or created by you.
+
+### ResultIterators
+
+A ResultIterator will represent the result of a query. It will allow you to specify it.
 
 Usage sample
 ------------
@@ -45,7 +57,7 @@ $user = new User("myName");
 // Fill the remaining (nullable) columns of the bean using the setters
 $user->setPassword(password_hash("myPassword", PASSWORD_DEFAULT));
 $user->setMail("[email protected]");
-// Any date should be passed as a PHP DateTime or DateTimeImmutable
+// Any date should be passed as a PHP DateTimeImmutable
 $user->setCreateDate(new DateTimeImmutable());
 
 // Finally, let's save this bean.
@@ -54,9 +66,8 @@ $user->setCreateDate(new DateTimeImmutable());
 $userDao->save($user);
 ```
 
-Since we have a "users" table, TDBM generated
-a `UserDao` class and a `User` class. `UserDao` can be used to create/update/delete/search any
-user.
+Since we have a "users" table, TDBM generated a `UserDao` class, a `User` class and a `UserResultIterator` class.
+`UserDao` can be used to create/update/delete/search any user.
 
 You can also notice that the "save()" method is called on the `UserDao`, not on the `User`.
 
@@ -73,9 +84,6 @@ echo $user->getName();
 TDBM will automatically detect the primary key of your table (of course, your table must have a primary key). There is
 no name convention to respect, your primary key column can be named anything ('id', 'userid', 'iduser', ...)
 
-To use this method, the primary key must be on a single column. If your primary key is on several columns, you can still use the
-search method (see below).
-
 ###Querying the database
 
 Now, what about getting the list of all users and displaying their name?
@@ -103,7 +111,7 @@ Bill Shakespeare
 ```
 
 
-The `findAll` method will return the list of beans.
+The `findAll` method will return the list of beans as a `UserResultIterator`.
 Of course, most of the time, you don't want all the rows in a database.
 You want to perform a query with filters.
 
@@ -177,6 +185,10 @@ generated 4 classes:
   column of the "users" table. It is generated by TDBM and you should never modify this class.
 - `User`: this class extends `AbstractUser`. If you have some custom getters and setters, you should implement them in this class. You can
   edit it as TDBM will never overwrite it.
+- `AbstractUserResultIterator`: the resultIterator representing a query on the "users" table. This class contains methods to specify you query.
+  It is generated by TDBM and you should never modify this class.
+- `UserResultIterator`: this class extends `AbstractUserResultIterator`. If you have some custom function to narrow down your queries you should implement them in this class. You can
+  edit it as TDBM will never overwrite it.
 
 
 In our example, we want to perform a query that retrieves any name starting with a "J". This is a new
@@ -191,7 +203,7 @@ class UserDao extends AbstractUserDao {
 	 * Returns the list of users starting with $firstLetter
 	 *
 	 * @param string $firstLetter
-	 * @return User[]
+	 * @return UserResultIterator
 	 */
 	public function findUsersByLetter($firstLetter) {
 		// The find can be used to retrieve a list of User
@@ -246,7 +258,7 @@ class ProductDao extends AbstractProductDao {
 	 *
 	 * @param Category $category
 	 * @param Store $store
-	 * @return Country[]
+	 * @return CountryResultIterator
 	 */
 	public function getProductsByCategoryAndStore(Category $category = null, Store $store = null) {
 		return $this->find("category = :category AND store = :store", [ 
@@ -403,7 +415,7 @@ class UserDao extends AbstractUserDao {
 	 * Returns the list of users whose country name starts by "$countryName"
 	 *
 	 * @param string $countryName
-	 * @return User[]
+	 * @return UserResultIterator
 	 */
 	public function getUsersByCountryName($countryName) {
 		// Behold the magic!
@@ -433,7 +445,7 @@ class UserDao extends AbstractUserDao {
 	 * Returns the list of users whose country is "$country"
 	 *
 	 * @param Country $country
-	 * @return User[]
+	 * @return UserResultIterator
 	 */
 	public function getUsersByCountry(Country $country) {
 		// You can pass a Country instance directly to the find method!
@@ -469,7 +481,7 @@ class CountryDao extends AbstractCountryDao {
 	 * Returns the list of countries whose country name starts by "$countryName"
 	 *
 	 * @param string $countryName
-	 * @return Country[]
+	 * @return CountryResultIterator
 	 */
 	public function findByCountryName($countryName) {
 		return $this->find("name LIKE :country", [ 'country' => $countryName.'%' ] );
@@ -492,7 +504,7 @@ class UserDao extends AbstractUserDao {
 	 * Returns the list of users whose country name starts by "$countryName"
 	 *
 	 * @param string $countryName
-	 * @return User[]
+	 * @return UserResultIterator
 	 */
 	public function getUsersByCountryName($countryName) {
 		return $this->find($this->countryDao->findByCountryName($countryName));
@@ -519,7 +531,7 @@ class RightDao extends AbstractRightDao {
 	 * Returns the list of rights for a given user
 	 *
 	 * @param User $user
-	 * @return Right[]
+	 * @return RightResultIterator
 	 */
 	public function getRightsForUser(User $user) {
 		// Behold the magic!
@@ -542,7 +554,7 @@ class RoleDao extends AbstractRoleDao {
 	/**
      * Returns the list of roles where right label = CAN_SING.
      *
-     * @return Role[]
+     * @return RoleResultIterator
      */
     public function getRolesByRightCanSing()
     {
@@ -578,7 +590,7 @@ class ProductDao extends AbstractProductDao {
 	 *
 	 * @param int $category_id
 	 * @param int $status
-	 * @return Product[]
+	 * @return ProductResultIterator
 	 */
 	public function findProductsByCategoryAndStatus(int $category_id, int $status) {
 		return $this->find([
@@ -598,7 +610,7 @@ class CountryDao extends AbstractCountryDao
 {
     /**
      * Returns the list of countries ordered by their users count (descending)
-     * @return Country[]
+     * @return CountryResultIterator
      */
     public function getCountriesByUserCount()
     {
@@ -639,7 +651,7 @@ class UserDao extends AbstractUserDao {
 	/**
 	 * Returns the list of users by alphabetical order
 	 *
-	 * @return User[]
+	 * @return UserResultIterator
 	 */
 	public function getUsersByAlphabeticalOrder() {
 		// The third parameter will be used in the "ORDER BY" clause of the SQL query.

doc/quickstart.md

@@ -38,12 +38,14 @@ TDBM is an opiniated ORM. It will not suit everybody and all needs. Here is what
 
 TDBM is a "database first" ORM. Everything starts from your database. TDBM is very good at understanding your database model and the intent behind it. It will generate PHP objects mapping your model.
 
+<!-- https://docs.google.com/drawings/d/1ZdwVgk5w1oFXnVDnDuK6d9uu_zXxNuuzYlyK409zVBE -->
 ![TDBM generates your PHP classes](doc/images/tdbm_generates_php_classes.png)
 
 TDBM **understands your database model**. From it, it will generate PHP classes that will help you access your database:
 
  - *DAOs* that are services helping you access a given table
- - and *Beans* that are classes representing a row in your database.
+ - *Beans* that are classes representing a row in your database.
+ - *ResultIterators* that are classes representing a query result.
 
 ```php
 // Daos are used to query the database
@@ -53,7 +55,7 @@ $user = $userDao->getById(42);
 $login = $user->getLogin();
 ```
 
-Because PHP objects are generated (no magic properties), you get a nice **autocompletion** in your favorite IDE (PHPStorm, Eclipse PDT, Netbeans...).
+Because PHP objects are generated (no magic properties), you get a nice **autocompletion** in your favorite IDE (PHPStorm, Eclipse PDT, NetBeans...).
 
 ## TDBM is really good at understanding your database model