T.F.V. 'Professor Francken'
This is the repository containing code for the new website of T.F.V. Porfessor Francken. We are using the Laravel v5.2 framework in combination with Broadway, an infrastructure library for creating CQRS and Event Sourced applications.
You can find some high quality introductory videos on laravelfromscratch.com. For more info on Broadway, watch Willem-Jan Zijderveld speak on CQRS and Event Sourcing.
- Getting started
- An introduction to this application's folder and namespace structure
If you want to get started working on our website, first clone the repository
using git. Next copy the
.env.example file and name the copy
docker-compose run composer install and
docker-compose run yarn
in the root of the project.
Once you've installed the dependencies run
docker-compose run php php artisan key:generate to generate an application key.
docker-compose run php php artisan migrate:refresh --seed to setup a
sqlite database and lastly run
docker-compose up nginx to start the website.
You can now visit the website at localhost.
Run the following commands to setup and start the website.
git clone email@example.com:ProfessorFrancken/ProfessorFrancken.git Francken && cd Francken cp .env.example .env docker-compose run composer install docker-compose run yarn docker-compose run npm npm run dev docker-compose run php php artisan key:generate docker-compose run php php artisan migrate:refresh --seed docker-compose up nginx
Before you push your changes to this repository make sure that the tests are all green and that there are no issues with code style.
Below you will find a quick summary on how to run the tests and a code style fixer.
Generating css (or compiling assets)
We use scss which compiles to css.
Alternatively if you prefer to use a docker container (that is if you have
installed Docker but don't have npm installed), then you can run
docker-compose run npm npm install.
npm run dev
in the root of this project (the folder in which a
package.json file is
present), or alternatively use
docker-compose run npm npm run dev.
The compiled files will be placed in the
/public/dist folder. This folder is
added to our
.gitignore so you won't see the folder until you run the above
Check the documentation of Laravel Mix to learn more about how our assets (css & js) are compiled.
I haven't yet tested whether this works on Windows.. If you're using Docker (which you should :-)) then the docker commands should work.
We use phpunit for most of our tests. To execute the tests using Docker run,
docker-compose run php vendor/bin/phpunit
We're using the PSR-2 code style guidelines as well as PSR-4 for autoloading classes.
See the PHP-fig for more info on the standards.
You can use
fabpot/php-cs-fixer to verify that your code conforms to the PSR-2
code style guidelines. By running the following command in the root directory
all code style issues be found.
vendor/bin/php-cs-fixer fix . --level=psr2 --dry-run --fixers=-psr0
By removing the
--dry-run option any issues found by the program will be fixed
automatically. Add the
--diff option to show the diff for each file.
N.B. once we've gone open source we will use a continuous integration service
that automatically checks whether your PR conforms to the code style guidelines.
Note we omit the
psr0 fixer. This fixer looks at the namespace declarations
however it is not compatible with PSR-4, which is an improvement over PSR-0.
The master branch is a protected branch, meaning you won't be able to force push changes to the master branch and status checks (i.e. tests should be green) are required before merging to master. Before sending a pull request with your latest changes you should make sure that your branch is up to date by rebasing your branch onto master. This makes it easier to review your pull request since there won't be many merge commits and it gives us a nice linear history.
We generally use a git flow ish git model. Since this application hasn't been pushed to production yet we won't be very strict about this, however you should try to be consistent with the naming of branching (i.e. using feature and branches and bug fix branches).
An introduction to this application's folder and namespace structure
This application is build upon an hexagonal architecture and is inspired by the talk Hexagonal architecture - message oriented software design by Matthias Noback.
The application is divided by three layers: a Domain layer, Application layer and an Infrastructure layer. Each layer is only allowed to be dependent on its own layer, or a layer "below" it. Doing so ensures that we can use dependency inversion and makes our application more testable.
The domain layer contains all of the business logic. Except for Broadway this layer should not have any external dependencies and must be framework agnostic.
The code in the domain layer should have 100% line and mutation coverage and should only need unit tests.
The docs folder contains some documentation of important domain concepts.
The application layer gives us an entry point into the domain layer. Inside the application layer we can find use cases of some our domain concepts. These use cases can be commands and command handlers, projections, event handlers and processors. The code inside this layer should be framework agnostic and should not need acceptance tests, however each class should be unit and integration tested.
We use projectors to generate read models. Currently these projectors are placed
App\ReadModels. Once you've created a projector you should add its Fully
Qualified Classs Name (FQCN) to the
event_sourcing.php config file.
The application will then automatically call each of the projectors in the
config file when an event is published.
The infrastructure layer is the only layer that is not framework agnostic and could as well be called the "framework layer". This layer contains Laravel's service providers and the console and http kernels and their commands and controllers. It may also contain implementations of repositories, notification services etc.
Code inside the infrastructure layer should be tested using acceptance criteria. Unit and integration tests should be written whenever they are useful.