Skip to main content

Add a New Table

After creating the project, you're ready to create your own tables.

Create the Table​

Create a new migration file in the migrations folder using the format 0000X-message.sql, where X represents a sequential number that determines execution order.

  1. Create an "up" migration file db/migrations/up/00002-create-table-example.sql:
create table example_crud
(
    id int auto_increment not null primary key,
    name varchar(50) not null,
    birthdate datetime null,
    code int null
);
  1. Create a corresponding "down" migration file db/migrations/down/00001-rollback-table-example.sql for rollbacks:
drop table example_crud;

Run the Migration​

Apply your migrations with:

APP_ENV=dev composer run migrate -- update
# OR
composer run migrate -- --env=dev update

Expected output:

> Builder\Scripts::migrate
> Command: update
Doing migrate, 2

To rollback changes:

APP_ENV=dev composer run migrate -- update --up-to=1
# OR
composer run migrate -- --env=dev update --up-to=1

The result should be:

> Builder\Scripts::migrate
> Command: update
Doing migrate, 1

Remember to run the migrating update again to apply the changes.

Generate CRUD Components with the Code Generator​

Generate all necessary files for your new table:

# Ensure DB is updated first
APP_ENV=dev composer run migrate -- update
# OR: composer run migrate -- --env=dev update

# Generate files (options: rest, model, test, repo, config, or all)
APP_ENV=dev composer run codegen -- --table example_crud --save all
# OR: composer run codegen -- --env=dev --table example_crud --save all

This creates:

  • ./src/Model/ExampleCrud.php - Model class
  • ./src/Repository/ExampleCrudRepository.php - Repository class
  • ./src/Service/ExampleCrudService.php - Service class
  • ./src/Rest/ExampleCrudRest.php - REST controller
  • ./tests/Rest/ExampleCrudTest.php - Functional tests
Automatic Configuration

The repository and service are automatically registered in:

  • config/dev/04-repositories.php
  • config/dev/05-services.php

No manual configuration needed!

ActiveRecord Pattern

To generate ActiveRecord pattern instead of Repository pattern:

APP_ENV=dev composer run codegen -- --table example_crud --save activerecord
# OR: composer run codegen -- --env=dev --table example_crud --save activerecord

This generates a simpler architecture with the model containing data access methods. See Code Generator Documentation for details.

Run the Tests​

The automatically generated test is located at tests/Rest/ExampleCrudTest.php.

Run it:

composer run test

Initial tests will fail because we need to:

  1. Generate OpenAPI documentation to create the endpoints:
composer run openapi
  1. Fix the test data by updating tests/Rest/ExampleCrudTest.php:

Locate:

    protected function getSampleData($array = false)
    {
        $sample = [

            'name' => 'name',
            'birthdate' => 'birthdate',
            'code' => 1,
        ];
...

And Change:

'birthdate' => 'birthdate',

To:

'birthdate' => '2023-01-01 00:00:00',
  1. Run the tests again:
composer run test

Your tests should now pass successfully!

Next Steps​

Continue with Adding a New Field to enhance your implementation.