Kimai logo Kimai Docs Developer

Development environment

How to setup your local developer environment, tools and best practices

Kimai 1.14 2.24.0 (latest version)

This page is for all developers who want to contribute to Kimai. You rock!

Setting up your environment

All you need is:

  • a recent PHP version, best is 8.3+
  • some standard PHP extensions, see composer file for more infos
  • a MariaDB 11.1+ or MySQL 8.3+ instance
  • Composer and git

Development installation

Clone the repository and install all dependencies:

git clone https://github.com/kimai/kimai.git
cd kimai/
composer install

You need to change your environment to dev and configure your database connection in your .env file:

APP_ENV=dev
DATABASE_URL=mysql://user:password@127.0.0.1:3306/database?charset=utf8mb4&serverVersion=8.3.0

The next command will import demo data, to test the application in its full beauty - with different user accounts, customers, projects, activities and several thousand timesheet records. Let’s bootstrap your database (command only available in dev environment):

bin/console kimai:reset:dev

Almost there!

Now you need to start a web server and can access Kimai in your browser. Its totally up to you how to achieve that, I can recommend the Symfony local webserver (it is fast and supports local https setup):

symfony serve --port=8010

You can now log in with these accounts:

Username Password API Key Role
clara_customer password token Customer
john_user password token User
chris_user password token User (deactivated)
tony_teamlead password token Teamlead
anna_admin password token Administrator
susan_super password token Super-Administrator

Demo data can always be deleted by dropping the schema and re-creating it. The kimai:reset:dev command will do that automatically and can always be executed later on to reset your dev database and cache.

If you want to test with an empty installation, erase the database and re-create an empty schema:

bin/console doctrine:schema:drop --force
bin/console doctrine:schema:create

Frontend dependencies

If you want to make changes to CSS / Javascript, you need:

Please install Yarn for your OS and then:

yarn install

To rebuild all assets you have to execute:

yarn run prod

You can find more information here and here.

local.yaml

Beware: if you use the local.yaml then don’t put it in config/packages/ as all configs in there are used when running the PHPUnit testsuite.

The (integration) tests are written to work with the default configuration of Kimai and locally changed configs might unexpectedly break the tests.

Therefor put your local.yaml into the dev/ folder: config/packages/dev/local.yaml.

Tests suites with PHPUnit

Kimai tries to adopt a high test and code coverage. Whenever changing code, you have to make sure that the tests are still running. New code needs additional tests, otherwise your pull request might be declined.

You can run the unit and integration tests with built-in commands:

composer kimai:tests-unit
composer kimai:tests-integration

Or you simply run all tests with one of:

  • composer kimai:tests
  • vendor/bin/phpunit

Static code analysis via PHPStan

Besides automated tests Kimai relies on PHPStan to detect code problems.

composer kimai:phpstan

Coding styles

You can run the code sniffer with the built-in command like that:

composer kimai:codestyle

And you can also automatically fix the violations by running:

composer kimai:codestyle-fix

Be aware that this command will modify all files with violations in the directories src/ and tests/, so its a good idea to commit first.

Kimai code-styles are configured in .php_cs.dist.

Top