Releasing 1.2.0

Author: technicalguru

.gitignore

@@ -5,3 +5,5 @@ composer.phar
 # You may choose to ignore a library lock file http://getcomposer.org/doc/02-libraries.md#lock-file
 # composer.lock
 /composer.lock
+/nbproject/private/
+/set-local-test-env.sh

README.md

@@ -65,8 +65,8 @@ The interface usually delivers `stdClass` objects by default. However, you can n
 your own data class so the data will be populated in such a class:
 
 ```
-$arr = $db->queryList('SELECT * FROM #__devtest', 'MyNamespace\MyDataClass');
-$obj = $db->querySingle('SELECT * FROM #__devtest WHERE uid='.$uid, 'MyNamespace\MyDataClass');
+$arr = $db->queryList('SELECT * FROM #__devtest', 'MyNamespace\\MyDataClass');
+$obj = $db->querySingle('SELECT * FROM #__devtest WHERE uid='.$uid, 'MyNamespace\\MyDataClass');
 ```
 
 ## Inserting, Updating and deleting objects
@@ -144,10 +144,10 @@ However, you can tell `DAO` your specifics:
 
 ```
 // Uses a specific class for the data
-$dao = \TgDatabase\DAO($db, '#__users', 'MyNamespace\User`);
+$dao = \TgDatabase\DAO($db, '#__users', 'MyNamespace\\User`);
 
 // Uses a specific class and another primary key attribute
-$dao = \TgDatabase\DAO($db, '#__users', 'MyNamespace\User`, 'id');
+$dao = \TgDatabase\DAO($db, '#__users', 'MyNamespace\\User`, 'id');
 ```
 
 `DAO` can actually handle non-numeric primary keys. The usage is not recommended though.
@@ -251,7 +251,7 @@ That way you can further abstract data access, e.g.
 class Users extends DAO {
 
     public function __construct($database) {
-        parent::__construct($database, '#__users', 'MyNamespace\User');
+        parent::__construct($database, '#__users', 'MyNamespace\\User');
     }
     
     public function findByEmail($email) {
@@ -344,6 +344,147 @@ $users = $myModel->get('users')->find();
 
 Imagine, how much error-proned code you would have to write yourself!
 
+# Criteria API
+Version 1.2 introduces a basic form of `Criteria` which gives you more freedom to express SQL conditions
+when searching for rows and objects. It is designed using the Hibernate ORM Criteria template. So much
+of the code may appear familiar to you.
+
+The Criteria API was created additional to the Data Model and DAO API and enhances it. So you can still use
+the v1.0 way of searching objects while already starting the Criteria API. However, it is planned to
+replace the `queryList()` and `querySingle()` methods in `Database` as well as  `count()` and 
+`find()` methods in `DAO` by the Criteria API in next major versions. At the moment both APIs exist
+independently.
+
+**Disclaimer:** The Criteria API cannot yet produce `GROUP BY` clauses as they are more complex to build.
+It will be added later.
+
+## Creating a Criteria
+Two ways exist: Creating a `Criteria` object from the `Database` object, or alternatively from the `DAO`
+object:
+
+```
+// From Database object
+$criteria = $database->createCriteria('#__users');
+ 
+// From DAO object
+$criteria = $userDAO->createCriteria();
+```
+
+You can define model classes (the objects returned from `SELECT` queries) and aliases when creating a `Criteria`:
+
+```
+// From Database object
+$criteria = $database->createCriteria('#__users', 'MyNamespace\\User', 'a');
+ 
+// From DAO object
+$criteria = $userDAO->createCriteria('a');
+```
+
+As the DAO already knows about the model class, there is no need to mention it when creating from a `DAO`.
+
+The alias is assigned to the underlying table name and will be added automatically when required in restrictions.
+
+## Using Restrictions
+Restrictions are expressions that can be used in `WHERE` clauses (and in `JOIN` - see below). The helper
+class `Restrictions` helps you to create them:
+
+```
+$expr1 = Restrictions::eq('name', 'myUsername');
+$expr2 = Restrictions::isNotNull('email');
+$criteria->add($expr1, $expr);
+```
+
+The most common restrictions are provided: eq, ne, lt, gt, ge, le, like, isNull, isNotNull, between. You can also
+use restrictions between two properties:
+
+```
+// Check for equalitity of name and email of a user.
+$expr = Restrictions::eq('name', 'email');
+```
+
+And it is possible to combine restrictions with `and()` and `or()`:
+
+```
+$expr = Restrictions::or($expr1, $expr2, $expr3);
+```
+
+## Using Projections
+Basic projections - the aggregation of columns of different rows - are available:
+
+```
+$proj = Projections::rowCount();
+$criteria->setProjection($proj);
+```
+
+You will find projections for: count, distinct, sum, avg, min, max. Please notice that
+the returned model class is always the `stdClass` when using projections.
+
+## Subcriteria and JOINs
+This is most likely the biggest advance in using the Criteria API. The traditional API methods
+were not able to use subcriteria when searching for objects depending from other tables.
+
+Let's assume you want to find all books in a database whose author name start with an A. 
+The main criteria comes from books then as it is our desired model class to be returned
+
+```
+$criteria = $bookDAO->createCriteria('a');
+```
+
+Next we join the authors table and add it to the main criteria using the respective restriction
+to join them properly:
+
+```
+$authors     = $authorDAO->createCriteria('b');
+$restriction = Restrictions::eq(array('a','author'), array('b','uid'));
+$criteria->addCriteria($authors, $restriction);
+```
+
+And finally we apply the search condition for the author:
+
+```
+$authors->add(Restrictions::like('name', 'A%'));
+```
+
+## Getting the result
+That's the most easiest part:
+
+```
+$criteria->list();
+```
+
+You can set restrictions on the result:
+
+```
+$criteria->setFirstResult(10);
+$criteria->setMaxResults(20);
+```
+
+## Advantages and Limitations
+The Criteria API will further ease in searching object in a database and return model classes, using more
+complex expressions and restrictions. You will be able to dynamically apply restrictions depending on
+the requirements of your front-end users and your application. And you won't need the DAO once you 
+created the `Criteria` object. It is self-contained.
+
+However, some limitations exist:
+
+' Criteria API supports basic use cases so far (searching objects with simple restrictions).
+* Only MySQL / MariaDB SQL dialect is produced (but can be extended to other dialects easily when you stick to the API).
+* GROUP BY clauses are not implemented
+* Multiple projections are not yet supported (such as `SELECT MAX(name), MIN(name) FROM #__users`) - will be extended.
+* Criteria API is not yet built into DAOs to make it more exchangeable. This might break the DAO API and hence will 
+  be added in one of the next major versions.
+* A few of the limitations may be ovecome by using the `SqlExpression` and `SqlProjection` classes:
+
+```
+// Use a specific restriction not supported
+$myExpr = Restrictions::sql('my-sql-fragment');
+
+// Use a specific projection not supported
+$myProj = Projections::sql('name, email');
+```
+  
+But feel free to raise an issue (see below) when you need some extension that is not yet supported.
+
 # Contribution
 Report a bug, request an enhancement or pull request at the [GitHub Issue Tracker](https://github.com/technicalguru/php-database/issues).
 

composer.json

@@ -23,6 +23,11 @@
 			"TgDatabase\\" : "src/TgDatabase/"
 		}
 	},
+	"autoload-dev" : {
+		"psr-4" : {
+			"TgDatabase\\" : "tests/TgDatabase/"
+		}
+	},
 	"extra": {
 		"branch-alias": {
 			"dev-master": "1.0-dev"

nbproject/project.properties

@@ -0,0 +1,7 @@
+include.path=${php.global.include.path}
+php.version=PHP_73
+source.encoding=UTF-8
+src.dir=.
+tags.asp=false
+tags.short=false
+web.root=.

nbproject/project.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://www.netbeans.org/ns/project/1">
+    <type>org.netbeans.modules.php.project</type>
+    <configuration>
+        <data xmlns="http://www.netbeans.org/ns/php-project/1">
+            <name>php-database</name>
+        </data>
+    </configuration>
+</project>

set-test-env.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+#######################################################
+#
+# TEST HOWTO
+#
+# Copy this file to e.g. set-local-test-env.sh and
+# set the various variables below. Then source the
+# file on you bash shell:
+#
+# ~/git/php-database$ . ./set-local-test-env.sh
+#
+# and start the PHP Unit tests:
+#
+# ~/git/php-database$ ./vendor/bin/phpunit tests
+#
+#######################################################
+
+# The Database connect information
+DB_TEST_HOST=www.example.com
+DB_TEST_PORT=3306
+DB_TEST_NAME=test
+DB_TEST_PREFIX=test
+DB_TEST_USER=username
+DB_TEST_PASS=password
+
+export DB_TEST_HOST
+export DB_TEST_PORT
+export DB_TEST_NAME
+export DB_TEST_PREFIX
+export DB_TEST_USER
+export DB_TEST_PASS
+

src/TgDatabase/Criteria.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace TgDatabase;
+
+/**
+  * Criteria is a simplified API for retrieving entities by composing Criterion objects. This is a very 
+  * convenient approach for functionality like "search" screens where there is a variable number of 
+  * conditions to be placed upon the result set.
+  */
+interface Criteria {
+
+	/**
+	  * Add a restriction to constrain the results to be retrieved.
+	  * @return Criteria - this criteria for method chaining.
+	  */
+	public function add(Criterion ...$criterion);
+
+	/**
+	  * Add an ordering to the result set.
+	  */
+	public function addOrder(Order ...$order);
+
+	/**
+	  * Set a projection for the criteria.
+	  */
+	public function setProjection(Projection $projection);
+
+	/**
+	  * Set the index of the first result to be retrieved.
+	  * @return Criteria - this criteria for method chaining.
+	  */
+	public function setFirstResult(int $firstResult);
+
+	/**
+	  * Set a limit upon the number of rows to be retrieved. 
+	  * @return Criteria - this criteria for method chaining.
+	  */
+	public function setMaxResults(int $maxResults);
+
+	/**
+	  * Create a new join criteria.
+	  */
+	public function createCriteria($tableName, $alias, $joinCriterion);
+
+	/**
+	  * Add a new join criteria.
+	  */
+	public function addCriteria(Criteria $criteria, $joinCriterion);
+
+	/**
+	  * Queries the database.
+	  */
+	public function list();
+
+	/**
+	  * Queries the database and returns all defined rows.
+	  */
+	public function first();
+}

src/TgDatabase/Criterion.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace TgDatabase;
+
+/**
+ * An object-oriented representation of a query criterion that may be used as a restriction in a Criteria query. 
+ * Built-in criterion types are provided by the Restrictions factory class. This interface might be implemented 
+ * by application classes that define custom restriction criteria. 
+ */
+interface Criterion {
+
+	/**
+	  * Render the SQL fragment.
+	  * @param Criteria $localCriteria   - local criteria object (e.g. subquery)
+	  * @param Criteria $overallCriteria - overall criteria object
+	  * @return string - the SQL fragment representing this criterion.
+	  */
+	public function toSqlString($localCritera, $overallCriteria);
+
+}

src/TgDatabase/Criterion/AggregateProjection.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace TgDatabase\Criterion;
+
+use TgDatabase\Projection;
+use TgDatabase\Criteria;
+
+class AggregateProjection implements Projection {
+
+	public function __construct($functionName, $propertyName) {
+		$this->functionName = $functionName;
+		$this->propertyName = $propertyName;
+	}
+
+	/**
+	  * Render the SQL fragment.
+	  * @param Criteria $localCriteria   - local criteria object (e.g. subquery)
+	  * @param Criteria $overallCriteria - overall criteria object
+	  * @return string - the SQL fragment representing this criterion.
+	  */
+	public function toSqlString($localCriteria, $overallCriteria) {
+		return $this->functionName.'('.$overallCriteria->quoteName($localCriteria->getAlias(), $this->propertyName).')';
+	}
+}
+

src/TgDatabase/Criterion/AliasedProjection.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace TgDatabase\Criterion;
+
+use TgDatabase\Projection;
+use TgDatabase\Criteria;
+
+class AliasedProjection implements Projection {
+
+	public function __construct($projection, $alias) {
+		$this->projection = $projection;
+		$this->alias      = $alias;
+	}
+
+	/**
+	  * Render the SQL fragment.
+	  * @param Criteria $localCriteria   - local criteria object (e.g. subquery)
+	  * @param Criteria $overallCriteria - overall criteria object
+	  * @return string - the SQL fragment representing this criterion.
+	  */
+	public function toSqlString($localCriteria, $overallCriteria) {
+		return $this->projection->toSqlString($localCriteria, $overallCriteria).' AS '.$overallCriteria->quoteName($this->alias);
+	}
+}
+