README

Datamanager is a simple persistence abstraction component in the database. Its author is not a professional in the development area, just someone from the Technology area who is improving his knowledge.

O Datamanager é um simples componente de abstração de persistência no banco de dados. Seu autor não é profissional da área de desenvolvimento, apenas alguem da área de Tecnologia que está aperfeiçoando seus conhecimentos.

Highlights

• Easy to set up (Fácil de configurar)
• Total CRUD asbtration (Asbtração total do CRUD)
• Create safe models (Crie de modelos seguros)
• Composer ready (Pronto para o composer)

Installation

Datamanager is available via Composer:

"hnrazevedo/datamanager": "^2.1"

or run

composer require hnrazevedo/Datamanager

Documentation

For details on how to use the Datamanager, see the sample folder with details in the component directory

Para mais detalhes sobre como usar o Datamanager, veja a pasta de exemplos com detalhes no diretório do componente

Errors

In case of errors, Datamanager will throw a DatamanagerException, so it is necessary to import it into your class

Em casos de erros, o Datamanager disparara uma DatamanagerException, então é necessário importar a mesma em sua classe.

use HnrAzevedo\Datamanager\DatamanagerException;

Connection

To begin using the Datamanager, you need to connect to the database (MariaDB / MySql). For more connections PDO connections manual on PHP.net

Para começar a usar o Datamanager precisamos de uma conexão com o seu banco de dados. Para ver as conexões possíveis acesse o manual de conexões do PDO em PHP.net

define("DATAMANAGER_CONFIG", [
    "driver" => "mysql",
    "host" => "localhost",
    "charset" => "utf8",
    "port" => 3306,
    "username" => "root",
    "password" => "",
    "database" => "",
    "timezone" => "America/Sao_Paulo",
    "options" => [
        PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES utf8",
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_OBJ,
        PDO::ATTR_CASE => PDO::CASE_NATURAL,
        PDO::ATTR_ORACLE_NULLS => PDO::NULL_EMPTY_STRING
    ],
    "dateformat" => "d/m/Y",
    "datetimeformat" => "d/m/Y H:i:s",
    "lang" => "pt_br"
]);

Your model

The Datamanager is based on an MVC structure. Soon to consume it is necessary to create the model of your table and inherit the Datamanager\Model.

O Datamanager é baseado em uma estrutura MVC. Logo para consumir é necessário criar o modelo de sua tabela e herdar o Datamanager\Model.

namespace Model;

use HnrAzevedo\Datamanager\Model;

class User extends Model
{
    public function __construct()
    {
        /* To return something in place in the database table field in case of errors. */
        /* NOTE: its definition is optional. */
        $this->fields = [
            'email' => 'Email',
            'username' => 'Nome de usuário'
        ];

        /**
         * @param string Table name
         * @param string Primary key column
         */
        parent::create('user', 'id');
    }
}

Methods

Find

use Model\User;
    
$entity = new User();

/* Find by primary key */
$user = $entity->find(1)->execute()->first()->toEntity();

/* Search only for columns defined in advance  */
$user = $entity->find(1)->only(['name','email'])->execute()->first();
$name = $user->name;
$email = $user->email;
/* OR */
$name = $entity->find()->only('name')->execute()->first()->name;

/* Search except for columns defined in advance  */
$user = $entity->find()->except(['name','email'])->execute()->first();
/* OR */
$user = $entity->find()->except('name')->execute()->first();

/* Limit example */
$users = $entity->find()->limit(5)->execute()->result();
/* Offset example */
$users = $entity->find()->limit(5)->offset(5)->execute()->result();

/* OrdeBy example */
$users = $entity->find()->orderBy('birth ASC')->execute()->result();
/* OR */
$users = $entity->find()->orderBy('birth','ASC')->execute()->result();

/* Between example */
$user = $entity->find()->between([
    'AND birth'=> ['01/01/1996','31/12/1996']
    ])->execute()->first();

/* Condition AND is default */
$user = $entity->find()->between([
    'birth'=> ['01/01/1996','31/12/1996']
    ])->execute()->first();

/* Clause IN */
$user = $entity->find()->where([
    'birth'=> ['01/01/1996','31/12/1996']
    ])->execute()->first();


/* Where example */
$user->find()->where([
    ['name','=','Henri Azevedo'],
    'OR' => ['email','LIKE','otheremail@gmail.com']
])->execute();

/* Searches through all records and returns a result array */
$results = $entity->find()->execute()->result();

/* Searches for all records and returns an array of Model\User objects */
$results = $entity->find()->execute()->toEntity();

Save

$entity = new User();

$user = $entity->find()->execute()->first();

/* Change info to update */
$user->name = 'Other Name';
$user->email = 'otheremail@gmail.com';

/* Upload by primary key from the uploaded entity */
/* If the changed information is a primary key or a foreign key it will be ignored in the update */
/* NOTE: Must already have the Model returned from a query */
$user->save();

If there are no state changes to be saved, a DatamanagerException will be thrown.

Caso não haja mudanças de estado para serem salvas, será lançada uma DatamanagerException.

Remove

use Model\User;

$entity = new User();

/* Remove by cause *Where* */
$entity->remove()->where([
    ['name','=','Other Name'],
    'OR' => ['email','LIKE','otheremail@gmail.com']
])->execute();

/* Remove by primary key */
/* NOTE: Required to have already returned a query */
$entity->remove()->execute();
/* OR */
$entity->remove(true);

Persist

use Model\User;

$entity = new User();

/* Set new info for insert in database */
$entity->name = 'Henri Azevedo';
$entity->email = 'hnr.azevedo@gmail.com';
$entity->password = password_hash('123456' ,PASSWORD_DEFAULT);
$entity->birth = '28/09/1996';
$entity->register = date('Y-m-d H:i:s');

/* Insert entity in database */
$entity->persist();

Count

use Model\User;

$entity = new User();
$registers = $entity->find()->only('id')->execute()->count();

debug

$entity = new User();

$user = $entity->find()->execute();

var_dump($user->debug());           // Return string replacing clause values
/*
 * Result:
 * string(110) " SELECT id,name,username,email,password,code,birth,register,lastaccess,status,type FROM user  WHERE   1 = '1' "
*/

var_dump($user->debug(true));       // Return array with executed string and field values ​​in separate index
/*
 * Result:
 * array(2) {
 * ["query"]=>
 *   string(112) " SELECT id,name,username,email,password,code,birth,register,lastaccess,status,type FROM user  WHERE   1 = :q_10 "
 * ["data"]=>
 *   array(1) {
 *     ["q_10"]=>
 *     string(1) "1"
 *   }
 * }
 * 
*/

Cache model

To avoid abstracting the greatest amount of persistence errors in the database, Datamanager describes the model as soon as the instance is created, in a static way, so that at other times of the application if the same by instance, the query will not be made again.

Para evitar abstrair a maior quantidade de erros de persistencias no banco de dados, o Datamanager faz um describe do model assim que o instânciado, de uma forma estática, para que em outros momentos da aplicação se o mesmo for instânciado, a consulta não sejá feita novamente.

To improve it even more, but the performance of your application is possible to cache this structure query, below is an example below a simple cache in SESSION.

Para melhorar ainda mas o desempenho de sua aplicação é possível cachear está consulta da estrutura, segue exemplo abaixo de um simples cache em SESSION.

namespace App\Model;

use HnrAzevedo\Datamanager\Model as Entity;

Class User extends Entity
{

    public function __construct(){
        
        $this->fields = [
            'email' => 'Email',
            'username' => 'Nome de usuário'
        ];

        if(!isset($_SESSION['cache']['datamanager'][get_class($this)])){
            parent::create('user','id');
            $_SESSION['cache']['datamanager'][get_class($this)] = serialize($this->clone());
        }
        
        $this->clone(unserialize($_SESSION['cache']['datamanager'][get_class($this)]));
        return $this;
    }

}

Support

Security: If you discover any security related issues, please email hnr.azevedo@gmail.com instead of using the issue tracker.

Se você descobrir algum problema relacionado à segurança, envie um e-mail para hnr.azevedo@gmail.com em vez de usar o rastreador de problemas.

Credits

• Henri Azevedo (Developer)

License

The MIT License (MIT). Please see License File for more information.