All jobs

Add Database Migrations to a Slim 4 App

Yes. An agent adds Phinx migrations and a seed to a Slim 4 app, swaps the in-memory user repository for a PDO one behind the same interface, tests it and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the app wires its container before touching persistence, because the whole point is to keep the domain interface and swap what stands behind it. In an app laid out like slimphp/Slim-Skeleton, composer.json requires slim/slim ^4.12, slim/psr7 ^1.6, php-di/php-di ^6.4 and monolog/monolog ^2.9 on php ^7.4 || ^8.0, with phpunit/phpunit ^9.6.17, phpstan/phpstan ^1.10 and squizlabs/php_codesniffer ^3.9 in require-dev, and scripts start (php -S localhost:8080 -t public) and test (phpunit). public/index.php builds a PHP-DI container from app/settings.php, app/dependencies.php and app/repositories.php, and app/repositories.php is one line of substance: it autowires App\Domain\User\UserRepository to InMemoryUserRepository. That class in src/Infrastructure/Persistence/User/ holds five hard-coded User objects keyed by id and implements the two methods the interface in src/Domain/User/UserRepository.php declares, findAll() and findUserOfId(int $id), throwing UserNotFoundException for a missing id. User itself has a nullable id, username, firstName and lastName, lowercases the username and capitalises the names in its constructor, and serialises to JSON. app/routes.php exposes GET /users and GET /users/{id} through ListUsersAction and ViewUserAction. There is no database, no PDO service and no db setting anywhere.

Phinx is the migration tool the agent adds, and its current release requires PHP 8.1 or later, cakephp/database and symfony/console. That collides with the ^7.4 || ^8.0 floor and with the tests.yml matrix, which runs PHP 7.4, 8.0, 8.1 and 8.2 and runs phpcs and phpstan on 8.1. The agent raises php to ^8.1 in composer.json, drops 7.4 and 8.0 from the matrix, and says in the pull request that both are past their end of life and that a team that must keep them can pin an older Phinx instead. It then adds robmorgan/phinx to require, a phinx.php at the root with development, testing and production environments read from DB_ADAPTER, DB_NAME, DB_HOST, DB_USER and DB_PASS, SQLite under var/ as the default so composer start works with nothing installed, and db/migrations and db/seeds as the paths.

The first migration, db/migrations/<timestamp>_create_users_table.php, creates users with an auto-increment id, username as a unique string, first_name and last_name, and timestamps, matching the four fields User carries. db/seeds/UserSeeder.php inserts the same five people InMemoryUserRepository hard-codes, so GET /users returns what it returned before. src/Infrastructure/Persistence/User/PdoUserRepository.php implements UserRepository over a PDO instance with prepared statements, maps rows to User and throws UserNotFoundException the way the in-memory class does. app/settings.php gains a db block, app/dependencies.php a PDO::class definition built from it with ERRMODE_EXCEPTION, and app/repositories.php points the interface at the new class; the in-memory class stays in the tree for tests that want it. composer.json gets migrate and seed scripts that call vendor/bin/phinx, and .gitignore gets the SQLite file under var/.

The existing action tests under tests/Application/Actions/User replace the repository through the container with a Prophecy double, so they keep passing untouched. The agent adds tests/Infrastructure/Persistence/User/PdoUserRepositoryTest.php, which opens an in-memory SQLite PDO, runs the migration through Phinx's TextWrapper against the testing environment, inserts two rows and asserts findAll() and findUserOfId() return User objects with the capitalised names and that a missing id throws. It runs vendor/bin/phpunit, vendor/bin/phpstan at the level phpstan.neon.dist sets and vendor/bin/phpcs in its sandbox, then composer migrate, composer seed, composer start and curl localhost:8080/users to show the seeded list, with phinx status printed once before and once after the migration.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add database migrations to this Slim 4 app with Phinx and move users out of memory. Read composer.json, public/index.php, app/settings.php, app/dependencies.php, app/repositories.php, app/routes.php, src/Domain/User and src/Infrastructure/Persistence/User, tests/TestCase.php, the action tests, phpunit.xml, phpstan.neon.dist, phpcs.xml, .gitignore, docker-compose.yml and .github/workflows/tests.yml first. Phinx needs PHP 8.1, so raise the composer php floor, trim the CI matrix and explain why. Add phinx.php with development, testing and production environments from environment variables and SQLite under var as the default, a users migration matching the User entity, a seeder with the five existing users, a PdoUserRepository behind the existing interface, a PDO definition in dependencies, a db block in settings, migrate and seed composer scripts, and the SQLite file in .gitignore. Keep the in-memory repository in the tree. Add a repository test that migrates an in-memory SQLite database through Phinx's TextWrapper. Run phpunit, phpstan, phpcs, the migration, the seed and a curl of /users, and open a pull request with the output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request adds phinx.php, db/migrations/<timestamp>_create_users_table.php, db/seeds/UserSeeder.php, src/Infrastructure/Persistence/User/PdoUserRepository.php and tests/Infrastructure/Persistence/User/PdoUserRepositoryTest.php, and changes composer.json, composer.lock, app/settings.php, app/dependencies.php, app/repositories.php, .gitignore and .github/workflows/tests.yml. Its description pastes phinx status before and after composer migrate, the phpunit, phpstan and phpcs results, and the curl localhost:8080/users body showing the five seeded users.

The Tests workflow runs on the trimmed matrix on the pull request, so the reviewer sees the suite and the static analysis pass on PHP 8.1 and 8.2. The run's record keeps every command, including the migration against the SQLite file and the test's migration against an in-memory database, so a reviewer can tell the two apart.

Before merging, a reviewer chooses the production adapter and credentials for phinx.php, decides whether migrations run from a deploy step or by hand, and whether the Docker Compose service should gain a database container. The actions, routes and the User entity are unchanged.

Run it on every Slim service still reading from memory

A team with several Slim services starts one run per repository from its own server: a POST /o/{org}/sessions each, with the repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own app/repositories.php, so a service that already uses PDO gets Phinx added around its existing schema with a baseline migration, and one on Doctrine gets the migrations proposed through Doctrine's own tool instead.

After that, a Linear issue labelled schema in the Project can start a run through an automation with a linear trigger and the prompt "write the Phinx migration this issue describes, update the repository and its test, run phpunit and open a pull request"; the trigger adds the issue after the prompt, and the run reads it through the Linear connection. Each schema change then arrives as a reviewable migration rather than a hand-run script.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Moving a skeleton off its in-memory repository is a cross-cutting change: a migration tool with a PHP floor the project does not meet, a container definition that has to exist before the repository does, and a test suite that mocks the interface and must keep passing. The agent reads the real container wiring, notices the PHP floor before composer require fails in CI, and runs the migration, the seed and the HTTP request in its sandbox before the pull request exists.

Every command stays with the run, from phinx status to the curl, and the pull request quotes them. A handful of Slim services get the same treatment at once, each on its own machine with its own output and pull request.

Frequently asked questions

Why does the pull request raise the PHP version?

Because the current Phinx release requires PHP 8.1 and the skeleton allows 7.4 and 8.0, which are past end of life. The agent raises the php floor and removes those two from the CI matrix, and says so in the pull request. A team that cannot move can pin an older Phinx release; the pull request names the constraint to change.

Do the existing tests still pass?

Yes. The action tests in tests/Application/Actions/User build the app through TestCase::getAppInstance and replace UserRepository in the container with a Prophecy double, so they never touch PDO. The new repository test is the only one that migrates a database, and it uses an in-memory SQLite connection.

Why keep the in-memory repository?

It costs nothing, it is useful for tests and local experiments, and removing it is an unrelated decision. app/repositories.php now points the interface at PdoUserRepository; switching back is one line.

Which database does this use in production?

Whichever phinx.php reads from DB_ADAPTER and the related variables; SQLite under var/ is only the default so composer start works out of the box. Phinx supports MySQL, PostgreSQL, SQLite and SQL Server, and the PdoUserRepository uses standard prepared statements, so the choice is configuration, not code.

More Slim jobs

The same job on other stacks

Keep reading