This document gives an overview of how Kimai works. It is intended for developers (core and extensions).
First lets talk about the wording used in Kimai to describe things:
Floater (or Dialog)
Those are the dragable “windows” which open as an overlay in the page. For example the preferences dialog or the dialog to add new timerecords.
The lists in the lower part which show users, customers, projects and events.
PHP files which handle AJAX calls.
Every tab you see in Kimai (like timesheet, export, admin panel) is an extension.
- core these are the dispatcher files for kimai (entry points for web/mobile/api/floater)
- css stylesheets which are independant of any skin
- extensions every subfolders is one extension, for details see the chapter below
- grfx graphics which are independant of any skin (like the logo)
- includes Files which are needed in almost every other file.
- autoconf.php Contains the configuration given by the user during setup. (Database connection information)
- basics.php Simple wrapper to include all usually necessary files like functions and database layer.
- db_layer_mysql.php as an example this is the database layer when the mysql extension is used to connect to the database
- func.php Database independant functions are placed here.
- kspi.php “Kimai Standard Processor Initialization” is included by every processor. Some setup is done here.
- installer Installer for Kimai.
- languages Every file is shown as a possible langauge (without the .php file extension) in the preferences dialog.
- libraries External libraries which are used (and possibly modified) by Kimai.
- jQuery Some JQuery files, like datepicker.
- tcpdf Library to create PDF files using pure PHP.
- skins Currently contains only one skin. Other folders will be shown as available skins. Only the styles.css is mandatory. But for the sake of readability you should split your stylesheets up into several files.
- templates Templates used by the core, e.g. login forms and sublists.
- temporary Used for temporary file creation.
Login happens at the /index.php file. This is where you land when you open the kimai folder in your browser. Both, customers and users can login through the same login mask. For conflicting names (user and customer have the same name) the customer account takes precendence.
After a successfull login the user is redirected to /core/kimai.php. Here all extensions are loaded and the main user interface is being build.
Only after an extension/tab is selected its content is being loaded. This is handled by the init.php file in the extensions folder. The processor.php file handles AJAX calls and floater.php creates those dragable windows.
Install a release
From time to time we will release ZIP archives. These are most often beta versions, to be tested by our user base for problems and bugs. Prodution ready releases will be linked specifically in the download section at our website.
You can download the current developer-version as ZIP from our master branch at GitHub.
Install from the repository
To get the developer version use the repository. Please keep in mind, that this version is NOT stable! We like to receive bug reports to be faster with fixing them, but we can not guarantee support for these versions.
We recommend using a fork, so any changes made can be pushed back and then submitted back via pull-requests:
- Fork Kimai
- Clone it locally:
git clone https://github.com/YOUR-USERNAME/kimai.git
Then, if you want to make changes and submit them, use a feature branch:
git checkout -b my-feature
git commit -am "Added my feature"
git push origin my_kimai
Create a pull request from your GitHub repo page.
Build Kimai from source
Nightly Builds can be created by zipping the “core”-folder. Thats all you have todo.
For beta versions we have to edit the file “includes/version.php” and change $kga[‘status’] to “beta”.
For a release we have to do the following:
- Deactivate “Debug Extension” by prepending a # to the folder name
- Change $kga[‘status’] to an empty string
- Add error_reporting(E_ERROR); to “basics.php”