Table of Contents

Doctrine ORM

Summary

This page connects Dotkernel Frontend to a MariaDB or MySQL database, creates the tables by running the migrations, and seeds the default user roles with the fixtures.

Details

This step saves the database connection credentials in a Frontend configuration file. We do not cover the creation steps of the database itself.

Setup database

Create a new MySQL database and set its collation to utf8mb4_general_ci.

Fill out the database credentials in config/autoload/local.php under $databases['default']. Below is the item you need to focus on.

my_database, my_user, my_password are provided only as an example.

$databases = [
    'default' => [
        'host'     => 'localhost',
        'dbname'   => 'my_database',
        'user'     => 'my_user',
        'password' => 'my_password',
        'port'     => 3306,
        'driver'   => 'pdo_mysql',
        'charset'  => 'utf8mb4',
        'collate'  => 'utf8mb4_general_ci',
    ],
    // you can add more database connections into this array
];

Migrations

Running the migrations is done with this command

php vendor/bin/doctrine-migrations migrate

Note: If you have already run the migrations, you may get this message. You should double-check to make sure the new migrations are ok to run.

WARNING! You have x previously executed migrations in the database that are not registered migrations.
  {migration list}
Are you sure you wish to continue? (y/n)

When using an empty database, you will get this confirmation message instead.

WARNING! You are about to execute a database migration that could result in schema changes and data loss. Are you sure you wish to continue? (y/n)

Again, submit y to run all the migrations in chronological order. Each migration will be logged in the migrations table to prevent running the same migration more than once, which is often not desirable.

If everything ran correctly, you will get this confirmation.

[OK] Successfully migrated to version: Frontend\Migrations\Version20241120160406

The migration name Version20241120160406 may differ in future Frontend updates.

Fixtures

Run this command to populate the user_role table with the default roles (admin, user and guest):

php bin/doctrine fixtures:execute

You should see our galloping horse in the command line.

Executing Frontend\Fixtures\RoleLoader
Fixtures have been loaded.
                .''
      ._.-.___.' (`\
     //(        ( `'
    '/ )\ ).__. )
    ' <' `\ ._/'\
       `   \     \

FAQ

Q: Which character set and collation should the database use?

A: utf8mb4 with utf8mb4_general_ci, the values set in config/autoload/local.php.dist.

Q: Where is the list of executed migrations kept?

A: In the migrations table, as configured in config/migrations.php. Doctrine Migrations uses it to skip migrations that have already run.

Q: Which roles do the fixtures create?

A: admin, user and guest, in the user_role table.

Q: Can I run the fixtures again?

A: Not on the same database. The command appends data instead of purging it, and user_role.name is unique, so a second run fails on the duplicate role names.

On this page