README

MySQL utilities for PHP 8.4+: DSN builder, robust PDO connection builder, and a high-level admin model for managing databases, users, privileges and tables.

📚 Documentation

Full project documentation is available at:
👉 https://bcommebois.github.io/oihana-php-mysql

📦 Installation

Requires PHP 8.4+ and ext-pdo

Install via Composer:

composer require oihana/php-mysql

✨ Features

• MysqlDSN – build a MySQL DSN string from a structured configuration (host, port, dbname, charset, unix socket).
• MysqlPDOBuilder – create a configured PDO instance with sane defaults, optional validation, and easy override of options.
• MysqlModel – high-level administrative model on top of PDO to manage databases, users, privileges and tables.
• Traits – reusable building blocks (MysqlDatabaseTrait, MysqlUserTrait, MysqlPrivilegeTrait, MysqlTableTrait, MysqlAssertionsTrait, MysqlRootTrait).
• Enums – MysqlParam, MysqlPrivileges for strongly-typed configuration keys and privilege names.
• Helpers – toMysqlIdentifier() to turn any name into an identifier that needs no quoting and fits a length limit; describeDatabaseDump(), describeDatabaseDumpStream() and dumpTableNames() to read a SQL dump — its checksum, its size, its tables — line by line, whatever its size.

🚀 Quick start

require __DIR__ . '/vendor/autoload.php';

use oihana\mysql\MysqlPDOBuilder;
use oihana\mysql\MysqlModel;

// Build a PDO connection
$pdo = (new MysqlPDOBuilder([
    'host'     => '127.0.0.1',
    'dbname'   => 'demo',
    'username' => 'root',
    'password' => 'secret',
]))();

// Use the admin model
$model = new MysqlModel();
$model->setPDO( $pdo );

if ( !$model->databaseExists('my_app') )
{
    $model->createDatabase('my_app');
}

🧰 Usage

Build a DSN

use oihana\mysql\MysqlDSN;

$dsn = new MysqlDSN([
    MysqlDSN::HOST        => '127.0.0.1',
    MysqlDSN::PORT        => 3306,
    MysqlDSN::DBNAME      => 'my_database',
    MysqlDSN::CHARSET     => 'utf8mb4',
    MysqlDSN::UNIX_SOCKET => '/tmp/mysql.sock',
]);

echo (string) $dsn;
// mysql:host=127.0.0.1;port=3306;dbname=my_database;charset=utf8mb4;unix_socket=/tmp/mysql.sock

Build a PDO connection

use oihana\mysql\MysqlPDOBuilder;

$pdo = (new MysqlPDOBuilder([
    'host'     => 'localhost',
    'dbname'   => 'test_db',
    'username' => 'user',
    'password' => 'secret',
    // 'validate'   => false, // disable validation if needed
    // 'skipDbName' => true,  // build DSN without dbname
]))();

Administrative operations

use oihana\mysql\MysqlModel;

$model = new MysqlModel();
$model->setPDO( $pdoAdmin ); // connect as root/admin

$model->createDatabase('my_app');
$model->createUser('myuser', 'localhost', 'securepass');
$model->grantPrivileges('myuser', 'localhost', 'my_app');
$model->flushPrivileges();

// Rename a user
$model->renameUser('myuser', 'localhost', 'user', 'localhost');

// Revoke privileges
$model->revokePrivileges('user', 'localhost', 'my_app');

// Export information
print_r( $model->toArray() );

Name a database

use function oihana\mysql\helpers\toMysqlIdentifier;

toMysqlIdentifier( 'Example.com-WWW' ) ;              // 'example_com_www'
toMysqlIdentifier( $longName . '_user' , 32 ) ;       // cut to 32, ending in a digest of the whole name

MySQL allows 64 characters for a database name and 32 for a user name. A name too long is cut and given the first eight characters of its SHA-256, so two long names never collapse onto one identifier.

Read a SQL dump

use function oihana\mysql\helpers\describeDatabaseDump;
use function oihana\mysql\helpers\dumpTableNames;

describeDatabaseDump( '/var/backups/app/database.sql' ) ;
// [ 'sha256' => '9f86d0…' , 'bytes' => 52428800 , 'tables' => 12 ]

dumpTableNames( '/var/backups/app/database.sql' ) ;
// [ 'app_options' , 'app_posts' , 'app_users' ]

The checksum and the size tell whether the bytes are still those that were written; the count of CREATE TABLE statements tells whether the dump finished — a dump cut short hashes faithfully, and holds fewer tables. describeDatabaseDumpStream() reads the same from an open stream, such as a pipe out of tar -xO. All of them read line by line.

✅ Running Unit Tests

To run all tests:

composer run-script test

To run a specific test file:

composer run test ./tests/oihana/mysql/MysqlDSNTest.php

🤝 Contributing

Contributions are welcome! Please:

• Open an issue for discussion before large changes
• Write tests for new features and bug fixes
• Run the full test suite locally before submitting a PR

🗒️ Changelog

See CHANGELOG.md for notable changes.

🧾 License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

👤 About the author

• Author: Marc ALCARAZ (aka eKameleon)
• Mail: marc@ooop.fr
• Website: http://www.ooop.fr

🛠️ Generate the Documentation

We use phpDocumentor to generate the documentation into the ./docs folder.

composer doc

🔗 Related packages

• oihana/php-models – the PDO model this library builds on: https://github.com/BcommeBois/oihana-php-models
• oihana/php-traits – the container and string traits it uses: https://github.com/BcommeBois/oihana-php-traits
• oihana/php-core – core helpers and utilities used by this library: https://github.com/BcommeBois/oihana-php-core
• oihana/php-enums – a collection of strongly-typed constant enumerations for PHP: https://github.com/BcommeBois/oihana-php-enums
• oihana/php-reflect – reflection and hydration utilities: https://github.com/BcommeBois/oihana-php-reflect