Notions de Base de Base de Données¶

Tour Rapide¶

Les fonctions décrites dans ce chapitre illustrent les possibilités de l’API de bas niveau d’accès à la base de données. Si vous souhaitez plutôt en apprendre plus sur l’ORM complet, vous pouvez lire les sections portant sur le Query Builder et Les Objets Table.

La manière la plus simple de créer une connexion à la base de données est d’utiliser une chaine DSN:

use Cake\Datasource\ConnectionManager;

$dsn = 'mysql://root:password@localhost/my_database';
ConnectionManager::setConfig('default', ['url' => $dsn]);

Vous pouvez commencer à utiliser l’objet de connexion aussitôt après l’avoir créé:

$connection = ConnectionManager::get('default');

use Cake\Datasource\ConnectionManager;

$connection = ConnectionManager::get('default');
$results = $connection->execute('SELECT * FROM articles')->fetchAll('assoc');

$results = $connection
    ->execute('SELECT * FROM articles WHERE id = :id', ['id' => 1])
    ->fetchAll('assoc');

use Cake\Datasource\ConnectionManager;
use DateTime;

$connection = ConnectionManager::get('default');
$results = $connection
    ->execute(
        'SELECT * FROM articles WHERE created >= :created',
        ['created' => new DateTime('1 day ago')],
        ['created' => 'datetime']
    )
    ->fetchAll('assoc');

$results = $connection
    ->newQuery()
    ->select('*')
    ->from('articles')
    ->where(['created >' => new DateTime('1 day ago')], ['created' => 'datetime'])
    ->order(['title' => 'DESC'])
    ->execute()
    ->fetchAll('assoc');

use Cake\Datasource\ConnectionManager;
use DateTime;

$connection = ConnectionManager::get('default');
$connection->insert('articles', [
    'title' => 'A New Article',
    'created' => new DateTime('now')
], ['created' => 'datetime']);

use Cake\Datasource\ConnectionManager;
$connection = ConnectionManager::get('default');
$connection->update('articles', ['title' => 'New title'], ['id' => 10]);

use Cake\Datasource\ConnectionManager;
$connection = ConnectionManager::get('default');
$connection->delete('articles', ['id' => 10]);

Configuration¶

Par convention, les connexions à la base de données sont configurées dans config/app.php. L’information de connexion définie dans ce fichier est envoyée au Cake\DataSource\ConnectionManager créant la configuration de la connexion que votre application utilisera. Un exemple d’information sur la connexion se trouve dans config/app.default.php. La configuration de la connexion pourrait par exemple ressembler à ceci:

'Datasources' => [
    'default' => [
        'className' => 'Cake\Database\Connection',
        'driver' => 'Cake\Database\Driver\Mysql',
        'persistent' => false,
        'host' => 'localhost',
        'username' => 'my_app',
        'password' => 'secret',
        'database' => 'my_app',
        'encoding' => 'utf8mb4',
        'timezone' => 'UTC',
        'cacheMetadata' => true,
    ]
],

Le code ci-dessus va créer une connexion “default”, avec les paramètres fournis. Vous pouvez définir autant de connexions que vous le souhaitez dans votre fichier de configuration. Vous pouvez aussi définir des connexions supplémentaires à la volée en utilisant Cake\DataSource\ConnectionManager::setConfig(). Voici un exemple:

use Cake\Datasource\ConnectionManager;

ConnectionManager::setConfig('default', [
    'className' => 'Cake\Database\Connection',
    'driver' => 'Cake\Database\Driver\Mysql',
    'persistent' => false,
    'host' => 'localhost',
    'username' => 'my_app',
    'password' => 'secret',
    'database' => 'my_app',
    'encoding' => 'utf8mb4',
    'timezone' => 'UTC',
    'cacheMetadata' => true,
]);

Les options de configuration peuvent également être fournies en tant que chaîne DSN. C’est utile lorsque vous travaillez avec des variables d’environnement ou des fournisseurs PaaS:

ConnectionManager::setConfig('default', [
    'url' => 'mysql://my_app:secret@localhost/my_app?encoding=utf8&timezone=UTC&cacheMetadata=true',
]);

Lorsque vous utilisez une chaîne DSN, vous pouvez définir des paramètres/options supplémentaires en tant qu’arguments de query string.

Par défaut, tous les objets Table vont utiliser la connexion default. Pour utiliser une autre connexion, reportez-vous à la configuration des connexions.

La configuration de la base de données supporte de nombreuses clés. Voici la liste complète:

className

Nom de classe complet (incluant le namespace) de la classe qui représente une connexion au serveur de base de données. Cette classe a pour rôle de charger le pilote de base de données, de fournir les mécanismes de transaction et de préparer les requêtes SQL (entres autres choses).

driver

Le nom de la classe du pilote utilisé pour implémenter les spécificités d’un moteur de bases de données. Cela peut être soit un nom de classe court en utilisant la syntaxe de plugin, soit un nom complet avec namespace, soit une instance du pilote déjà construite. Les exemples de noms de classe courts sont Mysql, Sqlite, Postgres, et Sqlserver.

persistent

S’il faut utiliser ou non une connexion persistante à la base de données. Cette option n’est pas supportée par SqlServer. Une exception est lancée si vous essayez de définir persistent à true sur SqlServer.

host

Le nom d’hôte du serveur de base de données (ou une adresse IP).

username

Le nom d’utilisateur pour votre compte.

password

Le mot de passe pour le compte.

database

Le nom de la base de données à utiliser pour cette connexion. Éviter d’utiliser . dans votre nom de base de données. CakePHP ne supporte pas . dans les noms de base de données parce que cela complique l’échappement des identifiants. Les chemins vers vos bases de données SQLite doivent être absolus (par exemple ROOT . DS . 'my_app.db') pour éviter les erreurs de chemins incorrects à cause de chemins relatifs.

port (optionnel)

Le port TCP ou le socket Unix utilisé pour se connecter au serveur.

encoding

Indique le jeu de caractères à utiliser lors de l’envoi d’instructions SQL au serveur. L’encodage par défaut est celui de la base de données pour toutes les bases de données autres que DB2.

timezone

Le timezone du serveur.

schema

Utilisé pour spécifier le schema à utiliser pour les bases de données PostgreSQL.

unix_socket

Utilisé par les drivers qui le supportent pour se connecter via les fichiers socket Unix. Si vous utilisez PostgreSQL et que vous voulez utiliser les sockets Unix, laissez la clé host vide.

ssl_key

Le chemin vers le fichier de clé SSL (supporté seulement par MySQL).

ssl_cert

Le chemin vers le fichier du certificat SSL (supporté seulement par MySQL).

ssl_ca

Le chemin vers le fichier de l’autorité de certification SSL (supporté seulement par MySQL).

init

Une liste de requêtes qui doivent être envoyées au serveur de la base de données lorsque la connexion est créée.

log

Défini à true pour activer les logs des requêtes. Si activé, les requêtes seront écrites au niveau debug avec le scope queriesLog.

quoteIdentifiers

Défini à true si vous utilisez des mots réservés ou des caractères spéciaux dans les noms de tables ou de colonnes. Si cette option est activée, les identificateurs seront quotés lors de la génération du SQL dans les requêtes construites avec le Query Builder. Notez que ceci diminue la performance parce que chaque requête a besoin d’être traversée et manipulée avant d’être exécutée.

flags

Un tableau associatif de constantes PDO qui doivent être passées à l’instance PDO sous-jacente. Regardez la documentation de PDO pour les flags supportés par le pilote que vous utilisez.

cacheMetadata

Soit un booléen true, soit une chaîne contenant la configuration du cache pour stocker les métadonnées. Désactiver la mise en cache des métadonnées n’est pas conseillé et peut entraîner de faibles performances. Consultez la section sur La Mise en Cache des Métadonnées pour plus d’information.

mask

Définit les droits sur le fichier de base de données généré (seulement supporté par SQLite)

cache

Le drapeau cache à envoyer à SQLite.

mode

La valeur du drapeau mode à envoyer à SQLite.

Au point où nous en sommes, vous pouvez aller voir Conventions de CakePHP. Le nommage correct de vos tables (et de quelques colonnes) peut vous offrir des fonctionnalités utiles sans aucun effort et vous éviter d’avoir à faire de la configuration. Par exemple, si vous nommez votre table de base de données big_boxes, votre table BigBoxesTable, et votre controller BigBoxesController, tout fonctionnera ensemble automatiquement. Par convention, utilisez les underscores, les minuscules et les formes plurielles pour vos noms de table de la base de données - par exemple: bakers, pastry_stores, et savory_cakes.

'flags' => [\PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8']

Gérer les Connexions¶

class Cake\Datasource\ConnectionManager¶

La classe ConnectionManager agit comme un registre pour accéder aux connexions à la base de données que votre application. Elle fournit un endroit où les autres objets peuvent obtenir des références aux connexions existantes.

use Cake\Datasource\ConnectionManager;

$connection = ConnectionManager::get('default');

ConnectionManager::setConfig('ma_connexion', $config);
$connection = ConnectionManager::get('ma_connexion');

Types de Données¶

class Cake\Database\TypeFactory¶

Puisque tous les fournisseurs de base de données n’intègrent pas la même définition des types de données, ou pas les mêmes noms pour des types de données similaires, CakePHP fournit un ensemble de types de données abstraits à utiliser avec la couche de la base de données. Les types supportés par CakePHP sont:

string

Correspond au type VARCHAR. Avec SQL Server, c’est le type NVARCHAR qui est utilisé.

char

Correspond au type CHAR. Avec SQL Server, c’est le type NCHAR qui est utilisé.

text

Correspond aux types TEXT.

uuid

Correspond au type UUID si une base de données en fournit un, sinon cela générera un champ CHAR(36).

binaryuuid

Correspond au type UUID si la base de données en fournit un, sinon cela générera un champ BINARY(16).

integer

Correspond au type INTEGER fourni par la base de données. BIT n’est pour l’instant pas supporté.

smallinteger

Correspond au type SMALLINT fourni par la base de données.

tinyinteger

Correspond au type TINYINT ou SMALLINT fourni par la base de données. Sur MySQL TINYINT(1) sera traité comme un booléen.

biginteger

Correspond au type BIGINT fourni par la base de données.

float

Correspond soit à DOUBLE, soit à FLOAT selon la base de données. L’option precision peut être utilisée pour définir la précision utilisée.

decimal

Correspond au type DECIMAL. Supporte les options length et precision. Les valeurs du type decimal sont représentées par des chaînes de texte (et non par des float comme on pourrait s’y attendre). Cela vient du fait que les types décimaux sont utilisés pour réprésenter des valeurs numériques exactes dans les bases de données, alors que l’utilisation de type flottants en PHP peut potentiellement entraîner des pertes de précision.

Si vous voulez que les valeurs soient représentées par des float dans votre code PHP, envisagez plutôt d’utiliser des types de colonnes FLOAT ou DOUBLE dans votre base de données. Ensuite, selon l’utilisation que vous en ferez, vous pourrez faire correspondre explicitement vos colonnes décimales à un type float dans votre schéma de table.

boolean

Correspond au BOOLEAN sauf pour MySQL, où TINYINT(1) est utilisé pour représenter les booléens. BIT(1) n’est pour l’instant pas supporté.

binary

Correspond au type BLOB ou BYTEA fourni par la base de données.

date

Correspond au type de colonne natif DATE. La valeur de retour de ce type de colonne est Cake\I18n\Date qui étend la classe native DateTime.

datetime

Consultez Type DateTime.

datetimefractional

Consultez Type DateTime.

timestamp

Correspond au type TIMESTAMP.

timestampfractional

Correspond au type TIMESTAMP(N).

time

Correspond au type TIME dans toutes les bases de données.

json

Correspond au type JSON s’il est disponible, sinon il correspond à TEXT.

Ces types sont utilisés à la fois pour les fonctionnalités de reflection de schema fournies par CakePHP, et pour les fonctionnalités de génération de schema que CakePHP utilise lors des fixtures de test.

Chaque type peut aussi fournir des fonctions de traduction entre les représentations PHP et SQL. Ces méthodes sont invoquées selon les spécifications de type fournies lorsque les requêtes sont créées. Par exemple une colonne qui est marquée en “datetime” va automatiquement convertir les paramètres d’entrée d’instances DateTime en timestamp ou en chaînes de dates formatées. De même, les colonnes “binary” vont accepter des transmissions de fichiers, et générer un fichier lors de la lecture des données.

// dans config/bootstrap.php
use Cake\Database\TypeFactory;
use Cake\Database\Type\DateTimeFractionalType;

// Remplacer le type de date par défaut par un type plus précis.
TypeFactory::map('datetime', DateTimeFractionalType::class);

// dans config/bootstrap.php
use Cake\Database\TypeFactory;
use Cake\Database\Type\DateTimeTimezoneType;

// Remplacer le type de date par défaut par un type plus précis.
TypeFactory::map('datetime', DateTimeTimezoneType::class);

// Dans src/Database/Type/JsonType.php

namespace App\Database\Type;

use Cake\Database\DriverInterface;
use Cake\Database\Type\BaseType;
use PDO;

class JsonType extends BaseType
{
    public function toPHP($value, DriverInterface $driver)
    {
        if ($value === null) {
            return null;
        }
        return json_decode($value, true);
    }

    public function marshal($value)
    {
        if (is_array($value) || $value === null) {
            return $value;
        }
        return json_decode($value, true);
    }

    public function toDatabase($value, DriverInterface $driver)
    {
        return json_encode($value);
    }

    public function toStatement($value, DriverInterface $driver)
    {
        if ($value === null) {
            return PDO::PARAM_NULL;
        }
        return PDO::PARAM_STR;
    }

}

use Cake\Database\TypeFactory;

TypeFactory::map('json', 'App\Database\Type\JsonType');

use Cake\Database\Schema\TableSchemaInterface;

class WidgetsTable extends Table
{
    public function getSchema(): TableSchemaInterface
    {
        $schema = parent::getSchema();
        $schema->setColumnType('widget_prefs', 'json');

        return $schema;
    }

}

// dans src/Database/Type/JsonType.php

namespace App\Database\Type;

use Cake\Database\DriverInterface;
use Cake\Database\Type\BaseType;
use Cake\Database\Type\ColumnSchemaAwareInterface;
use Cake\Database\Schema\TableSchemaInterface;
use PDO;

class JsonType extends BaseType
    implements ColumnSchemaAwareInterface
{
    // les autres méthodes d'avant

    /**
     * Convertit la définition de schéma abstrait en un code SQL spécifique
     * au pilote pouvant être utilisé dans une instruction CREATE TABLE.
     *
     * Returner null va faire retomber vers les types intégrés à CakePHP.
     */
    public function getColumnSql(
        TableSchemaInterface $schema,
        string $column,
        DriverInterface $driver
    ): ?string {
        $data = $schema->getColumn($column);
        $sql = $driver->quoteIdentifier($column);
        $sql .= ' JSON';
        if (isset($data['null') && $data['null'] === false) {
            $sql .= ' NOT NULL';
        }
        return $sql;
    }

    /**
     * Convertit les données de la colonnes renvoyées par la reflection du
     * schéma en données abstraites de schéma.
     *
     * Returner null va faire retomber vers les types intégrés à CakePHP.
     */
    public function convertColumnDefinition(
        array $definition,
        DriverInterface $driver
    ): ?array {
        return [
            'type' => $this->_name,
            'length' => null,
        ];
    }

// dans src/Database/Point.php
namespace App\Database;

// Notre objet de valeur est immuable.
class Point
{
    protected $_lat;
    protected $_long;

    // Méthode de fabrique.
    public static function parse($value)
    {
        // Analyse les données WKB de MySQL.
        $unpacked = unpack('x4/corder/Ltype/dlat/dlong', $value);

        return new static($unpacked['lat'], $unpacked['long']);
    }

    public function __construct($lat, $long)
    {
        $this->_lat = $lat;
        $this->_long = $long;
    }

    public function lat()
    {
        return $this->_lat;
    }

    public function long()
    {
        return $this->_long;
    }
}

namespace App\Database\Type;

use App\Database\Point;
use Cake\Database\DriverInterface;
use Cake\Database\Expression\FunctionExpression;
use Cake\Database\ExpressionInterface;
use Cake\Database\Type\BaseType;
use Cake\Database\Type\ExpressionTypeInterface;

class PointType extends BaseType implements ExpressionTypeInterface
{
    public function toPHP($value, DriverInterface $d)
    {
        return Point::parse($value);
    }

    public function marshal($value)
    {
        if (is_string($value)) {
            $value = explode(',', $value);
        }
        if (is_array($value)) {
            return new Point($value[0], $value[1]);
        }
        return null;
    }

    public function toExpression($value): ExpressionInterface
    {
        if ($value instanceof Point) {
            return new FunctionExpression(
                'POINT',
                [
                    $value->lat(),
                    $value->long()
                ]
            );
        }
        if (is_array($value)) {
            return new FunctionExpression('POINT', [$value[0], $value[1]]);
        }
        // Manipulations d'autres cas.
    }

    public function toDatabase($value, DriverInterface $driver)
    {
        return $value;
    }
}

TypeFactory::build('datetime')->useImmutable();
TypeFactory::build('date')->useImmutable();
TypeFactory::build('time')->useImmutable();
TypeFactory::build('timestamp')->useImmutable();

Classes de Connexion¶

class Cake\Database\Connection¶

Les classes de connexion fournissent une interface simple pour interagir avec les connexions à la base de données de façon cohérente. Elles ont pour objectif d’être une interface plus abstraite de la couche du pilote et de fournir des fonctionnalités pour l’exécution des requêtes, le logging des requêtes, et l’utilisation de transactions.

$statement = $connection->query('UPDATE articles SET published = 1 WHERE id = 2');

$statement = $connection->execute(
    'UPDATE articles SET published = ? WHERE id = ?',
    [1, 2]
);

$statement = $connection->execute(
    'UPDATE articles SET published_date = ? WHERE id = ?',
    [new DateTime('now'), 2],
    ['date', 'integer']
);

$query = $connection->newQuery();
$query->update('articles')
    ->set(['published' => true])
    ->where(['id' => 2]);
$statement = $query->execute();

$query = $connection->newQuery();
$query->select('*')
    ->from('articles')
    ->where(['published' => true]);

foreach ($query as $row) {
    // Faire quelque chose avec la ligne.
}

$connection->begin();
$connection->execute('UPDATE articles SET published = ? WHERE id = ?', [true, 2]);
$connection->execute('UPDATE articles SET published = ? WHERE id = ?', [false, 4]);
$connection->commit();

$connection->transactional(function ($connection) {
    $connection->execute('UPDATE articles SET published = ? WHERE id = ?', [true, 2]);
    $connection->execute('UPDATE articles SET published = ? WHERE id = ?', [false, 4]);
});

Interagir avec les Requêtes¶

Lors de l’utilisation de l’API de plus bas niveau, vous rencontrerez souvent des objets statement. Ces objets vous permettent de manipuler les requêtes sous-jacentes préparées par le pilote. Après avoir créé et exécuté un objet query, ou en utilisant execute(), vous devriez avoir une instance StatementDecorator. Elle enveloppe l’objet statement basique sous-jacent et fournit quelques fonctionnalités supplémentaires.

// Les statements à partir de execute auront déjà des valeurs liées aux paramètres.
$statement = $connection->execute(
    'SELECT * FROM articles WHERE published = ?',
    [true]
);

// Les statements à partir de prepare auront des placeholders pour les paramètres.
// Vous avez besoin de lier les paramètres avant de tenter de les exécuter.
$statement = $connection->prepare('SELECT * FROM articles WHERE published = ?');

$statement = $connection->prepare(
    'SELECT * FROM articles WHERE published = ? AND created > ?'
);

// Lier plusieurs valeurs
$statement->bind(
    [true, new DateTime('2013-01-01')],
    ['boolean', 'date']
);

// Lier une valeur unique
$statement->bindValue(1, true, 'boolean');
$statement->bindValue(2, new DateTime('2013-01-01'), 'date');

$statement = $connection->prepare(
    'SELECT * FROM articles WHERE published = :published AND created > :created'
);

// Lier plusieurs valeurs
$statement->bind(
    ['published' => true, 'created' => new DateTime('2013-01-01')],
    ['published' => 'boolean', 'created' => 'date']
);

// Lier une valeur unique
$statement->bindValue('published', true, 'boolean');
$statement->bindValue('created', new DateTime('2013-01-01'), 'date');

$statement->execute();

// Lire une ligne.
$row = $statement->fetch('assoc');

// Lire toutes les lignes.
$rows = $statement->fetchAll('assoc');

// Lire les lignes en faisant une itération.
foreach ($statement as $row) {
    // Faire quelque chose
}

$rowCount = count($statement);
$rowCount = $statement->rowCount();

$code = $statement->errorCode();
$info = $statement->errorInfo();

Générer des Logs de Requêtes¶

Le logs de requêtes peuvent être activés lors de la configuration de votre connexion en définissant l’option log à true. Vous pouvez aussi changer le log de requêtes à la volée, en utilisant enableQueryLogging:

// Active les logs des requêtes.
$connection->enableQueryLogging(true);

// Stoppe les logs des requêtes
$connection->enableQueryLogging(false);

Quand les logs de requêtes sont activés, les requêtes sont loguées dans Cake\Log\Log en utilisant le niveau “debug”, et le scope “queriesLog”. Vous aurez besoin d’avoir un logger configuré pour capter ce niveau et ce scope. Faire des logs vers stderr peut être utile lorsque vous travaillez sur les tests unitaires, et les logs de fichiers/syslog peuvent être utiles lorsque vous travaillez avec des requêtes web:

use Cake\Log\Log;

// Logs vers la Console
Log::setConfig('queries', [
    'className' => 'Console',
    'stream' => 'php://stderr',
    'scopes' => ['queriesLog']
]);

// Logs vers des Fichiers
Log::setConfig('queries', [
    'className' => 'File',
    'path' => LOGS,
    'file' => 'queries.log',
    'scopes' => ['queriesLog']
]);

Échapper les Identificateurs¶

Par défaut CakePHP ne quote pas les identificateurs dans les requêtes SQL générées. La raison en est que l’ajout de quotes autour des identificateurs a quelques inconvénients:

• Par-dessus tout la performance - Ajouter des quotes est bien plus lent et complexe que de ne pas le faire.

• Pas nécessaire dans la plupart des cas - Dans des bases de données récentes qui suivent les conventions de CakePHP, il n’y a pas de raison de quoter les identificateurs.

Si vous utilisez un schema datant un peu qui nécessite de quoter les identificateurs, vous pouvez l’activer en utilisant le paramètre quoteIdentifiers dans votre Configuration. Vous pouvez aussi activer cette fonctionnalité à la volée:

$connection->getDriver()->enableAutoQuoting();

Quand elle est activée, la fonctionnalité d’échappement va entraîner des traversées supplémentaires de requêtes qui vont convertir tous les identificateurs en objets IdentifierExpression.

La Mise en Cache des Métadonnées¶

L’ORM de CakePHP utilise la réflexivité des bases de données pour déterminer le schéma, les index et les clés étrangères de votre application. Comme ces méta-données changent peu fréquemment et qu’il peut être lourd d’y accéder, elles sont habituellement mises en cache. Par défaut, les méta-données sont stockées dans la configuration de cache _cake_model_. Vous pouvez définir une configuration de cache personnalisée en utilisant l’option cacheMetatdata dans la configuration de la source de données:

'Datasources' => [
    'default' => [
        // Autres clés ici.

        // Utilise la config de cache 'orm_metadata' pour les méta-données.
        'cacheMetadata' => 'orm_metadata',
    ]
],

Vous pouvez aussi configurer le cache des méta-données à l’exécution avec la méthode cacheMetadata():

// Désactive le cache
$connection->cacheMetadata(false);

// Active le cache
$connection->cacheMetadata(true);

// Utilise une config de cache personnalisée
$connection->cacheMetadata('orm_metadata');

CakePHP intègre aussi un outil CLI pour gérer les mises en cache de méta-données. Consultez le chapitre Shell du Cache du Schéma pour plus d’information.

Créer des Bases de Données¶

Si vous voulez créer une connexion sans sélectionner de base de données, vous pouvez omettre le nom de la base de données:

$dsn = 'mysql://root:password@localhost/';

Vous pouvez maintenant utiliser votre objet de connexion pour exécuter des requêtes qui créent/modifient des bases de données. Par exemple pour créer une base de données:

$connection->query("CREATE DATABASE IF NOT EXISTS my_database");