Download the PHP package phpaml/data without Composer

phpaml/data

Couche de données typée et indépendante pour PHPAML, AML View et les projets PHP 8.2+.

État : 0.1.0-alpha.4. SQLite, MySQL, MariaDB et PostgreSQL sont validés par intégration réelle. PHPStan passe au niveau maximal.

Exemple minimal

Connexions nommées et choix du moteur

Les pilotes SQL natifs sont sqlite, mysql, mariadb et pgsql. mongodb est un point d'extension : sans adaptateur enregistré, le gestionnaire demande explicitement l'installation de phpaml/data-mongodb.

Les commandes acceptent le même nom de connexion :

L'ancienne configuration plate avec une simple clé dsn reste acceptée et devient implicitement la connexion main.

Installation et génération AML

Dans un projet moderne, l'installation prépare src/models/, src/Data/, runtime/database/migrations/, runtime/database/seeders/ et le stockage SQLite, puis écrit la configuration dans la section data de phpaml.json. Un ancien projet sans section application conserve automatiquement configs/data.php pour assurer sa compatibilité.

Les modèles générés étendent AML\Data\Entity. Les migrations utilisent Schema et Table; les seeders implémentent AML\Data\Seeding\Seeder.

Relations

with() charge chaque relation par requêtes groupées et évite le problème N+1. Une table pivot peut être maintenue explicitement :

attach() ignore les associations déjà présentes. sync() attache et détache uniquement les différences.

Migrations et schéma SQLite

Le constructeur de schéma compile désormais SQLite, MySQL/MariaDB et PostgreSQL. Les dialectes gèrent notamment les identifiants, booléens, clés auto-incrémentées et le RETURNING PostgreSQL.

Ces moteurs sont couverts par la matrice d'intégration sur serveurs réels.

Matrice d'intégration SQL

Les tests serveur sont activés uniquement lorsque leurs variables sont présentes :

La matrice crée une table temporaire dédiée, vérifie schéma, CRUD, génération de clé et rollback, puis supprime cette table. Sans DSN, le moteur est indiqué comme ignoré et la suite reste verte.

aml data:doctor --json expose désormais le pilote PDO, la connexion, la version du serveur et les capacités détectées (transactions, savepoints, returning, foreign_keys) sans afficher le mot de passe.

Les paramètres dont le nom contient password, secret, token, api_key, authorization ou cookie sont automatiquement masqués dans les diagnostics de requêtes.

Validation multi-environnement

La procédure qa/README.md démarre MySQL 8.4, MariaDB 11.4, PostgreSQL 17 et MongoDB 8.2 en replica set. Le workflow .github/workflows/ci.yml couvre PHP 8.2, 8.3 et 8.4.

Des smoke tests valident aussi l'installation dans une application PHPAML classique, une application AML View et un projet PHP autonome.

Durcissement des migrations

Les migrations utilisent un verrou concurrent : fichier verrouillé sous SQLite, GET_LOCK sous MySQL/MariaDB et verrou consultatif sous PostgreSQL. Une erreur expose la migration concernée et la phase up ou down. Le constructeur de schéma prend en charge les index simples/composés, l'ajout ou le renommage de colonnes, la suppression de colonnes, les index et le renommage de tables.

Le guide docs/MIGRATION.md explique la transition depuis l'ancienne API PHPAML\Data et le pont temporaire qui réutilise son objet PDO.

Unité de travail

Le CRUD de DbSet reste immédiat. Pour regrouper plusieurs changements atomiquement :

Les entités obtenues depuis un DbSet sont suivies automatiquement. Modifier une propriété publique puis appeler saveChanges() suffit donc sans update() explicite. Si une opération échoue, toute l'unité de travail est annulée et demeure en attente. Les transactions imbriquées utilisent des points de sauvegarde.

Les méthodes de construction de requête retournent des clones : un DbSet peut être réutilisé sans conserver les filtres d'une requête précédente. Les valeurs passent toujours par des paramètres préparés et les noms de colonnes doivent appartenir aux métadonnées de l'entité.

Transactions et diagnostic

Un objet implémentant AML\Data\Diagnostics\QueryLogger peut être fourni à Connection::sqlite(). Il reçoit le SQL, ses paramètres et la durée. Les applications doivent masquer les données sensibles dans leur implémentation du journal.

Structure d'application

Les entités applicatives restent dans src/models/, avec le namespace App\Models. Le package ne déplace pas les modèles dans son propre dossier.

Portée actuelle

Disponible dans cette version alpha : entités, attributs Table, Column et Key, DbContext, DbSet, CRUD, where, orderBy, limit, first, find, count, pagination, transactions et diagnostic des requêtes.

La validation (Required, Email, Length), les quatre relations principales, with(), le suivi automatique, saveChanges(), les migrations par lots, les rollbacks, les statuts, les seeders transactionnels et les commandes data:migrate, data:rollback, data:seed, data:status et data:doctor font également partie de l'alpha.

L'installation automatisée est disponible via aml install data, avec sélection du pilote par --driver.