|
1 | 1 | # php-engine-skeleton |
2 | | -Dockerized PHP skeleton for Event Engine |
| 2 | + |
| 3 | +Dockerized PHP skeleton for [Event Engine](https://event-engine.io) |
| 4 | + |
| 5 | +## Installation |
| 6 | +Please make sure you have installed [Docker](https://docs.docker.com/engine/installation/ "Install Docker") and [Docker Compose](https://docs.docker.com/compose/install/ "Install Docker Compose"). |
| 7 | + |
| 8 | +```bash |
| 9 | +$ docker run --rm -it -v $(pwd):/app prooph/composer:7.2 create-project event-engine/php-engine-skeleton <your_project_name> |
| 10 | +$ cd <your_project_name> |
| 11 | +$ sudo chown $(id -u -n):$(id -g -n) . -R |
| 12 | +$ docker-compose up -d |
| 13 | +$ docker-compose run php php scripts/create_event_stream.php |
| 14 | +``` |
| 15 | + |
| 16 | +## Customization |
| 17 | + |
| 18 | +Replace `MyService` in all files to your appropriate service namespace. |
| 19 | + |
| 20 | +## Tutorial |
| 21 | + |
| 22 | +[https://event-engine.io/php-tutorial/](https://event-engine.io/php-tutorial/) |
| 23 | + |
| 24 | +Head over to `http://localhost:8080` to check if the containers are up and running. |
| 25 | +You should see a "It works" message. |
| 26 | + |
| 27 | +### Database |
| 28 | + |
| 29 | +The skeleton uses a single Postgres database for both write and read model. |
| 30 | + |
| 31 | +You can connect to the Postgres DB using following credentials (listed also in `app.env`): |
| 32 | + |
| 33 | +```dotenv |
| 34 | +PDO_DSN=pgsql:host=postgres port=5432 dbname=event_engine |
| 35 | +PDO_USER=postgres |
| 36 | +PDO_PWD= |
| 37 | +``` |
| 38 | + |
| 39 | +*Note: The DB runs insight a docker container. Use `localhost` as host name if you want to connect from your host system!* |
| 40 | + |
| 41 | +### RabbitMQ |
| 42 | + |
| 43 | +The skeleton uses RabbitMQ as a message broker with a preconfigured exchange called `ui-exchange` and a corresponding |
| 44 | +queue called `ui-queue`. You can open the Rabbit Mgmt UI in the browser: `http://localhost:8081` and login with `user: prooph` |
| 45 | +and `password: prooph`. |
| 46 | + |
| 47 | +The skeleton also contains a demo JS client which connects to a websocket and consumes messages from the `ui-queue`. |
| 48 | +Open `http://localhost:8080/ws.html` in your browser and forward events on the queue with `$eventEngine->on(Event::MY_EVENT, UiExchange::class)`. |
| 49 | +Check `src/Domain/Api/Listener` for an example. |
| 50 | + |
| 51 | +## Unit and Integration Tests |
| 52 | + |
| 53 | +We've prepared a `BaseTestCase` located in `tests`. Extend your test cases from that class to get access to some very useful test helpers. |
| 54 | +Check the tutorial for a detailed explanation. |
| 55 | + |
| 56 | +You can run the tests using docker: |
| 57 | + |
| 58 | +```bash |
| 59 | +docker-compose run php php vendor/bin/phpunit |
| 60 | +``` |
| 61 | + |
| 62 | +## Troubleshooting |
| 63 | + |
| 64 | +With the command `docker-compose ps` you can list the running containers. This should look like the following list: |
| 65 | + |
| 66 | +```bash |
| 67 | + Name Command State Ports |
| 68 | +--------------------------------------------------------------------------------------------------------------------------------------------------- |
| 69 | +proophbuildingmgmt_event_engine_projection_1 docker-php-entrypoint php ... Up |
| 70 | +proophbuildingmgmt_nginx_1 nginx -g daemon off; Up 0.0.0.0:443->443/tcp, 0.0.0.0:8080->80/tcp |
| 71 | +proophbuildingmgmt_php_1 docker-php-entrypoint php-fpm Up 9000/tcp |
| 72 | +proophbuildingmgmt_postgres_1 docker-entrypoint.sh postgres Up 0.0.0.0:5432->5432/tcp |
| 73 | +proophbuildingmgmt_rabbit_1 docker-entrypoint.sh rabbi ... Up 0.0.0.0:8081->15671/tcp, 15672/tcp, |
| 74 | + 0.0.0.0:15691->15691/tcp, 25672/tcp, 4369/tcp, 5671/tcp, |
| 75 | + 5672/tcp |
| 76 | +``` |
| 77 | + |
| 78 | +Make sure that all required ports are available on your machine. If not you can modify port mapping in the `docker-compose.yml`. |
| 79 | + |
| 80 | +### Have you tried turning it off and on again? |
| 81 | + |
| 82 | +If something does not work as expected try to restart the containers first: |
| 83 | + |
| 84 | +```bash |
| 85 | +$ docker-compose down |
| 86 | +$ docker-compose up -d |
| 87 | +``` |
| 88 | + |
| 89 | +### Projection reset |
| 90 | + |
| 91 | +The Event Engine Skeleton uses a single projection process (read more about prooph projections in the [prooph docs](http://docs.getprooph.org/event-store/projections.html#3-4)). |
| 92 | +You can register your own projections in event engine which are all handled by the one background process that is started automatically |
| 93 | +with the script `bin/event_engine_projection.php`. Also see `docker-compose.yml`. |
| 94 | +The projection container is not activated by default. Uncomment it in the `docker-compose.yml` to make use of it. |
| 95 | + |
| 96 | +Docker is configured to restart the projection container in case of a failure. |
| 97 | +In dev mode, the projection process dies from time to time to catch up with your latest code changes. |
| 98 | + |
| 99 | +If you recognize that your read models are not up-to-date or you need to reset the read model you can use this command: |
| 100 | + |
| 101 | +```bash |
| 102 | +$ docker-compose run php php bin/reset.php |
| 103 | +``` |
| 104 | + |
| 105 | +If you still have trouble try a step by step approach: |
| 106 | + |
| 107 | +```bash |
| 108 | +$ docker-compose stop event_engine_projection |
| 109 | +$ docker-compose run php php bin/reset.php |
| 110 | +$ docker-compose up -d |
| 111 | +``` |
| 112 | + |
| 113 | +You can also check the projection log with: |
| 114 | + |
| 115 | +```bash |
| 116 | +$ docker-compose logs -f event_engine_projection |
| 117 | +``` |
| 118 | + |
| 119 | +### Swagger UI is not updated |
| 120 | + |
| 121 | +When you add new commands or queries in Event Engine the Swagger UI will not automatically reread the schema from the backend. |
| 122 | +Simply reload the UI or press `Explore` button. |
| 123 | + |
| 124 | + |
| 125 | +## Batteries Included |
| 126 | + |
| 127 | +You know the headline from Docker, right? |
| 128 | +The Event Engine skeleton follows the same principle. It ships with a default set up so that you can start without messing around with configuration and such. |
| 129 | +The default set up is likely not what you want to use in production. The skeleton can be and **should be** adapted. |
| 130 | + |
| 131 | +Focus of the skeleton is to provide *an easy to use development environment*, hence it uses default settings of Postgres and RabbitMQ containers. |
| 132 | +**Make sure to secure the containers before you deploy them anywhere!** You should build and use your own docker containers in production anyway. |
| 133 | +And if you cannot or don't want to use Docker then provide the needed infrastructure the way you prefer and just point Event Engine to it by adjusting configuration. |
| 134 | + |
| 135 | +## Powered by prooph software |
| 136 | + |
| 137 | +[](http://prooph.de) |
| 138 | + |
| 139 | +Event Engine is maintained by the [prooph software team](http://prooph-software.de/). The source code of Event Engine |
| 140 | +is open sourced along with an API documentation and a getting started demo. Prooph software offers commercial support and workshops |
| 141 | +for Event Engine as well as for the [prooph components](http://getprooph.org/). |
| 142 | + |
| 143 | +If you are interested in this offer or need project support please [get in touch](http://getprooph.org/#get-in-touch). |
| 144 | + |
0 commit comments