PHP Cody Tutorial

InspectIO can connect to a coding bot called Cody. With its help you can generate working code from an event map. Check out the slide deck From Event Storming to Working Code for a quick overview. This tutorial guides you through the first steps. You'll learn the basics as well as customizing code generation to suit your needs.

This tutorial is also available for our Node.js Cody Bot

Preparation

We've prepared a repository containing some exercises.

Please make sure you have installed Docker and Docker Compose to execute the exercises. PHPUnit is used to validate the results.

It's important to follow each setup step. The exercises require a specific folder structure to function correctly!

1. Create a new folder (f.e. in your home directory) that will contain the exercises as well as the coding bot.

mkdir cody-tutorial
cd cody-tutorial

2. Clone exercises from Github

git clone https://github.com/event-engine/php-iio-cody-tutorial.git exercises

3. Install exercises dependencies

cd exercises
docker-compose run --rm composer install 

4. Setup coding bot

# Change back to root directory cody-tutorial
cd ..

# Install Cody Server using composer
docker run --rm -it \
    -v $(pwd):/app \
    -u $(id -u ${USER}):$(id -g ${USER}) \
    prooph/composer:7.4 create-project \
        -s dev \
        --remove-vcs \
        event-engine/php-inspectio-cody \
        /app/cody-bot

# Change into bot directory and prepare first start
cd cody-bot
cp .env.dist .env # Adjust UID in .env if needed
cp app.env.dist app.env
./dev.sh

5. Create cody tutorial board on InspectIO and test connection

You can use InspectIO free version for the tutorial (no login required).

InspectIO is a modeling tool specifically designed for remote Event Storming. It ships with realtime collaboration features for teams (only available in paid version). The free version is a standalone variant without any backend connection. Your work is stored in local storage and can be exported. It is hosted on Github Pages and has the same code generation capabilities as the SaaS version.

Create a new board called "Cody Tutorial". You'll be redirected to the fresh board. Choose "Cody" from top menu to open the Cody Console. Just hit ENTER in the console to connect to the default Cody server that we've setup and started in the previous step.

Finally type "/help" in the console to let Cody explain the basic functionality.

6. Mount exercises to Cody Bot

The Cody Server (coding bot) runs in a docker container. To be able to generate source code it needs access to a code repository. In our case this is the exercises repository. We can mount the directory to the server by modifying docker-compose.yml located in the server repository cody-bot:

version: '2'

services:
  iio-ic-react-http:
    image: prooph/php:7.4-cli
    volumes:
      - .:/app
     # ADD THE FOLLOWING LINE:
      - ../exercises:/exercises
    user: ${UID}
    ports:
      - 3311:8080
    env_file:
      - ./app.env
    command: vendor/bin/php-watcher public/index.php

7. Prepare codyconfig

Cody is a proxy to your own code generation logic. More on that in a second. A central codyconfig.php file tells Cody what to do when it receives tasks from InspectIO. As a first step we register the newly mounted /exercises directory in a context object as a base path for all generated code files. Open cody-bot/codyconfig.php and modify it like this:

<?php

/**
 * @see       https://github.com/event-engine/php-inspectio-cody for the canonical source repository
 * @copyright https://github.com/event-engine/php-inspectio-cody/blob/master/COPYRIGHT.md
 * @license   https://github.com/event-engine/php-inspectio-cody/blob/master/LICENSE.md MIT License
 */

declare(strict_types=1);

use EventEngine\InspectioCody\CodyConfig;

$context = new stdClass(); // replace it with your own context class

// ADD THE FOLLOWING LINE:
$context->path = '/exercises/src';

return new CodyConfig(
    $context,
    [
//        CodyConfig::HOOK_ON_AGGREGATE => new AggregateHook(),
//        CodyConfig::HOOK_ON_COMMAND => new CommandHook(),
//        CodyConfig::HOOK_ON_EVENT => new EventHook(),
//        CodyConfig::HOOK_ON_POLICY => new PolicyHook(),
//        CodyConfig::HOOK_ON_DOCUMENT => new DocumentHook(),
    ]
);

8. Restart Cody

Finally let's restart Cody so that our changes take effect:

docker-compose stop && docker-compose up -d

Please Note: Restarting the docker container is only needed because we've added a volume mount in docker-compose.yml. When adding or changing something in the Cody Bot source code a file watcher takes care of restarting the server.

Recap Preparation

Cody is a http server running in a docker container on your local machine. InspectIO can connect to it using /connect [server address] in the Cody Console. codyconfig.php is the central place to configure code generation. Generated code needs to be written to a target repository. We can use a docker volume mount to give Cody access to our project repository. In the tutorial our project is represented by exercises, which contains a PHPUnit test case for each exercise to validate that generated code looks like the expected one.

Next - Exercise I