Skip to content

Commit

Permalink
[skip ci] add SDAO & prepared queries doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@jcheron
jcheron committed Mar 15, 2020
1 parent a0cf855 commit e3457cf
Show file tree
Hide file tree
Showing 2 changed files with 154 additions and 34 deletions.
186 changes: 152 additions & 34 deletions docs/model/dao.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,36 +9,17 @@ The **DAO** class is responsible for loading and persistence operations on model

Connecting to the database
==========================

Check that the database connection parameters are correctly entered in the configuration file:

.. code-block:: bash
Ubiquity config -f=database
If the database is to be used in all http requests, the connection can be located in the ``app/config/services.php`` file:

.. code-block:: php
try{
\Ubiquity\orm\DAO::startDatabase($config);
}catch(Exception $e){
echo $e->getMessage();
}
Since 2.3.0 release

If the database is only used on a part of the application, it is better to create a base controller for that part, and implement the connection in its override initialize method:
Database startup with ``DAO::startDatabase($config)`` in services.php file is useless, no need to start the database, the connection is made automatically at the first request.
Use ``DAO::start()`` in **app/config/services.php** file when using several databases (with multi db feature)

.. code-block:: php
:linenos:
:caption: app/controllers/ControllerWithDb.php
namespace controllers;
class ControllerWithDb extends ControllerBase{
public function initialize(){
$config=\Ubiquity\controllers\Startup::getConfig();
\Ubiquity\orm\DAO::startDatabase($config);
}
}

Loading data
============
Expand All @@ -50,7 +31,15 @@ Loading an instance of the `models\\User` class with id `5`
use Ubiquity\orm\DAO;
$user=DAO::getOne("models\User",5);
$user=DAO::getById(models\User::class, 5);
Loading an instance using a condition:

.. code-block:: php
use Ubiquity\orm\DAO;
DAO::getOne(models\User::class, 'name= ?',false,['DOE']);
BelongsTo loading
^^^^^^^^^^^^^^^^^
Expand All @@ -60,14 +49,14 @@ Each user belongs to only one category:

.. code-block:: php
$user=DAO::getOne("models\User",5);
$user=DAO::getById(models\User::class,5);
echo $user->getCategory()->getName();
It is possible to prevent this default loading ; the third parameter allows the loading or not of belongsTo members:

.. code-block:: php
$user=DAO::getOne("models\User",5, false);
$user=DAO::getOne(models\User::class,5, false);
echo $user->getCategory();// NULL
HasMany loading
Expand All @@ -78,9 +67,9 @@ Each user has many groups:

.. code-block:: php
$user=DAO::getOne("models\User",5,["groupes"]);
$user=DAO::getOne(models\User::class,5,['groupes']);
foreach($user->getGroupes() as $groupe){
echo $groupe->getName()."<br>";
echo $groupe->getName().'<br>';
}
Composite primary key
Expand All @@ -89,7 +78,7 @@ Either the `ProductDetail` model corresponding to a product ordered on a command

.. code-block:: php
:linenos:
:caption: app/models/Products.php
:caption: app/models/ProductDetail.php
namespace models;
class ProductDetail{
Expand All @@ -110,7 +99,7 @@ The second parameter `$keyValues` can be an array if the primary key is composit

.. code-block:: php
$productDetail=DAO::getOne("models\ProductDetail",[18,'BF327']);
$productDetail=DAO::getOne(models\ProductDetail::class,[18,'BF327']);
echo 'Command:'.$productDetail->getCommande().'<br>';
echo 'Product:'.$productDetail->getProduct().'<br>';
Expand All @@ -120,7 +109,7 @@ Loading instances of the `User` class:

.. code-block:: php
$users=DAO::getAll("models\User");
$users=DAO::getAll(models\User::class);
foreach($users as $user){
echo $user->getName()."<br>";
}
Expand All @@ -132,7 +121,7 @@ Loading instances of the `User` class with its category and its groups :

.. code-block:: php
$users=DAO::getAll("models\User",["groupes","category"]);
$users=DAO::getAll(models\User::class,['groupes','category']);
foreach($users as $user){
echo "<h2>".$user->getName()."</h2>";
echo $user->getCategory()."<br>";
Expand All @@ -149,7 +138,7 @@ Loading instances of the `User` class with its category, its groups and the orga

.. code-block:: php
$users=DAO::getAll("models\User",["groupes.organization","category"]);
$users=DAO::getAll(models\User::class,['groupes.organization','category']);
foreach($users as $user){
echo "<h2>".$user->getName()."</h2>";
echo $user->getCategory()."<br>";
Expand All @@ -168,7 +157,7 @@ Loading instances of the `User` class with its category, its groups and all rela

.. code-block:: php
$users=DAO::getAll("models\User",["groupes.*","category"]);
$users=DAO::getAll(models\User::class,['groupes.*','category']);
Querying using conditions
-------------------------
Expand Down Expand Up @@ -236,7 +225,7 @@ Adding an instance of User, in an organization:

.. code-block:: php
$orga=DAO::getOne(Organization::class, 1);
$orga=DAO::getById(Organization::class, 1);
$user=new User();
$user->setFirstname('DOE');
$user->setLastname('John');
Expand Down Expand Up @@ -278,3 +267,132 @@ If the instance is not loaded, it is more appropriate to use the `delete` method
if(DAO::delete(Organization::class,5)){
echo 'Organization deleted from database';
}
Deleting multiple instances
===========================
Deletion of multiple instances without prior loading:

.. code-block:: php
if($res=DAO::deleteAll(models\User::class, 'id in (?,?,?)',[1,2,3])){
echo "$res elements deleted";
}
Bulk queries
============
Bulk queries allow several operations (insertion, modification or deletion) to be performed in a single query, which contributes to improved performance.

Bulk inserts
------------

Insertions example:

.. code-block:: php
$u = new User();
$u->setName('Martin1');
DAO::toInsert($u);
$u = new User();
$u->setName('Martin2');
DAO::toInsert($u);
//Perform inserts
DAO::flushInserts();
Bulk updates
------------

Updates example:

.. code-block:: php
$users = DAO::getAll(User::class, 'name like ?', false, [
'Martin%'
]);
foreach ($users as $user) {
$user->setName(\strtoupper($user->getName()));
DAO::toUpdate($user);
}
DAO::flushUpdates();
Bulk deletes
------------

Deletions example

.. code-block:: php
$users = DAO::getAll(User::class, 'name like ?', false, [
'BULK%'
]);
DAO::toDeletes($users);
DAO::flushDeletes();
The `DAO::flush()` method can be called if insertions, updates or deletions are pending.

SDAO class
==========
The **SDAO** class accelerates CRUD operations for the business classes without relationships.

Models must in this case declare public members only, and not respect the usual encapsulation.

.. code-block:: php
:linenos:
:caption: app/models/Product.php
namespace models;
class Product{
/**
* @id
*/
public $id;
public $name;
...
}
The **SDAO** class inherits from **DAO** and has the same methods for performing CRUD operations.

.. code-block:: php
use Ubiquity\orm\DAO;
$product=DAO::getById(models\Product::class, 5);
Prepared DAO queries
====================
Preparing certain requests can improve performance with Swoole, Workerman or Roadrunner servers. |br|
This preparation initializes the objects that will then be used to execute the query. |br|
This initialization is done at server startup, or at the startup of each worker, if such an event exists.

Swoole sample
-------------

Preparation
^^^^^^^^^^^

.. code-block:: php
:caption: app/config/swooleServices.php
$swooleServer->on('workerStart', function ($srv) use (&$config) {
\Ubiquity\orm\DAO::startDatabase($config);
\Ubiquity\orm\DAO::prepareGetById('user', models\User::class);
\Ubiquity\orm\DAO::prepareGetAll('productsByName', models\Product::class,'name like ?');
});
Usage
^^^^^

.. code-block:: php
:caption: app/controllers/UsersController.php
public function displayUser($idUser){
$user=DAO::executePrepared('user',[1]);
echo $user->getName();
}
public function displayProducts($name){
$products=DAO::executePrepared('productsByName',[$name]);
...
}
2 changes: 2 additions & 0 deletions src/Ubiquity/orm/SDAO.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@
use Ubiquity\orm\parser\Reflexion;

/**
* DAO class for models without relationships
* Model classes must declare public members only
* Ubiquity\orm$SDAO
* This class is part of Ubiquity
*
Expand Down

0 comments on commit e3457cf

Please sign in to comment.