removed inline documentation (#624)
This commit is contained in:
Kevin Papst
@@ -11,7 +11,7 @@ Send us your ideas, code reviews, pull requests and feature requests to help us
|
||||
- With sending in a PR, you accept that your contributions/code will be published under MIT license (see the [LICENSE](LICENSE) file as well).
|
||||
- If one of the PR checks fails, please fix them before asking us for a review.
|
||||
|
||||
Further documentation can be found in the [developer documentation](var/docs/developers.md).
|
||||
Further documentation can be found in the [developer documentation](https://www.kimai.org/documentation/developers.html).
|
||||
|
||||
### File-header template
|
||||
```
|
||||
|
||||
@@ -16,16 +16,16 @@ It is built from scratch and doesn't share any source code with its [predecessor
|
||||
But it adapts the same ideas and a clean & simple UI for your time-tracking experience.
|
||||
|
||||
By now it is in an pre-stable development phase, usable and with most advanced features from Kimai 1.
|
||||
You can even [import your data](var/docs/migration_v1.md) and start testing and using it today.
|
||||
You can even [import your data](https://www.kimai.org/documentation/migration-v1.html) and start testing and using it today.
|
||||
|
||||
Kimai is a [multi-language application](var/docs/translations.md) and already translated to english, german, italian, french, spanish, russian, arabic, hungarian and portuguese.
|
||||
Kimai is a [multi-language application](https://www.kimai.org/documentation/translations.html) and already translated to english, german, italian, french, spanish, russian, arabic, hungarian and portuguese.
|
||||
|
||||
### Requirements
|
||||
|
||||
- PHP 7.1.3 or higher (test your system compatibility with the [requirements-checker](http://symfony.com/doc/current/reference/requirements.html))
|
||||
- The PHP extensions [xml](http://php.net/manual/en/book.xml.php), [mbstring](http://php.net/manual/en/book.mbstring.php), [gd](http://php.net/manual/en/book.image.php), [intl](https://php.net/manual/en/book.intl.php), [zip](https://php.net/manual/en/book.zip.php) and [PDO](https://php.net/manual/en/book.pdo.php) with either [pdo_sqlite](https://php.net/manual/en/ref.pdo-sqlite.php) or [pdo_mysql](https://php.net/manual/en/ref.pdo-mysql.php) enabled
|
||||
- Kimai needs its own sub-domain or you need to [recompile the frontend assets](var/docs/developers.md) for usage in a sub-directory
|
||||
- If you use MariaDB, make sure its at least v10.2.7 (see [FAQ](var/docs/faq.md))
|
||||
- Kimai needs its own sub-domain or you need to [recompile the frontend assets](https://www.kimai.org/documentation/developers.html) for usage in a sub-directory
|
||||
- If you use MariaDB, make sure its at least v10.2.7 (see [FAQ](https://www.kimai.org/documentation/faq.html))
|
||||
- A modern browser, Kimai v2 might be broken on old browsers like IE 10
|
||||
|
||||
## Documentation
|
||||
|
||||
@@ -38,7 +38,7 @@ Check if you want to apply changes to your `local.yaml`:
|
||||
## [0.7](https://github.com/kevinpapst/kimai2/releases/tag/0.7)
|
||||
|
||||
The configuration `kimai.theme.active_warning` was deprecated and should be replaced in your local.yaml,
|
||||
[read config docs for more information](https://github.com/kevinpapst/kimai2/blob/master/var/docs/configurations.md#limit-active-entries).
|
||||
[read config docs for more information](https://www.kimai.org/documentation/timesheet.html#limit-active-entries).
|
||||
|
||||
## [0.6.1](https://github.com/kevinpapst/kimai2/releases/tag/0.6.1)
|
||||
|
||||
@@ -56,7 +56,7 @@ Some configuration nodes were removed, if you have one of them in your `local.ya
|
||||
- `kimai.invoice.renderer`
|
||||
- `kimai.invoice.number_generator`
|
||||
|
||||
The new config `kimai.invoice.documents` was introduced, holding a list of directories ([read more](https://github.com/kevinpapst/kimai2/blob/master/var/docs/invoices.md)).
|
||||
The new config `kimai.invoice.documents` was introduced, holding a list of directories ([read more](https://www.kimai.org/documentation/invoices.html)).
|
||||
|
||||
**BC break:** InvoiceTemplate name was changed from 255 characters to 60. If you used longer invoice-template names, they will be truncated when upgrading the database.
|
||||
Please make sure that they are unique in the first 60 character before you upgrade your database with `doctrine:migrations:migrate`.
|
||||
@@ -79,7 +79,7 @@ sudo -u www-data composer update symfony/flex --no-plugins --no-scripts
|
||||
|
||||
## [0.3](https://github.com/kevinpapst/kimai2/releases/tag/0.3)
|
||||
|
||||
You need to adjust your `.env` file and add your `from` address for [all emails](https://github.com/kevinpapst/kimai2/blob/master/var/docs/emails.md) generated by Kimai 2:
|
||||
You need to adjust your `.env` file and add your `from` address for [all emails](https://www.kimai.org/documentation/emails.html) generated by Kimai 2:
|
||||
```
|
||||
MAILER_FROM=kimai@example.com
|
||||
```
|
||||
|
||||
@@ -105,16 +105,6 @@ $(function() {
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
$('.markdown-body :header').prepend(function() {
|
||||
$(this).prepend('<a class="anchor" href="#'+$(this).attr('id')+'"><i class="fas fa-link"></i>');
|
||||
});
|
||||
|
||||
$('.markdown-body :header').hover(function(){
|
||||
$(this).find('a.anchor').show();
|
||||
}, function(){
|
||||
$(this).find('a.anchor').hide();
|
||||
});
|
||||
},
|
||||
reloadDatatableWithToolbarFilter: function() {
|
||||
var $form = $('.toolbar form');
|
||||
|
||||
@@ -37,5 +37,4 @@ footer.main-footer {
|
||||
@import 'calendar';
|
||||
@import 'dashboard';
|
||||
@import 'navbar';
|
||||
@import 'documentation';
|
||||
@import 'daterangepicker';
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
/*
|
||||
* This file is part of the Kimai time-tracking app.
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
.markdown-body {
|
||||
h1, h2, h3, h4, h5, h6 {
|
||||
a.anchor {
|
||||
float: left;
|
||||
font-size: 0.5em;
|
||||
margin-left: -1em;
|
||||
padding-top: 0.5em;
|
||||
color: $text-color;
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@media (min-width: $screen-sm-min) {
|
||||
.markdown-body {
|
||||
padding-left: 25px;
|
||||
}
|
||||
}
|
||||
@@ -30,7 +30,7 @@ kimai:
|
||||
|
||||
# If you want to apply different hourly rates for specific weekdays, you can uncomment the "rates" configuration.
|
||||
# The "weekend" rule will add 50% to each timesheet entry that will be recorded on "saturdays" or "sundays".
|
||||
# Please read var/docs/configurations.md to find out more about rates rules
|
||||
# See documentation about rate rules: https://www.kimai.org/documentation/timesheet.html#rate-calculation
|
||||
# rates:
|
||||
# weekend:
|
||||
# days: ['saturday','sunday']
|
||||
@@ -196,8 +196,8 @@ kimai:
|
||||
# color: '#ccc'
|
||||
|
||||
# --------------------------------------------------------------------------------
|
||||
# theme related settings, will be available as twig globals at "kimai_context.*"
|
||||
# please see documentation at var/docs/theme.md
|
||||
# Theme related settings, will be available as twig globals at "kimai_context.*".
|
||||
# See documentation at https://www.kimai.org/documentation/theme.html
|
||||
theme:
|
||||
# BETA test: If you set this to 'selectpicker' the customer/project/activity select boxes will be transformed
|
||||
# into a searchable and javascript enhanced input type
|
||||
@@ -207,7 +207,8 @@ kimai:
|
||||
box_color: 'green'
|
||||
|
||||
# --------------------------------------------------------------------------------
|
||||
# Dashboard widget sections, please see documentation at var/docs/dashboard.md
|
||||
# Dashboard widget sections.
|
||||
# See documentation at https://www.kimai.org/documentation/dashboard.html
|
||||
dashboard:
|
||||
user_duration:
|
||||
title: dashboard.you
|
||||
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"build/app.js": "/build/app.js?cae858aec32ae026057b",
|
||||
"build/app.css": "/build/app.css?e067eb7af0fed5e92ada44bb38e51cb5",
|
||||
"build/app.js": "/build/app.js?f4920c78e36b8782bf97",
|
||||
"build/app.css": "/build/app.css?8a23cdbf97765f6025693a6288873cd2",
|
||||
"build/images/blue@2x.png": "/build/images/blue@2x.png?2694acfd",
|
||||
"build/images/blue.png": "/build/images/blue.png?96f8a905",
|
||||
"build/fonts/fa-solid-900.woff2": "/build/fonts/fa-solid-900.woff2?e8a92a29",
|
||||
|
||||
@@ -1,81 +0,0 @@
|
||||
<?php
|
||||
|
||||
/*
|
||||
* This file is part of the Kimai time-tracking app.
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
namespace App\Controller;
|
||||
|
||||
use App\Constants;
|
||||
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;
|
||||
use Symfony\Component\Routing\Annotation\Route;
|
||||
|
||||
/**
|
||||
* This controller can render the markdown documentation from /var/docs/
|
||||
*
|
||||
* @Route(path="/help")
|
||||
* @Security("is_granted('ROLE_USER')")
|
||||
*/
|
||||
class HelpController extends AbstractController
|
||||
{
|
||||
public const README = 'README';
|
||||
public const DOCS_DIR = 'var/docs/';
|
||||
|
||||
/**
|
||||
* @var string
|
||||
*/
|
||||
protected $projectDirectory;
|
||||
|
||||
/**
|
||||
* HelpController constructor.
|
||||
* @param string $projectDirectory
|
||||
*/
|
||||
public function __construct(string $projectDirectory)
|
||||
{
|
||||
$this->projectDirectory = $projectDirectory;
|
||||
}
|
||||
|
||||
/**
|
||||
* @Route(path="/", defaults={"chapter": "README"}, name="help", methods={"GET"})
|
||||
* @Route(path="/{chapter}", requirements={"chapter": "[a-zA-Z]*"}, name="help_chapter", methods={"GET"})
|
||||
*
|
||||
* @param string $chapter
|
||||
* @return \Symfony\Component\HttpFoundation\Response
|
||||
*/
|
||||
public function indexAction(string $chapter)
|
||||
{
|
||||
$breadcrumb = [self::README];
|
||||
if (self::README !== $chapter) {
|
||||
$breadcrumb[] = $chapter;
|
||||
}
|
||||
|
||||
$chapterFile = $this->getFilenameForChapter($chapter);
|
||||
|
||||
if (!file_exists($chapterFile)) {
|
||||
throw $this->createNotFoundException('Documentation chapter not found: ' . $chapter);
|
||||
}
|
||||
|
||||
$content = file_get_contents($chapterFile);
|
||||
|
||||
$content = preg_replace('/\[(.+)\]\(([\w\-\/]+)(\.md)(\#[\w\-]+){0,1}\)/i', '[$1]($2$4)', $content);
|
||||
|
||||
return $this->render('help/index.html.twig', [
|
||||
'breadcrumb' => $breadcrumb,
|
||||
'chapter' => $chapter,
|
||||
'documentation' => $content,
|
||||
'github' => Constants::GITHUB
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* @param string $chapter
|
||||
* @return string
|
||||
*/
|
||||
protected function getFilenameForChapter(string $chapter)
|
||||
{
|
||||
return $this->projectDirectory . DIRECTORY_SEPARATOR . self::DOCS_DIR . $chapter . '.md';
|
||||
}
|
||||
}
|
||||
@@ -1,25 +0,0 @@
|
||||
{% extends 'base.html.twig' %}
|
||||
|
||||
{% block page_title %}{{ 'help.title'|trans }}{% endblock %}
|
||||
{% block page_subtitle %}{{ 'help.subtitle'|trans }}{% endblock %}
|
||||
|
||||
{% block main %}
|
||||
|
||||
{% set replacer = {
|
||||
'<table>': '<table class="table">',
|
||||
'href="../../': 'target="_blank" href="'~github~'blob/master/',
|
||||
('href="' ~ github): 'target="_blank" href="'~github
|
||||
} %}
|
||||
|
||||
<div class="box">
|
||||
{% if chapter != 'README' %}
|
||||
<div class="box-header with-border">
|
||||
<a href="{{ path('help') }}">{{ 'action.back'|trans }}</a>
|
||||
</div>
|
||||
{% endif %}
|
||||
<div class="box-body markdown-body">
|
||||
{{ documentation|md2html|replace(replacer)|raw }}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{% endblock %}
|
||||
@@ -1,56 +0,0 @@
|
||||
<?php
|
||||
|
||||
/*
|
||||
* This file is part of the Kimai time-tracking app.
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
namespace App\Tests\Controller;
|
||||
|
||||
/**
|
||||
* @coversDefaultClass \App\Controller\HelpController
|
||||
* @group integration
|
||||
*/
|
||||
class HelpControllerTest extends ControllerBaseTest
|
||||
{
|
||||
public function testIsSecure()
|
||||
{
|
||||
$this->assertUrlIsSecured('/help/');
|
||||
}
|
||||
|
||||
public function testReadmePage()
|
||||
{
|
||||
$client = $this->getClientForAuthenticatedUser();
|
||||
$this->request($client, '/help/');
|
||||
$this->assertTrue($client->getResponse()->isSuccessful());
|
||||
$this->assertContains('<h1 id="kimai-documentation">Kimai documentation</h1>', $client->getResponse()->getContent());
|
||||
$this->assertContains('<a href="configurations">', $client->getResponse()->getContent());
|
||||
$this->assertContains('<a href="developers">', $client->getResponse()->getContent());
|
||||
$this->assertContains('<a href="users">', $client->getResponse()->getContent());
|
||||
}
|
||||
|
||||
public function testUsersPage()
|
||||
{
|
||||
$client = $this->getClientForAuthenticatedUser();
|
||||
$this->request($client, '/help/users');
|
||||
$this->assertTrue($client->getResponse()->isSuccessful());
|
||||
$this->assertContains('<a href="/en/help/">Back</a>', $client->getResponse()->getContent());
|
||||
}
|
||||
|
||||
public function testMissingPage()
|
||||
{
|
||||
$client = $this->getClientForAuthenticatedUser();
|
||||
$this->request($client, '/help/foo');
|
||||
$this->assertFalse($client->getResponse()->isSuccessful());
|
||||
$this->assertEquals(404, $client->getResponse()->getStatusCode());
|
||||
}
|
||||
|
||||
public function testValidateRouteDoesNotAllowSpecialChars()
|
||||
{
|
||||
$client = $this->getClientForAuthenticatedUser();
|
||||
$this->request($client, '/help/.users');
|
||||
$this->assertRouteNotFound($client);
|
||||
}
|
||||
}
|
||||
@@ -364,18 +364,6 @@
|
||||
<target>تبديل حالة صفحة الشريط الجانبي الأيسر في صفحة (فتح أو طي)</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Help - Manual
|
||||
-->
|
||||
<trans-unit id="help.title">
|
||||
<source>help.title</source>
|
||||
<target>مساعدة</target>
|
||||
</trans-unit>
|
||||
<trans-unit id="help.subtitle">
|
||||
<source>help.subtitle</source>
|
||||
<target>تعليمات لاستخدام وتكوين Kimai</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Admin: Timesheet
|
||||
-->
|
||||
|
||||
@@ -413,18 +413,6 @@
|
||||
<target>Ansicht und Verwaltung ihrer gebuchten Zeiteinträge anhand eines Kalenders</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Help - Manual
|
||||
-->
|
||||
<trans-unit id="help.title">
|
||||
<source>help.title</source>
|
||||
<target>Hilfe</target>
|
||||
</trans-unit>
|
||||
<trans-unit id="help.subtitle">
|
||||
<source>help.subtitle</source>
|
||||
<target>Anleitung zur Benutzung und Konfiguration von Kimai (nur auf Englisch verfügbar)</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Admin: Timesheet
|
||||
-->
|
||||
|
||||
@@ -413,18 +413,6 @@
|
||||
<target>View and manage your timesheet data within a calendar</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Help - Manual
|
||||
-->
|
||||
<trans-unit id="help.title">
|
||||
<source>help.title</source>
|
||||
<target>Help</target>
|
||||
</trans-unit>
|
||||
<trans-unit id="help.subtitle">
|
||||
<source>help.subtitle</source>
|
||||
<target>Instructions for using and configuring Kimai</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Admin: Timesheet
|
||||
-->
|
||||
|
||||
@@ -368,18 +368,6 @@
|
||||
<target>Alternar la vista de la barra lateral izquierda al cargar la página (abrierta o colapsar)</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Help - Manual
|
||||
-->
|
||||
<trans-unit id="help.title">
|
||||
<source>help.title</source>
|
||||
<target>Ayuda</target>
|
||||
</trans-unit>
|
||||
<trans-unit id="help.subtitle">
|
||||
<source>help.subtitle</source>
|
||||
<target>Documentación para usar y configurar Kimai</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Admin: Timesheet
|
||||
-->
|
||||
|
||||
@@ -368,18 +368,6 @@
|
||||
<target>Faire basculer l'état de la barre latérale gauche lors du chargement de la page (ouverture ou fermeture).</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Help - Manual
|
||||
-->
|
||||
<trans-unit id="help.title">
|
||||
<source>help.title</source>
|
||||
<target>Aide</target>
|
||||
</trans-unit>
|
||||
<trans-unit id="help.subtitle">
|
||||
<source>help.subtitle</source>
|
||||
<target>Instructions pour configuer et utiliser Kimai</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Admin: Timesheet
|
||||
-->
|
||||
|
||||
@@ -382,18 +382,6 @@
|
||||
<target>Nap</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Help - Manual
|
||||
-->
|
||||
<trans-unit id="help.title">
|
||||
<source>help.title</source>
|
||||
<target>Súgó</target>
|
||||
</trans-unit>
|
||||
<trans-unit id="help.subtitle">
|
||||
<source>help.subtitle</source>
|
||||
<target>Segítség a Kimai használatához és beállításához</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Admin: Timesheet
|
||||
-->
|
||||
|
||||
@@ -356,18 +356,6 @@
|
||||
<target>Auto collassa la sidebar di sinistra</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Help - Manual
|
||||
-->
|
||||
<trans-unit id="help.title">
|
||||
<source>help.title</source>
|
||||
<target>Aiuto</target>
|
||||
</trans-unit>
|
||||
<trans-unit id="help.subtitle">
|
||||
<source>help.subtitle</source>
|
||||
<target>Istruzioni su come usare e configurare Kimai</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Admin: Timesheet
|
||||
-->
|
||||
|
||||
@@ -381,18 +381,6 @@
|
||||
<target>Dia</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Help - Manual
|
||||
-->
|
||||
<trans-unit id="help.title">
|
||||
<source>help.title</source>
|
||||
<target>Ajuda</target>
|
||||
</trans-unit>
|
||||
<trans-unit id="help.subtitle">
|
||||
<source>help.subtitle</source>
|
||||
<target>Instruções para usar e configurar o Kimai</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Admin: Timesheet
|
||||
-->
|
||||
|
||||
@@ -360,18 +360,6 @@
|
||||
<target>Управление статусом левой панели навигации (скрыта или открыта)</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Help - Manual
|
||||
-->
|
||||
<trans-unit id="help.title">
|
||||
<source>help.title</source>
|
||||
<target>Помощь</target>
|
||||
</trans-unit>
|
||||
<trans-unit id="help.subtitle">
|
||||
<source>help.subtitle</source>
|
||||
<target>Руководство к пользованию и конфигурации Kimai (доступно только на английском)</target>
|
||||
</trans-unit>
|
||||
|
||||
<!--
|
||||
Admin: Timesheet
|
||||
-->
|
||||
|
||||
@@ -1,30 +0,0 @@
|
||||
# Kimai documentation
|
||||
|
||||
This is the official Kimai v2 documentation.
|
||||
|
||||
Most parts of Kimai should be self-explanatory, but if you miss any information please [let us know](https://github.com/kevinpapst/kimai2/issues)
|
||||
and we will add it as soon as possible.
|
||||
|
||||
## User manual
|
||||
|
||||
- [Timesheets](timesheet.md) - information about timesheets
|
||||
- [Export](export.md) - export filtered timesheet data
|
||||
- [Invoices](invoices.md) - create invoices from timesheet data in different formats with customizable templates
|
||||
- [User and Security](users.md) - docu for user and security topics, like authentication, registration and roles
|
||||
|
||||
## Admins and Developers
|
||||
|
||||
- [Configurations](configurations.md) - intro into the global application configs
|
||||
- [Calendar](calendar.md) - the Timesheet calendar view
|
||||
- [Dashboard & widgets](dashboard.md) - how to configure widgets and dashboard sections
|
||||
- [Emails](emails.md) - transport configuration and handling of emails
|
||||
- [Permissions](permissions.md) - flexible and configurable ROLE based permission system
|
||||
- [Developer](developers.md) - docs about extending Kimai's feature set
|
||||
- [API](developers_api.md) - how to use the JSON API
|
||||
- [Theme settings](theme.md) - theme related settings
|
||||
- [Installation](installation.md) - instructions about several installation methods
|
||||
- [Update Kimai](updates.md) - updating an existing Kimai 2 installation to the latest version
|
||||
- [Docker](docker.md) - using the built-in Dockerfile for development
|
||||
- [Importing data](migration_v1.md) - how to import your timesheets from Kimai v1
|
||||
- [Translations](translations.md) - all about languages and translations
|
||||
- [FAQ](faq.md) - some answers to frequently asked questions
|
||||
@@ -1,52 +0,0 @@
|
||||
# Calendar
|
||||
|
||||
Kimai 2 provides a calendar view, which displays your timesheet entries in a easy readable format.
|
||||
You can choose between a monthly, weekly and daily view.
|
||||
|
||||
The calendar view look and feel is configured with the config keys below `kimai.calendar` in `kimai.yaml` / your [local.yaml](configurations.md):
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
calendar:
|
||||
week_numbers: true
|
||||
day_limit: 4
|
||||
businessHours:
|
||||
days: [1, 2, 3, 4, 5]
|
||||
begin: '08:00'
|
||||
end: '20:00'
|
||||
```
|
||||
|
||||
- `week_numbers` - whether week numbers should be displayed in the monthly view (default: true)
|
||||
- `day_limit` defined the max amount of items to be displayed for one day in the monthly view (default: 4)
|
||||
- `businessHours.days` defines your working days, which will be highlighted in the weekly and daily view. counting starts with sunday and the index 0, so 1 = monday, ..., 6 = saturday. (default: 1-5 / monday to friday)
|
||||
- `businessHours.begin` the start time of your working day, which will be highlighted in the weekly and daily view (default: 08:00 / 8am)
|
||||
- `businessHours.end` the end time of your working day, which will be highlighted in the weekly and daily view (default: 20:00 / 8pm)
|
||||
|
||||
## Initial view
|
||||
|
||||
The initial view for the calendar is `month`.
|
||||
It is a user specific setting and each user can configure it in his _User profile_ at _Preferences_.
|
||||
|
||||
Available options are: `month`, `agendaWeek`, `agendaDay`
|
||||
|
||||
## Integrating google calender
|
||||
|
||||
If you want to embed Google calendars e.g. to display regional holidays or company events you can import (multiple) Google calendars.
|
||||
|
||||
- read how to obtain your [Google API key and find the Calender ID](https://fullcalendar.io/docs/google-calendar)
|
||||
- add the optional `kimai.calendar.google` configuration
|
||||
- you can add any number of sources under the `kimai.calendar.google.sources` node, each must have its own name (like `holidays` and `company` in this example)
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
calendar:
|
||||
google:
|
||||
api_key: 'your-restricted-google-api-key'
|
||||
sources:
|
||||
holidays:
|
||||
id: 'de.german#holiday@group.v.calendar.google.com'
|
||||
color: '#ccc'
|
||||
company:
|
||||
id: 'de.german#holiday@group.v.calendar.google.com'
|
||||
color: '#cc0000'
|
||||
```
|
||||
@@ -1,78 +0,0 @@
|
||||
# Configurations
|
||||
|
||||
This is an introduction into the configuration options and files, which are used by Kimai and an explanantion on how to change them.
|
||||
|
||||
Specific configurations are explained in the detailed feature docs:
|
||||
|
||||
- [Timesheet](timesheet.md)
|
||||
- [Permissions](permissions.md)
|
||||
- [Invoice](invoices.md)
|
||||
- [Calendar](calendar.md)
|
||||
- [Customer](customer.md)
|
||||
- [Emails](emails.md)
|
||||
- [Dashboard widgets](dashboard.md)
|
||||
- [Theme](theme.md)
|
||||
|
||||
## Environment specific settings (.env)
|
||||
|
||||
The most basic settings, which need always be adjusted are stored in the `.env` file:
|
||||
|
||||
- `MAILER_URL` - smtp connection for emails
|
||||
- `MAILER_FROM` - application specific "from" address for all emails
|
||||
- `APP_ENV` - environment for the runtime (use `prod` if you are unsure)
|
||||
- `DATABASE_URL` - database connection for storing all application data
|
||||
- `DATABASE_PREFIX` - precix for any Kimai table in the configured database
|
||||
- `APP_SECRET` - secret used for hasing user password (if you cahnge this, every password is invalid afterwards)
|
||||
|
||||
## Config files
|
||||
|
||||
Configuration of Kimai is spread in all files in the `config/`directory but mainly it these files:
|
||||
|
||||
- `.env` - environment specific settings
|
||||
- `config/packages/kimai.yaml` - Kimai specific settings
|
||||
- `config/packages/admin_lte.yaml` - Kimai base theme
|
||||
- `config/packages/fos_user.yaml` - user management and email settings
|
||||
- `config/packages/local.yaml` - your configuration settings (file needs to be created by yourself)
|
||||
|
||||
There are several other configurations that could potentially be interesting for you in [config/packages/*.yaml](../../config/packages/).
|
||||
|
||||
If you want to adjust a setting from any of these files, use `local.yaml` (see below).
|
||||
|
||||
## Overwriting local configs (local.yaml)
|
||||
|
||||
You should NOT edit the file `config/packages/kimai.yaml` directly, as it contains default settings and will be overwritten during an update.
|
||||
Instead create the file `config/packages/local.yaml` and store your own settings in there. This file will NEVER be shipped with Kimai.
|
||||
Having your custom settings in `local.yaml` allows you to easily update Kimai. This is the same concept which is used for the `.env` file.
|
||||
|
||||
An example `config/packages/local.yaml` file might look like this:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
timesheet:
|
||||
rounding:
|
||||
default:
|
||||
begin: 15
|
||||
end: 15
|
||||
|
||||
admin_lte:
|
||||
options:
|
||||
default_avatar: build/apple-touch-icon.png
|
||||
```
|
||||
|
||||
The `local.yaml` file will be imported as last configuration file, so you can overwrite any setting from the `config/packages/` directory.
|
||||
|
||||
Whenever the documentation asks you to edit a yaml file from the `config/packages/` directory, it means you should copy
|
||||
this specific configuration key to your `local.yaml` in order to overwrite the default configuration.
|
||||
|
||||
## Reload changed configurations
|
||||
|
||||
When you change a configuration file, Kimai will not see this change immediately.
|
||||
You can reload the configs after you are done by rebuilding the Symfony cache with:
|
||||
|
||||
```bash
|
||||
bin/console cache:clear --env=prod
|
||||
bin/console cache:warmup --env=prod
|
||||
```
|
||||
|
||||
Depending on your setup it might be necessary to execute these commands as webserver user,
|
||||
please read the [UPGRADING guide](../../UPGRADING.md) for more details.
|
||||
@@ -1,17 +0,0 @@
|
||||
# Customer
|
||||
|
||||
Customers in Kimai are used to manage project and activities, which are then used for time-records.
|
||||
|
||||
It is very common to have a _customer_ for your own company, to track times for administration and other internal work.
|
||||
|
||||
## Creating customer
|
||||
|
||||
Define the default values for a customer like this:
|
||||
```yaml
|
||||
kimai:
|
||||
defaults:
|
||||
customer:
|
||||
timezone: Europe/London
|
||||
country: GB
|
||||
currency: GBP
|
||||
```
|
||||
@@ -1,126 +0,0 @@
|
||||
# Dashboard
|
||||
|
||||
Read the [configuration chapter](configurations.md) before you start changing your configs.
|
||||
|
||||
## Widgets
|
||||
|
||||
Widgets are defined in the configuration node `kimai.widgets` and you find the pre-defined ones in [kimai.yaml](../../config/packages/kimai.yaml).
|
||||
|
||||
Here is an example of one widget definition:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
widgets:
|
||||
userDurationToday: { title: stats.durationToday, query: duration, user: true, begin: '00:00:00', end: '23:59:59', icon: duration, color: green }
|
||||
```
|
||||
|
||||
Widgets are currently only used in the Dashboard, but maybe used in other template parts as well in the future.
|
||||
|
||||
### Widget settings
|
||||
|
||||
- `title` - the title of your widget (will be translated)
|
||||
- `query` - the allowed queries to use for populating the widget data are `duration`, `rate`, `active` and `users`
|
||||
- `user` - whether the query is executed for the current user or for all users. possible values are `true` and `false` (default: `false` - all data is used to calculate the result)
|
||||
- `begin` - setting the start date for the query, formatted with the [PHP DateTime syntax](http://php.net/manual/en/datetime.formats.relative.php) (default: `null` - a query matching any start date)
|
||||
- `end` - setting the end date for the query, formatted with the [PHP DateTime syntax](http://php.net/manual/en/datetime.formats.relative.php) (default: `null` - a query matching any end date)
|
||||
- `color` - a color name, see all possible names in [theme settings](theme.md) (default: ``)
|
||||
- `icon` - an icon alias from [theme settings](theme.md) or any other icon from [Font Awesome 5](https://fontawesome.com/icons) (default: `null` - no icon)
|
||||
|
||||
## Dashboard sections
|
||||
|
||||
Within the dashboard all widgets are placed in sections (rows) like this:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
dashboard:
|
||||
user_duration:
|
||||
title: dashboard.you
|
||||
order: 10
|
||||
permission: ROLE_USER
|
||||
widgets: [userDurationToday, userDurationWeek, userDurationMonth, userDurationYear, userDurationTotal]
|
||||
```
|
||||
|
||||
### Section settings
|
||||
|
||||
- `permission` - the name of a role who is allowed to see the widgets, see [users](users.md)
|
||||
- `title` - the title of a section, if omitted no title will be shown (default: `null`)
|
||||
- `widgets` - an array of widget names (see above for an example)
|
||||
- `order` - allows to define the order of the section
|
||||
|
||||
### Default sections
|
||||
|
||||
The dashboard has the following default sections:
|
||||
|
||||
- `user_duration` - order 10
|
||||
- `user_rates` - order 20
|
||||
- `duration` - order 30
|
||||
- `active_users` - order 40
|
||||
- `rates` - order 50
|
||||
- `admin` - order 100 (this section is programmatically added)
|
||||
|
||||
### Overwriting sections
|
||||
|
||||
A section with an empty list of widgets will not be rendered.
|
||||
If you don't like the default sections you can remove them by overwriting their widget list like this:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
dashboard:
|
||||
user_duration: { widgets: [] }
|
||||
user_rates: { widgets: [] }
|
||||
duration: { widgets: [] }
|
||||
active_users: { widgets: [] }
|
||||
rates: { widgets: [] }
|
||||
```
|
||||
|
||||
It's also possible to change the title or the list of widgets for every section like this:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
dashboard:
|
||||
user_duration:
|
||||
title: 'some fancy widgets'
|
||||
widgets: [userDurationWeek, userDurationMonth, userDurationYear]
|
||||
```
|
||||
|
||||
### Reorder sections
|
||||
|
||||
If you want to reorder the sections, you can overwrite as many sections as you want and simply change their `order` key.
|
||||
Lower numbers will be rendered before higher numbers.
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
dashboard:
|
||||
user_duration: { order: 30 }
|
||||
user_rates: { order: 90 }
|
||||
duration: { order: 40 }
|
||||
active_users: { order: 20 }
|
||||
rates: { order: 50 }
|
||||
```
|
||||
|
||||
### Test widgets for the "brave users"
|
||||
|
||||
While working on the widgets, some of them were created for testing future functionalities of Kimai.
|
||||
You can try them out, but I can't guarantee that they will be supported in the future, as I don't consider them to be `stable` for now.
|
||||
|
||||
You can try this configuration in your `local.yaml` to see a chart instead of plain boxes for the last 2 years of monthly times:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
widgets:
|
||||
userRecapTwoYears: { title: stats.durationToday, query: monthly, user: true, begin: '01 january last year 00:00:00', end: '31 december this year 23:59:59', color: '#3b8bba|rgba(0,115,183,0.6);#c1c7d1|rgb(210,214,222,0.9)' }
|
||||
|
||||
dashboard:
|
||||
user_duration:
|
||||
type: chart
|
||||
widgets: [userRecapTwoYears, userDurationToday, userDurationWeek, userDurationMonth, userDurationYear]
|
||||
```
|
||||
|
||||
A brief description: the `monthly` query allows to fetch data by month and year, but the default widgets are not able to render this data.
|
||||
So internally a __chart section template__ (`type: chart`) is used to render the data, which is also able to fetch and display the data for
|
||||
all of the following widgets in the configured section (the above example overwrites the widget config of the default `user_duration` section).
|
||||
|
||||
In order to work, the chart widget `userRecapTwoYears` needs to be the first in the section.
|
||||
|
||||
This widgets setup and configuration will likely change in the future, so keep an eye on this config if this widget
|
||||
doesn't work after one of the next updates!
|
||||
@@ -1,245 +0,0 @@
|
||||
# Developers
|
||||
|
||||
This page is dedicated to all developers who want to contribute to Kimai. You are the best!
|
||||
|
||||
# Setting up your environment
|
||||
|
||||
All you need is:
|
||||
- PHP >= 7.1.3
|
||||
- PHP extensions: `PDO-SQLite`, `intl`, `zip`, `gd`, `mbstring`, `xml`
|
||||
|
||||
You can install php 7.2 and all dependencies on debian based linux with this command:
|
||||
```
|
||||
apt install php7.2 php7.2-sqlite3 php7.2-intl php7.2-zip php7.2-gd php7.2-mbstring php7.2-xml
|
||||
```
|
||||
|
||||
Optional requirement:
|
||||
- a MySQL/MariaDB instance
|
||||
- PHP extension: `PDO-MySQL` enabled
|
||||
|
||||
Read how to [install Kimai v2 in your dev environment](installation.md).
|
||||
|
||||
## Frontend dependencies
|
||||
|
||||
If you want to make changes to CSS / Javascript, you need:
|
||||
|
||||
- [NodeJS](https://www.npmjs.com/)
|
||||
- [Yarn Package Manager](https://yarnpkg.com/en/)
|
||||
- [Webpack](https://webpack.js.org/)
|
||||
- [Webpack Encore](https://github.com/symfony/webpack-encore)
|
||||
|
||||
Please [install Yarn for your OS](https://yarnpkg.com/lang/en/docs/install/) and then:
|
||||
|
||||
```bash
|
||||
yarn install
|
||||
```
|
||||
|
||||
To rebuild all assets you have to execute:
|
||||
```bash
|
||||
yarn run prod
|
||||
```
|
||||
|
||||
You can find more information at:
|
||||
|
||||
- https://symfony.com/doc/current/frontend/encore/installation.html
|
||||
- https://symfony.com/doc/current/frontend.html
|
||||
|
||||
### Rebuilding assets for use in a subdirectory
|
||||
|
||||
If you want to run Kimai in a subdirectory, you have to rebuild the frontend assets with a different webpack configuration.
|
||||
Edit the file [webpack.config.js](../../webpack.config.js) and change `.setPublicPath('/build/')` to your needs.
|
||||
After that re-compile the assets (see above).
|
||||
|
||||
## Running Unit tests
|
||||
|
||||
You can run unit and integration tests with built-in commands like that:
|
||||
|
||||
```bash
|
||||
bin/console kimai:test-unit
|
||||
bin/console kimai:test-integration
|
||||
```
|
||||
|
||||
Or you simply run all tests with:
|
||||
```bash
|
||||
bin/phpunit
|
||||
```
|
||||
|
||||
## Check your code styles
|
||||
|
||||
You can run the code sniffer with a built-in command like that:
|
||||
|
||||
```bash
|
||||
bin/console kimai:phpcs
|
||||
```
|
||||
|
||||
You can also automatically fix the violations by running:
|
||||
|
||||
```bash
|
||||
bin/console kimai:phpcs --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.
|
||||
|
||||
Our code-styles are configured in [.php_cs.dist](../../.php_cs.dist).
|
||||
|
||||
## Translations
|
||||
|
||||
Read more about [languages and translations](translations.md).
|
||||
|
||||
## Extending the navigation bar
|
||||
|
||||
If you want to add your own entries in the navigation bar, you can subscribe to these events:
|
||||
|
||||
- `App\Event\ConfigureMainMenuEvent::CONFIGURE`
|
||||
- `App\Event\ConfigureAdminMenuEvent::CONFIGURE`
|
||||
|
||||
And that's how to use it:
|
||||
|
||||
```php
|
||||
use App\Event\ConfigureMainMenuEvent;
|
||||
use App\Event\ConfigureAdminMenuEvent;
|
||||
use Avanzu\AdminThemeBundle\Model\MenuItemModel;
|
||||
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
|
||||
|
||||
class MyMenuSubscriber implements EventSubscriberInterface
|
||||
{
|
||||
public static function getSubscribedEvents(): array
|
||||
{
|
||||
return [
|
||||
ConfigureMainMenuEvent::CONFIGURE => ['onMainMenuConfigure', 100],
|
||||
ConfigureAdminMenuEvent::CONFIGURE => ['onAdminMenuConfigure', 100],
|
||||
];
|
||||
}
|
||||
|
||||
public function onMainMenuConfigure(ConfigureMainMenuEvent $event)
|
||||
{
|
||||
$event->getMenu()->addItem(
|
||||
new MenuItemModel('timesheet', 'menu.timesheet', 'timesheet', [], 'fa fa-clock-o')
|
||||
);
|
||||
}
|
||||
|
||||
public function onAdminMenuConfigure(ConfigureAdminMenuEvent $event)
|
||||
{
|
||||
$event->getAdminMenu()->addChild(
|
||||
new MenuItemModel('timesheet_admin', 'menu.admin_timesheet', 'admin_timesheet', [], 'fa fa-clock-o')
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
For more details check the [official menu subscriber](../../src/EventSubscriber/MenuSubscriber.php).
|
||||
|
||||
## Extending the dashboard with widgets
|
||||
|
||||
If you want to add your own widget rows to the dashboard, you can subscribe to the event:
|
||||
|
||||
- `App\Event\DashboardEvent::DASHBOARD`
|
||||
|
||||
And that's how to use it:
|
||||
|
||||
```php
|
||||
use App\Event\DashboardEvent;
|
||||
use App\Model\DashboardSection;
|
||||
use App\Model\Widget;
|
||||
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
|
||||
|
||||
class MyDashboardSubscriber implements EventSubscriberInterface
|
||||
{
|
||||
public static function getSubscribedEvents(): array
|
||||
{
|
||||
return [DashboardEvent::DASHBOARD => ['onDashboardEvent', 200]];
|
||||
}
|
||||
|
||||
public function onDashboardEvent(DashboardEvent $event)
|
||||
{
|
||||
$section = new DashboardSection('optional.row.title');
|
||||
$widget = new Widget('A title', 100);
|
||||
$widget
|
||||
->setIcon('duration')
|
||||
->setColor('purple')
|
||||
->setType(Widget::TYPE_COUNTER)
|
||||
;
|
||||
$section->addWidget($widget);
|
||||
$event->addSection($section);
|
||||
}
|
||||
}
|
||||
```
|
||||
For more details check this [dashboard subscriber](../../src/EventSubscriber/DashboardSubscriber.php).
|
||||
|
||||
## Adding tabs to the "control sidebar"
|
||||
|
||||
We use the AdminLTE bundle to render the control sidebar tabs, so adding another tab is as easy as adding a new config entry:
|
||||
|
||||
```yaml
|
||||
admin_lte:
|
||||
options:
|
||||
control_sidebar:
|
||||
# these are the "official" Kimai tabs
|
||||
settings:
|
||||
icon: "fas fa-cogs"
|
||||
controller: 'App\Controller\SidebarController::settingsAction'
|
||||
home:
|
||||
icon: "fas fa-question-circle"
|
||||
template: sidebar/home.html.twig
|
||||
```
|
||||
|
||||
You have to define the `icon` ([read more](theme.md)) to be used and then either `controller` action or twig `template`.
|
||||
Both follow the default naming syntax and you can link your bundle here instead of existing application controller or templates.
|
||||
You should NOT add them in `config/packages/kimai.yaml` but in your own bundle or the `local.yaml` [config](configurations.md),
|
||||
otherwise they might get lost during an update.
|
||||
|
||||
## Adding documents for invoice rendering
|
||||
|
||||
In the config `kimai.invoice.documents`, you can add a list of directories with the locations of your invoice document templates ([read more](invoices.md)).
|
||||
|
||||
## Adding invoice calculator
|
||||
|
||||
An invoice calculator is a class implementing `App\Invoice\CalculatorInterface` and it is responsible for calculating
|
||||
invoice rates, taxes and taking care of all timesheet entries that should be displayed.
|
||||
|
||||
Every invoice calculator class will be automatically available when refreshing the application cache by the [InvoiceServiceCompilerPass](../../src/DependencyInjection/Compiler/InvoiceServiceCompilerPass.php):
|
||||
|
||||
The ID of the calculator must be unique, please prefix it with your vendor or bundle name and make sure it only contains
|
||||
character as it will be stored in a database column.
|
||||
|
||||
Translations are stored in the `invoice-calculator.xx.xliff`.
|
||||
|
||||
## Adding invoice-number generator
|
||||
|
||||
An invoice-number generator is a class implementing `App\Invoice\NumberGeneratorInterface` and its only task is to generate
|
||||
a number for the invoice. In most cases you do not want to mix multiple invoice-number generators throughout your invoices.
|
||||
|
||||
Every invoice number-generator class will be automatically available up when refreshing the application cache by the [InvoiceServiceCompilerPass](../../src/DependencyInjection/Compiler/InvoiceServiceCompilerPass.php):
|
||||
|
||||
The ID of the number generator must be unique, please prefix it with your vendor or bundle name and make sure it only contains
|
||||
character as it will be stored in a database column.
|
||||
|
||||
Translations are stored in the `invoice-numbergenerator.xx.xliff`.
|
||||
|
||||
## Adding invoice renderer
|
||||
|
||||
An invoice renderer is a class implementing `App\Invoice\RendererInterface` and it is responsible to convert an `InvoiceModel` (the actual data)
|
||||
with the use of an `InvoiceDocument` (the template file) into a downloadable/printable document.
|
||||
|
||||
Every invoice renderer class will be automatically available when refreshing the application cache by the [InvoiceServiceCompilerPass](../../src/DependencyInjection/Compiler/InvoiceServiceCompilerPass.php):
|
||||
|
||||
## Adding export renderer
|
||||
|
||||
An export renderer is a class implementing `App\Export\RendererInterface` and it is responsible to convert ar array of `Timesheet` objects
|
||||
into a downloadable/printable document.
|
||||
|
||||
Every export renderer class will be automatically available when refreshing the application cache by the [ExportServiceCompilerPass](../../src/DependencyInjection/Compiler/ExportServiceCompilerPass.php):
|
||||
|
||||
## Adding timesheet calculator
|
||||
|
||||
A timesheet calculator will be called on stopped timesheet records. It can rewrite all values but will normally take care
|
||||
of the columns `begin`, `end`, `duration` and `rate` but could also be used to apply a default `description`.
|
||||
|
||||
Timesheet calculator need to implement the interface `App\Timesheet\CalculatorInterface` and will be automatically tagged
|
||||
as `timesheet.calculator` in the service container. They will be found and used *only* if you add them to the service container.
|
||||
|
||||
You can apply several rules in the config file [kimai.yaml](../../config/packages/kimai.yaml) for the existing
|
||||
`DurationCalculator` and `RateCalculator` implementations. Please read the [configurations chapter](configurations.md) to find out more.
|
||||
|
||||
The configuration for "rounding rules" can be fetched from the container parameter `kimai.timesheet.rounding`.
|
||||
|
||||
The configuration for "hourly-rates multiplication factors" can be fetched from the container parameter `kimai.timesheet.rates`.
|
||||
@@ -1,23 +0,0 @@
|
||||
# REST API
|
||||
|
||||
Read the Swagger documentation of the Kimai 2 API in your Kimai installation at `/api/doc`.
|
||||
|
||||
Or you can export the JSON collection by visiting `/api/doc.json`. Store the result in a file, which can be imported with Postman.
|
||||
|
||||
## Authentication
|
||||
|
||||
When calling the API you have to submit two additional header with every call for authentication:
|
||||
|
||||
- `X-AUTH-USER` - holds the username or email
|
||||
- `X-AUTH-TOKEN` - holds the users API password, which he can set in his profile
|
||||
|
||||
Please make sure to ONLY call the Kimai 2 API via `https` to protect the users data!
|
||||
|
||||
## Calling the API with Javascript
|
||||
|
||||
If you develop your own extension and need to use the API for logged-in user, then you have to set the header `X-AUTH-SESSION`
|
||||
which will allow Kimai to use the current user session and not look for the default token based API authentication.
|
||||
|
||||
### Next step
|
||||
|
||||
Back to the [developer documentation](developers.md).
|
||||
@@ -1,85 +0,0 @@
|
||||
# Docker
|
||||
|
||||
The Dockerfile supplied with this application is development or demonstration docker. It runs a self contained version of kimai2 against a sqlite database in the docker container.
|
||||
|
||||
There is an official docker repo for the kimai app that includes the Docker file from this repo and a docker file suitable for running in a production environment.
|
||||
|
||||
* The docker repo: [https://github.com/tobybatch/kimai2](https://github.com/tobybatch/kimai2)
|
||||
* That repo on dockerhub auto-building the prod and dev conatiners: [https://hub.docker.com/r/kimai/kimai2](https://hub.docker.com/r/kimai/kimai2).
|
||||
|
||||
Any issues with the container rather than the application itself should be raised [here](https://github.com/tobybatch/kimai2/issues).
|
||||
|
||||
## Build the docker
|
||||
|
||||
docker build -t kimai/kimai2:dev .
|
||||
|
||||
|
||||
|
||||
## Run the docker
|
||||
|
||||
```
|
||||
docker run -ti -p 8001:8001 --name kimai2 --rm kimai/kimai2:dev
|
||||
```
|
||||
|
||||
You can then access the site on http://127.0.0.1:8001. If that doesn't work check the IP of your docker:
|
||||
|
||||
```
|
||||
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' kimai2
|
||||
```
|
||||
|
||||
You can find Kimai at that IP on port 8001.
|
||||
|
||||
### Mac using docker-machine
|
||||
|
||||
When using dock-machine on your Mac, you need to use the IP of your machine.
|
||||
Considering you started the machine named `default`, you find the IP with:
|
||||
|
||||
```
|
||||
docker-machine ip default
|
||||
```
|
||||
|
||||
## Running commands in the docker
|
||||
|
||||
You can run any command in the container in this fashion once it is started. Add `-ti` to attach a terminal.
|
||||
|
||||
```
|
||||
docker exec -ti kimai2 bash
|
||||
```
|
||||
|
||||
## Create a user and dummy data
|
||||
|
||||
See the docs [here](installation.md) for full instructions, but this creates a user admin/admin with all privileges.
|
||||
|
||||
```
|
||||
docker exec kimai2 bin/console kimai:create-user admin admin@example.com ROLE_SUPER_ADMIN admin
|
||||
```
|
||||
|
||||
To install the fixtures:
|
||||
|
||||
```
|
||||
docker exec kimai2 bin/console kimai:reset-dev
|
||||
```
|
||||
|
||||
## Developing against the docker
|
||||
|
||||
It is possible to mount your source tree and sqlite DB into the container at run time. **N.B. The sqlite database needs to writable by the www-data user.** Use ```chown 33:33 kimai.sqlite``` on the host machine.
|
||||
|
||||
```
|
||||
docker run --rm -d -p 8001:8001 \
|
||||
-v $(pwd)/src:/opt/kimai/src \
|
||||
-v $(pwd)/var/data/kimai.sqlite:/opt/kimai/var/data/kimai.sqlite \
|
||||
--name kimai2 kimai/kimai2:dev
|
||||
```
|
||||
|
||||
Now edits in the local file tree will be served by the container and database changes will persist.
|
||||
|
||||
See [The official docker documentation](https://docs.docker.com/) for more options on running the container.
|
||||
|
||||
## Further docker solutions
|
||||
|
||||
As there are several approaches to docker images, you have multiple docker images to choose from.
|
||||
They were built by the community, we do not support them - for question please ask in their repositories:
|
||||
|
||||
- [dysonspherelab](https://hub.docker.com/r/dysonsphere/kimai2/) (for more infos [read this issue](https://github.com/kevinpapst/kimai2/issues/284))
|
||||
- [felixhummel](https://github.com/felixhummel/kimai-in-docker/tree/kimai2)
|
||||
- [Haidy777](https://github.com/Haidy777/kimai2/blob/docker/Dockerfile) (for more infos [read this issue](https://github.com/kevinpapst/kimai2/pull/311))
|
||||
@@ -1,55 +0,0 @@
|
||||
# Emails
|
||||
|
||||
Kimai uses the [Swift MailerBundle](https://symfony.com/doc/current/email.html) for sending emails.
|
||||
Please read their documentation, there are a lot of possible [configuration settings](https://symfony.com/doc/current/reference/configuration/swiftmailer.html) that you might want to adapt to your needs.
|
||||
|
||||
If not otherwise noted, all emails will be sent instantly (unless spooling is activated in [swiftmailer.yaml](../../config/packages/swiftmailer.yaml)).
|
||||
|
||||
## Activating email
|
||||
|
||||
You have to adapt two settings in your `.env` [configuration file](configurations.md):
|
||||
|
||||
- `MAILER_URL` - your smtp connection details for sending emails
|
||||
- `MAILER_FROM` - an application wide "from" address for all emails
|
||||
|
||||
## All existing emails
|
||||
|
||||
The following emails will be sent by Kimai:
|
||||
|
||||
### Security related emails
|
||||
|
||||
If you want to change the content of the emails, please have a look at the [FOSUserBundle config](../../config/packages/fos_user.yaml)
|
||||
and its [documentation](https://symfony.com/doc/current/bundles/FOSUserBundle/emails.html).
|
||||
|
||||
- Password reset
|
||||
- Account approval (only if activated, see [User docu](users.md))
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
You can test your email configuration with the command `bin/console -vv swiftmailer:email:send`, which will ask you for all required fields:
|
||||
- `to`
|
||||
- `from`
|
||||
- `subject`
|
||||
- `body`
|
||||
|
||||
The email will be sent using the transport from your configured `MAILER_URL`.
|
||||
|
||||
### SMTP does not accept emails
|
||||
|
||||
If you have the following error in your logfile:
|
||||
```
|
||||
app.ERROR: Exception occurred while flushing email queue: Expected response code 354 but got code "503", with message "503-All RCPT commands were rejected with this error: 503-R1: HELO should be a FQDN or address literal (See RFC 2821 4.1.1.1) 503 Valid RCPT command must precede DATA " [] []
|
||||
```
|
||||
you might suffer from a wrong configuration (read the documentation linked above) and try a full featured SMTP URL with a dedicated user account for authentication:
|
||||
```
|
||||
MAILER_URL=smtp://username:password@mx.example.com:587?encryption=tls&auth_mode=plain
|
||||
```
|
||||
Password should not contain URL characters like '&@:', which can cause problems parsing the SMTP URL.
|
||||
If you have to use one of these characters, you need to adjust the swiftmailer configuration at `config/packages/swiftmailer.yaml`.
|
||||
|
||||
If that still doesn't help, try to set a `local_domain` in the file `config/packages/local.yaml`:
|
||||
```yaml
|
||||
swiftmailer:
|
||||
local_domain: 'kimai.local'
|
||||
```
|
||||
This `local_domain` will be used for the `HELO` command when SwiftMailer contacts your SMTP.
|
||||
@@ -1,20 +0,0 @@
|
||||
# Export
|
||||
|
||||
The export module allows you to export filtered timesheet data into several formats.
|
||||
|
||||
## Difference between export and invoice
|
||||
|
||||
There are a couple of differences in these two Kimai modules, the most important ones:
|
||||
|
||||
- Invoices can only be created for a dedicated customer, where export can be done without selecting a customer
|
||||
- Export state is saved with each timesheet record, so you can filter whether already exported items should be included or not
|
||||
- Invoices do more calculation (e.g. tax) and support export to self-created templates (e.g. XLSX, ODS, DOCX)
|
||||
- Invoices set duration to 1 in case of a fixed rate, export shows the real duration
|
||||
|
||||
## Security and privacy
|
||||
|
||||
The export extension does not check timesheet permissions, as this would defeat the purpose of an export.
|
||||
|
||||
Giving a user the permission to export data allows to basically see everything inside Kimai.
|
||||
So all customer, projects, activities, all hourly rates, the personal time worked, the money earned become visible!
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
# Frequently asked questions
|
||||
|
||||
## I have a problem
|
||||
|
||||
Please check your logfile at `var/log/prod.log`. Many problems reveal themselves after checking it.
|
||||
|
||||
If that doesn't help, open a new issue at [GitHub](https://github.com/kevinpapst/kimai2/issues/) and we try to find a solution.
|
||||
|
||||
## Changed configs/templates do not load
|
||||
|
||||
Kimai is built on top of Symfony, a framework that optimizes its speed by caching most files.
|
||||
Therefor, if you are running Kimai in `production`, you have to clear the cache before changes will show up:
|
||||
|
||||
```bash
|
||||
bin/console cache:clear
|
||||
```
|
||||
|
||||
See also the [configurations docs](configurations.md).
|
||||
|
||||
## I have only FTP available
|
||||
|
||||
So you want to install Kimai v2 but have no SSH access to your server?
|
||||
There is a workaround available, read the additional [installation instructions](installation.md).
|
||||
|
||||
## Error on bin/console doctrine:schema:create
|
||||
|
||||
If you get an error during the installation of the database schema that mentions `DC2Type:json_array`, e.g. like the following:
|
||||
|
||||
```
|
||||
In PDOConnection.php line 109:
|
||||
|
||||
SQLSTATE[42000]: Syntax error or access violation: 1064 You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'JSON
|
||||
NOT NULL COMMENT '(DC2Type:json_array)', UNIQUE INDEX UNIQ_B9AC5BCE5E237E06' at line 1
|
||||
```
|
||||
|
||||
Then the most likely case is that you are using a MariaDB database which is too old. You can find out which version is
|
||||
used by executing `mysql --version` or by checking the server information e.g. with PHPMyAdmin.
|
||||
|
||||
There is a [discussion in the issue tracker](https://github.com/kevinpapst/kimai2/issues/191) about this topic.
|
||||
|
||||
Further readings:
|
||||
|
||||
- [MariaDB - JSON support was added with 10.2.7](https://mariadb.com/kb/en/library/json-data-type/)
|
||||
- [Using JSON fields with Doctrine ORM on PostgreSQL & MySQL](https://symfony.fi/entry/using-json-fields-with-doctrine-orm-on-postgresql-mysql)
|
||||
|
||||
## Dotenv::populate() must be an instance of Symfony\\Component\\Dotenv\\void
|
||||
|
||||
If you encounter an error like this:
|
||||
|
||||
```
|
||||
PHP Fatal error: Uncaught TypeError: Return value of Symfony\\Component\\Dotenv\\Dotenv::populate() must be an instance of Symfony\\Component\\Dotenv\\void, none returned in /var/www/kimai2/vendor/symfony/dotenv/Dotenv.php:95
|
||||
Stack trace:
|
||||
#0 /var/www/kimai2/vendor/symfony/dotenv/Dotenv.php(57): Symfony\\Component\\Dotenv\\Dotenv->populate(Array)
|
||||
#1 /var/www//kimai2/public/index.php(15): Symfony\\Component\\Dotenv\\Dotenv->load('/var/www/html/k...')
|
||||
#2 {main}\n thrown in /var/www/kimai2/vendor/symfony/dotenv/Dotenv.php on line 95
|
||||
|
||||
```
|
||||
|
||||
you are running PHP 7.0. Probably you were able to install Kimai v2, because your PHP-CLI uses a different PHP version than your webserver.
|
||||
Upgrade PHP and the error will be gone.
|
||||
@@ -1,269 +0,0 @@
|
||||
# Installation
|
||||
|
||||
The recommended way to install Kimai v2 is via SSH, you need GIT and [Composer](https://getcomposer.org/doc/00-intro.md).
|
||||
|
||||
But there are further installation methods described:
|
||||
- [Development setup](#development-installation)
|
||||
- [Docker](#docker)
|
||||
- [1-click installations](#hosting-and-1-click-installations)
|
||||
- [FTP](#ftp-installation) (not supported)
|
||||
- Hints for [local single-user setup](#installation-on-a-personal-computer)
|
||||
|
||||
## Recommended setup
|
||||
|
||||
To install Kimai 2 in your production environment, connect with SSH to your server and change to your webserver root directory.
|
||||
You need to install Git and [Composer](https://getcomposer.org/doc/00-intro.md) if you haven't already.
|
||||
|
||||
First clone this repo:
|
||||
|
||||
```bash
|
||||
git clone -b 0.8 --depth 1 https://github.com/kevinpapst/kimai2.git
|
||||
cd kimai2/
|
||||
```
|
||||
|
||||
Make sure the [file permissions are correct](https://symfony.com/doc/current/setup/file_permissions.html) and create your `.env` file:
|
||||
```bash
|
||||
chown -R :www-data .
|
||||
chmod -R g+r .
|
||||
chmod -R g+rw var/
|
||||
cp .env.dist .env
|
||||
```
|
||||
|
||||
Configure the database connection string in your the `.env` file (Kimai v2 supports MySQL/MariaDB and SQLite):
|
||||
```
|
||||
# adjust all settings in .env to your needs
|
||||
APP_ENV=prod
|
||||
DATABASE_URL=mysql://user:password@127.0.0.1:3306/database
|
||||
```
|
||||
SQLite is not recommended for production usage, check FAQ below.
|
||||
|
||||
Now install all dependencies for Kimai 2:
|
||||
```bash
|
||||
sudo -u www-data composer install --no-dev --optimize-autoloader
|
||||
```
|
||||
If you see a `Malformed patameter "url"` error, see below in the FAQ.
|
||||
|
||||
Optionally create the database:
|
||||
```bash
|
||||
bin/console doctrine:database:create
|
||||
```
|
||||
|
||||
Create all schema tables:
|
||||
```bash
|
||||
bin/console doctrine:schema:create
|
||||
```
|
||||
You can safely ignore the message: *This operation should not be executed in a production environment*!
|
||||
|
||||
Make sure that upcoming updates can be correctly applied by setting the initial database version:
|
||||
```bash
|
||||
bin/console doctrine:migrations:version --add --all
|
||||
```
|
||||
|
||||
Warm up the cache (as webserver user):
|
||||
```bash
|
||||
sudo -u www-data bin/console cache:warmup --env=prod
|
||||
```
|
||||
|
||||
Create your first user with the following command. You will be asked to enter a password afterwards:
|
||||
```bash
|
||||
bin/console kimai:create-user username admin@example.com ROLE_SUPER_ADMIN
|
||||
```
|
||||
_Tip: You can skip the "create user" step, if you are going to [import data from Kimai v1](migration_v1.md)._
|
||||
|
||||
For available roles, please refer to the [user documentation](users.md).
|
||||
|
||||
> **NOTE**
|
||||
>
|
||||
> If you want to use a fully-featured web server (like Nginx or Apache) to run
|
||||
> Kimai, configure it to point its DocumentRoot at the `public/` directory.
|
||||
> For more details, see:
|
||||
> https://symfony.com/doc/current/setup/web_server_configuration.html
|
||||
|
||||
Installation complete: enjoy time-tracking :-)
|
||||
|
||||
## Docker
|
||||
|
||||
There is a dedicated about [our Docker setup](docker.md), which is primarily meant for use in development.
|
||||
|
||||
## Hosting and 1-click installations
|
||||
|
||||
These platforms adopted Kimai 2 to be compatible with their one-click installation systems:
|
||||
|
||||
### YunoHost
|
||||
|
||||
[](https://install-app.yunohost.org/?app=kimai2)
|
||||
|
||||
Kimai 2 [package](https://github.com/YunoHost-Apps/kimai2_ynh) for [YunoHost](https://yunohost.org).
|
||||
|
||||
## FTP installation
|
||||
|
||||
If you have no SSH access to your server (e.g. when you use a shared hosting package) then you need to install Kimai locally and upload it afterwards.
|
||||
|
||||
Before I start to explain how to apply this workaround let me briefly explain the problem:
|
||||
Kimai has no [web-based installer](https://github.com/kevinpapst/kimai2/issues/209) for now and you have to create the first user with a console command.
|
||||
It also does not come as pre-built ZIP file, so you have to install the dependencies manually.
|
||||
|
||||
These are the steps you have to perform:
|
||||
|
||||
```
|
||||
git clone https://github.com/kevinpapst/kimai2.git
|
||||
cd kimai2/
|
||||
```
|
||||
|
||||
Create the `.env` file (as copy from `.env.dist`), using the `prod` environment and SQLite as database:
|
||||
```
|
||||
# you need all settings from .env.dist, but these two need to be adjusted!
|
||||
APP_ENV=prod
|
||||
DATABASE_URL=sqlite:///%kernel.project_dir%/var/data/kimai.sqlite
|
||||
```
|
||||
The file `var/data/kimai.sqlite` will hold all your data, so make sure to include it in your backups!
|
||||
|
||||
Prepare the environment by installing all dependencies:
|
||||
|
||||
```bash
|
||||
composer install --no-dev
|
||||
```
|
||||
|
||||
Create the database schemas:
|
||||
```bash
|
||||
bin/console doctrine:schema:create
|
||||
bin/console doctrine:migrations:version --add --all
|
||||
```
|
||||
|
||||
And create your first user with the following command. You will be asked to enter a password afterwards.
|
||||
|
||||
```bash
|
||||
bin/console kimai:create-user username admin@example.com ROLE_SUPER_ADMIN
|
||||
```
|
||||
|
||||
Now you can upload the `kimai2/` directory to your hosting environment and point your domain (document root) to `kimai2/public/`.
|
||||
|
||||
## Development installation
|
||||
|
||||
Clone the repository and install all dependencies:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/kevinpapst/kimai2.git
|
||||
cd kimai2/
|
||||
composer install
|
||||
```
|
||||
|
||||
The default installation uses a SQLite database, so there is no need to create a database for your first tests.
|
||||
Our default settings will work out-of-the-box, but you might want to adjust the `.env` values to your needs.
|
||||
You can configure your database in your `.env` file, e.g.:
|
||||
```
|
||||
DATABASE_PREFIX=kimai2_
|
||||
DATABASE_URL=sqlite:///%kernel.project_dir%/var/data/kimai.sqlite
|
||||
APP_ENV=dev
|
||||
```
|
||||
|
||||
The next commands will create the database and the schema:
|
||||
```bash
|
||||
bin/console doctrine:database:create
|
||||
bin/console doctrine:schema:create
|
||||
```
|
||||
|
||||
Lets bootstrap your environment by executing this command (which is only available in dev environment):
|
||||
```bash
|
||||
bin/console kimai:reset-dev
|
||||
```
|
||||
|
||||
You just imported demo data, to test the application in its full beauty and with several different user accounts and permission sets.
|
||||
|
||||
You can now login with these accounts:
|
||||
|
||||
| Username | Password | API Key | Role |
|
||||
|---|:---:|:---:|---|
|
||||
| clara_customer| kitten | api_kitten |Customer |
|
||||
| john_user| kitten | api_kitten |User |
|
||||
| chris_user| kitten | api_kitten |User (deactivated) |
|
||||
| tony_teamlead| kitten | api_kitten |Teamlead |
|
||||
| anna_admin| kitten | api_kitten |Administrator |
|
||||
| susan_super| kitten | api_kitten |Super-Administrator |
|
||||
|
||||
Demo data can always be deleted by dropping the schema and re-creating it.
|
||||
The `kimai:reset-dev` command can always be executed later on to reset your dev database and cache.
|
||||
|
||||
ATTENTION - if you don't want the test data, then erase it and create a empty schema:
|
||||
|
||||
```bash
|
||||
bin/console doctrine:schema:drop --force
|
||||
bin/console doctrine:schema:create
|
||||
```
|
||||
|
||||
There is no need to configure a virtual host in your web server to access the application for testing.
|
||||
Just use the built-in web server for your first tests:
|
||||
|
||||
```bash
|
||||
bin/console server:run
|
||||
```
|
||||
|
||||
This command will start a web server for Kimai. Now you can access the application in your browser at <http://127.0.0.1:8000/>.
|
||||
You can stop the built-in web server by pressing `Ctrl + C` while you're in the terminal.
|
||||
|
||||
To re-generate the frontend assets ([more information here](var/docs/developers.md)), execute:
|
||||
```bash
|
||||
yarn install
|
||||
npm run prod
|
||||
```
|
||||
|
||||
## FAQ and common problems
|
||||
|
||||
## SQLite not recommended for production usage
|
||||
|
||||
SQLite is a great database engine for testing, but when it comes to production usage it is imperfect due to several reasons:
|
||||
|
||||
- It does not support ALTER TABLE commands and makes update procedures very clunky and problematic (we still try to support updates, but they are heavy on large databases)
|
||||
- It does [not support FOREIGN KEY](https://www.sqlite.org/quirks.html#foreign_key_enforcement_is_off_by_default) constraints [out of the box](https://www.sqlite.org/foreignkeys.html#fk_enable), which can lead to critical bugs when deleting users/activities/projects/customers
|
||||
|
||||
Kimai works around the Foreign Keys issue by using a [Doctrine PostConnect EventSubscriber]({{ site.kimai_v2_file }}/src/Doctrine/SqliteSessionInitSubscriber.php) since v0.8.1,
|
||||
but it is not guaranteed that SQLite handles everything as expected.
|
||||
|
||||
### Malformed parameter "url"
|
||||
|
||||
If you see an error message like this, then you have a special character in your DATABASE_URL.
|
||||
```
|
||||
!!
|
||||
!! In DriverManager.php line 259:
|
||||
!!
|
||||
!! Malformed parameter "url".
|
||||
!!
|
||||
```
|
||||
This can be a character like `@` or `/` or some others, which need to be urlencoded.
|
||||
This can easily be done with one command, lets assume your password is `mG0/d1@3aT.Z)s` then you get your password like this:
|
||||
```
|
||||
$ php -r "echo urlencode('mG0/d1@3aT.Z)s');"
|
||||
mG0%2Fd1%403aT.Z%29s
|
||||
```
|
||||
|
||||
### Which user to use - no need to use www-data user?!
|
||||
|
||||
The installation instructions are intended primarily for server applications.
|
||||
|
||||
If you are installing Kimai 2 on your personal computer - maybe for use in a local network, but where the computer primarily
|
||||
serves as a single user computer - you will avoid permission errors by substituting `www-data` in the relevant commands with your username.
|
||||
|
||||
In particular, `sudo -u www-data` is a command which grants the `www-data` user temporary administrator/super-user privileges).
|
||||
However, depending on the configuration of your particular computer, you may be able to avoid sudo altogether (your user
|
||||
may already have adequate permissions).
|
||||
|
||||
You can try first leaving `sudo -u www-data` altogether in the relevant commands.
|
||||
If you have permission errors, you can substitute it for `sudo -u $USER` in the relevant commands (where username is the
|
||||
username that runs the server - if you don't know, it is likely your own username that you login with).
|
||||
|
||||
### chown & chmod commands
|
||||
|
||||
Further, `chown` and `chmod` commands should be for the username that runs the server instead of `www-data` (again, if you
|
||||
don't know, it is likely your own username).
|
||||
|
||||
Also note that, depending on where you are installing Kimai 2 and how your computer is configured, you may also receive
|
||||
"operation not permitted" errors when setting file permissions (chown and chmod commands).
|
||||
In that case, prefix them with `sudo`.
|
||||
|
||||
### Still doesn't work?
|
||||
|
||||
These infos were added to give you some possible guidance if you run into troubles. The Linux (and Mac) filesystem
|
||||
with its permission structure, especially when using server software, can be tricky and challenging.
|
||||
|
||||
But this has NOTHING to do with Kimai and we might not be able to help you in such situations ... it is your system and
|
||||
responsibility, be aware that wrong permissions might break Kimai and can also lead to security problems.
|
||||
@@ -1,17 +0,0 @@
|
||||
# Internal
|
||||
|
||||
Internal documentation for project maintainers
|
||||
|
||||
## Create a release
|
||||
|
||||
- Prepare a GitHub release-draft
|
||||
- Change .github_changelog_generator config accordingly to new release tag (increase future release)
|
||||
- Change version constants in `src/Constants.php`
|
||||
- Adjust the file `UPGRADING.md` with version specific information
|
||||
- Change version string in git command in `UPGRADING.md` and `var/docs/installation.md`
|
||||
- Create CHANGELOG.md with [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator]) by running `github_changelog_generator kevinpapst/kimai2`
|
||||
- Edit the release-draft and add the "Full changelog" link + everything from CHANGELOG.md related to the new version
|
||||
- Push a release branch and merge it as last PR into master
|
||||
- Create the release
|
||||
- Post a new issue at [YunoHost tracker for Kimai 2](https://github.com/YunoHost-Apps/kimai2_ynh)
|
||||
- Post a new issue at [Docker for Kimai 2](https://github.com/tobybatch/kimai2)
|
||||
@@ -1,223 +0,0 @@
|
||||
# Invoices
|
||||
|
||||
You can export your timesheet data to invoices in several formats.
|
||||
|
||||
## Invoice document
|
||||
|
||||
The invoice system currently supports the following formats:
|
||||
|
||||
- `HTML`
|
||||
- through the use of Twig templates
|
||||
- filename must end with `.html.twig`
|
||||
- Pros: no need for additional software, print or convert to PDF from your browser (if supported)
|
||||
- `DOCX`
|
||||
- OOXML - Open Office XML Text
|
||||
- Microsoft Word 2007-2013 XML
|
||||
- filename must end with `.docx`
|
||||
- Pros: simple customization and possibility to edit the invoice later on
|
||||
- our recommended invoice document format
|
||||
- `CSV`
|
||||
- Comma-separated file with UTF-8 encoding and double-quotes around each field
|
||||
- filename must end with `.csv`
|
||||
- Pros: good for exporting and creating enhanced reports with an office software package
|
||||
- our recommended export format
|
||||
- `XLSX`
|
||||
- Microsoft Excel™ 2007 shipped with a new file format, namely Microsoft Office Open XML SpreadsheetML, and Excel 2010 extended this still further with new features.
|
||||
- file extension: filename must end with `.xlsx`
|
||||
- PRO: good for exporting, creating enhanced reports with an office software package
|
||||
- `ODS`
|
||||
- Open Document Spreadsheet or OASIS, is the OpenOffice.org XML file format for spreadsheets supported by OpenOffice, LibreOffice, StarCalc, Microsoft and others
|
||||
- file extension: filename must end with `.ods`
|
||||
- Pros: open format - good for exporting, creating enhanced reports with an office software package
|
||||
- our recommended spreadsheet format
|
||||
|
||||
**Be aware**: the default templates were created and tested ONLY with LibreOffice!
|
||||
|
||||
## Create your own invoice document
|
||||
|
||||
Invoice documents are searched in two locations:
|
||||
|
||||
- `templates/invoice/renderer/`
|
||||
- `var/invoices/`
|
||||
|
||||
Be aware of the following rules:
|
||||
|
||||
- Documents are addressed by their filename without extension (e.g. `kimai.html.twig` results in `kimai`)
|
||||
- You can use every document name only once: so using `kimai.html.twig` and `kimai.docx` is not possible
|
||||
- The first file to be found takes precedence
|
||||
- Kimai looks first in `var/invoices/`, so you can overwrite default templates
|
||||
- You should store your templates in `var/invoices/` as this directory is not shipped with Kimai and not touched during updates
|
||||
- You can configure different search directories through the config key `kimai.invoice.documents` if you want to
|
||||
- hide the default templates
|
||||
- add additional template source directories
|
||||
- see below in `Configure search path` to find out how
|
||||
- After you created a new or updated an existing template, you might have to clear the cache with `bin/console cache:clear` to see the results
|
||||
|
||||
### Twig templates
|
||||
|
||||
If you are looking for a way to set the advanced contact data, see below in _Configure contact data_.
|
||||
|
||||
Generally speaking, you should use only the variable `model` in your template which is an instance of `App\Model\InvoiceModel`.
|
||||
|
||||
Please see the [default templates](https://github.com/kevinpapst/kimai2/tree/master/templates/invoice/renderer) at
|
||||
GitHub to find out which variables can be used or debug it with:
|
||||
|
||||
```twig
|
||||
{{ dump(model) }}
|
||||
```
|
||||
|
||||
The `dump()` method is only available in `dev` environment, check your `.env` if you are unsure.
|
||||
|
||||
If you want more examples of the available methods for a timesheet record, you can have a look in the other existing templates,
|
||||
like [the template which renders the "My times" page](https://github.com/kevinpapst/kimai2/tree/master/templates/timesheet/index.html.twig).
|
||||
|
||||
### Docx templates
|
||||
|
||||
Docx templates are powered by [PHPWord](https://github.com/PHPOffice/PHPWord) and its `TemplateProcessor`.
|
||||
|
||||
**Important:** You have to add one of the variables - either `${entry.description}` or `${entry.row}` - in one table row,
|
||||
otherwise the rendering process will fail! The row containing this variable will be cloned for every included timesheet record.
|
||||
|
||||
If you do not use `${entry.description}` then a fallback for `${entry.row}` is used and will be removed in the rendering process,
|
||||
it will not show up in the generated invoice.
|
||||
|
||||
See below in `Template variables` to find out which variables you can use in your template.
|
||||
|
||||
Find out more about PHPWord templates [here](https://phpword.readthedocs.io/en/latest/templates-processing.html).
|
||||
|
||||
### Spreadsheets (ODS, XLSX and CSV)
|
||||
|
||||
Spreadsheet templates are powered by [PhpSpreadsheet](https://github.com/PHPOffice/PhpSpreadsheet).
|
||||
|
||||
**Important:** within the first 100 rows you MUST-HAVE the template row for timesheet entries, which means there must be
|
||||
a value starting with `${entry.` in one of the first 10 columns, otherwise no timesheet records will be rendered!
|
||||
|
||||
_Check the default templates if that doesn't make sense to you ;-)_
|
||||
|
||||
This row will then be cloned for every timesheet entry.
|
||||
|
||||
See below in `Template variables` to find out which variables you can use in your CSV file.
|
||||
|
||||
## Template variables
|
||||
|
||||
Be aware, that the following list of variables is only working for the "document" based formats, but NOT for twig templates.
|
||||
Twig templates are rendered actively, it is up to the developer to calculate what is needed.
|
||||
|
||||
### Global variables
|
||||
|
||||
The documents which are rendered passively (ODS, XLSX, CSV, DOCX) can use the following global variables:
|
||||
|
||||
| Key | Description |
|
||||
|---|---|
|
||||
| ${invoice.due_date} | The due date for the invoice payment |
|
||||
| ${invoice.date} | The creation date of this invoice |
|
||||
| ${invoice.number} | The generated invoice number |
|
||||
| ${invoice.currency} | The invoice currency |
|
||||
| ${invoice.total_time} | The total working time (entries with a fixed rate are always calculated with 1) |
|
||||
| ${invoice.total} | The invoices total (including tax) |
|
||||
| ${invoice.subtotal} | The invoices subtotal (excluding tax) |
|
||||
| ${invoice.currency} | The invoices currency as string (like EUR or USD) |
|
||||
| ${invoice.vat} | The VAT in percent for this invoice |
|
||||
| ${invoice.tax} | The tax of the invoice amount |
|
||||
| ${template.name} | The invoice name, as configured in your template |
|
||||
| ${template.company} | The company name, as configured in your template |
|
||||
| ${template.address} | The invoicing address, as configured in your template |
|
||||
| ${template.title} | The invoice title, as configured in your template |
|
||||
| ${template.payment_terms} | Your payment terms, usage might differ from template to template |
|
||||
| ${template.due_days} | The amount of days for the payment, starting with the day of creating the invoice |
|
||||
| ${query.begin} | The query begin as formatted short date |
|
||||
| ${query.end} | The query end as formatted short date |
|
||||
| ${query.month} | The month for this query (begin date) |
|
||||
| ${query.year} | The year for this query (begin date) |
|
||||
|
||||
If a customer was selected the following values exist as well:
|
||||
|
||||
| Key | Description |
|
||||
|---|---|
|
||||
| ${customer.id} | The customer ID |
|
||||
| ${customer.address} | The customer address |
|
||||
| ${customer.name} | The customer name |
|
||||
| ${customer.contact} | The customer contact |
|
||||
| ${customer.company} | The customer company |
|
||||
| ${customer.number} | The customer number |
|
||||
| ${customer.country} | The customer country |
|
||||
| ${customer.homepage} | The customer homepage |
|
||||
| ${customer.comment} | The customer comment |
|
||||
|
||||
If a project was selected the following values exist as well:
|
||||
|
||||
| Key | Description |
|
||||
|---|---|
|
||||
| ${project.id} | The project ID |
|
||||
| ${project.name} | The project name |
|
||||
| ${project.comment} | The project name |
|
||||
| ${project.order_number} | The project order number |
|
||||
|
||||
### Timesheet entry variables
|
||||
|
||||
For each timesheet entry you can use the variables from the following table.
|
||||
|
||||
| Key | Description | Example |
|
||||
|---|---|---|
|
||||
| ${entry.row} | An empty string, used as template row for docx | |
|
||||
| ${entry.description} | The entries description | _foo bar_ |
|
||||
| ${entry.amount} | The format duration/amount for this entry | 02:47 h |
|
||||
| ${entry.rate} | The rate for one unit of the entry (normally one hour) | 100 |
|
||||
| ${entry.total} | The total rate for this entry | 278,33 |
|
||||
| ${entry.currency} | The currency for this record as string (like EUR or USD) | EUR |
|
||||
| ${entry.duration} | The duration in seconds | 10020 |
|
||||
| ${entry.duration_minutes} | The duration in minutes with no decimals | 167 |
|
||||
| ${entry.begin} | The begin date (format depends on the users language) | 27.10.2018 |
|
||||
| ${entry.begin_time} | The formatted time for the begin of this entry | 14:57 |
|
||||
| ${entry.begin_timestamp} | The timestamp for the begin of this entry | 1542016273 |
|
||||
| ${entry.end} | The begin date (format depends on the users language) | 27.10.2018 |
|
||||
| ${entry.end_time} | The formatted time for the end of this entry | 17:44 |
|
||||
| ${entry.end_timestamp} | The timestamp for the end of this entry | 1542016273 |
|
||||
| ${entry.date} | The start date when this record was created | 27.10.2018 |
|
||||
| ${entry.user_id} | The user ID | 1 |
|
||||
| ${entry.user_name} | The username | susan_super |
|
||||
| ${entry.user_alias} | The user alias | Susan Miller |
|
||||
| ${entry.activity} | Activity name | Post production |
|
||||
| ${entry.activity_id} | Activity ID | 124 |
|
||||
| ${entry.project} | Project name | Nemesis |
|
||||
| ${entry.project_id} | Project ID | 10 |
|
||||
| ${entry.customer} | Customer name | Acme Studios |
|
||||
| ${entry.customer_id} | Customer ID | 3 |
|
||||
|
||||
## Configure search path
|
||||
|
||||
An example config `config/packages/local.yaml` file might look like this:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
invoice:
|
||||
documents:
|
||||
- 'var/invoices/'
|
||||
```
|
||||
|
||||
This would disable the default documents, as Kimai will onl look in the directory `var/invoices/` for files.
|
||||
|
||||
## Configure contact data
|
||||
|
||||
Some HTML invoice templates need additional data, that can't be edited through the UI.
|
||||
These values should be added to your `local.yaml`:
|
||||
```yaml
|
||||
twig:
|
||||
globals:
|
||||
company:
|
||||
name: 'Kimai Inc.',
|
||||
homepage: 'www.kimai.org',
|
||||
email: 'kimai@example.com',
|
||||
phone: '0123-4567890',
|
||||
tax_number: 'YourTaxNumber',
|
||||
signature: '/build/images/signature.png',
|
||||
address: 'Kimai Inc.
|
||||
Example road 42
|
||||
D – 12345 City
|
||||
',
|
||||
bank_account: '
|
||||
Kimai Inc.
|
||||
IBAN: DE00 0000 0000 0000 0000 00
|
||||
BIC: XXXXXXXX (a bank name)
|
||||
'
|
||||
```
|
||||
@@ -1,29 +0,0 @@
|
||||
# Importing data from Kimai v1
|
||||
|
||||
Before importing your data from a Kimai v1 installation, please read the following carefully:
|
||||
|
||||
- Data from the existing v1 installation is only read and will never be changed
|
||||
- Data can only be imported from a Kimai installation with at least `v1.0.1` and database revision `1388` (check your `configuration` table)
|
||||
- User-specific rates are not yet supported in Kimai 2
|
||||
- fixed-rates and hourly-rates for projects and activities are imported
|
||||
- fixed-rates and hourly-rates and total rate for timesheet entries are imported
|
||||
- Customers in Kimai 2 are only used for recording
|
||||
- they cannot login and no user accounts will be created for them
|
||||
- they have a country code, which can be set during import or edited afterwards (Kimai v1 doesn't know the country)
|
||||
- they have a currency code, which can be set during import or edited afterwards (Kimai v1 only knows one global currency)
|
||||
- You have to supply the default password that is used for every imported user, as their password will be resetted
|
||||
- Data that was deleted in Kimai v1 (user, customer, projects, activities) will be imported and set to `invisible` (if you don't want that, you have to delete all entries that have the value `1` in the `trash` column before importing)
|
||||
|
||||
A possible full command for import:
|
||||
```bash
|
||||
bin/console kimai:import-v1 "mysql://user:password@127.0.0.1:3306/database?charset=utf8" "db_prefix" "password" "country" "currency"
|
||||
```
|
||||
The fields "country" and "currency" are optional and will be set to DE and EUR if not given.
|
||||
|
||||
It is recommended to test the import in a fresh database. You can test your import as often as you like and fix possible problems in your installation.
|
||||
A sample command could look like that:
|
||||
```bash
|
||||
bin/console doctrine:schema:drop --force && bin/console doctrine:schema:create && bin/console kimai:import-v1 "mysql://kimai:test@127.0.0.1:3306/kimai?charset=latin1" "kimai_" "test123" "CH" "CHF"
|
||||
```
|
||||
That will drop the configured Kimai v2 database schema and re-create it, before importing the data from the `mysql` database at `127.0.0.1` on port `3306` authenticating the user `kimai` with the password `test` for import.
|
||||
The connection will use the charset `latin1` and the default table prefix `kimai_` for reading data. Imported users can login with the password `test123` and all customer will have the country `CH` and the currency `CHF` assigned.
|
||||
@@ -1,120 +0,0 @@
|
||||
# Permissions
|
||||
|
||||
Kimai 2 provides a flexible permissions system, which can be adapted though your [local.yaml](configurations.md) config
|
||||
file and that is based on [user roles](users.md).
|
||||
|
||||
## Understanding permission structure
|
||||
|
||||
Before you learn to configure the permission system, you have to understand the three involved config types:
|
||||
|
||||
1. `Permission sets` define a re-usable name for a list of "permission names"
|
||||
2. `Permission maps` will apply a list of "permission sets" to a "user role"
|
||||
3. `Permissions` apply a list of "permission names" to a "user role"
|
||||
|
||||
An example and its explanation:
|
||||
|
||||
```yaml
|
||||
permissions:
|
||||
sets:
|
||||
ACTIVITY: [view_activity,create_activity]
|
||||
TIMESHEET: [view_own_timesheet,start_own_timesheet]
|
||||
maps:
|
||||
ROLE_USER: [TIMESHEET]
|
||||
ROLE_ADMIN: [TIMESHEET,ACTIVITY]
|
||||
roles:
|
||||
ROLE_USER: [my_profile]
|
||||
ROLE_ADMIN: [my_profile,start_other_timesheet]
|
||||
```
|
||||
|
||||
In `sets` we define the two `permissions sets` names "ACTIVITY" and "TIMESHEET". In `maps` we apply the `permissions set` to the
|
||||
called "TIMESHEET" to the user-role "ROLE_USER" and the two `permissions set` called "TIMESHEET" and "ACTIVITY" to the user-role "ROLE_ADMIN".
|
||||
|
||||
At this step the role have the following permissions:
|
||||
|
||||
- `ROLE_USER`: view_own_timesheet,start_own_timesheet
|
||||
- `ROLE_ADMIN`: view_own_timesheet,start_own_timesheet,view_activity,create_activity
|
||||
|
||||
As last step, the list of `permission names` will be added to the list of calculated permissions.
|
||||
So we add the permission "my_profile" to the user-role "ROLE_USER" and the two permissions "my_profile" and "start_other_timesheet" to the user-role "ROLE_ADMIN".
|
||||
|
||||
At the end the system calculated the final list of permissions:
|
||||
|
||||
- `ROLE_USER`: view_own_timesheet,start_own_timesheet,my_profile
|
||||
- `ROLE_ADMIN`: view_own_timesheet,start_own_timesheet,view_activity,create_activity,my_profile,start_other_timesheet
|
||||
|
||||
## Existing permissions
|
||||
|
||||
The permission-names were chosen to be self-explanatory. In the hope that it worked, here is the full list of existing permissions:
|
||||
|
||||
| Permission name | Set name | API use | Description |
|
||||
|---|---|---|---|
|
||||
| view_activity | ACTIVITIES | | allows access to the activity administration |
|
||||
| create_activity | ACTIVITIES | | - |
|
||||
| edit_activity | ACTIVITIES | | - |
|
||||
| delete_activity | ACTIVITIES | | - |
|
||||
| view_project | PROJECTS | | allows access to the project administration |
|
||||
| create_project | PROJECTS | | - |
|
||||
| edit_project | PROJECTS | | - |
|
||||
| delete_project | PROJECTS | | - |
|
||||
| view_customer | CUSTOMERS | | allows access to the customer administration |
|
||||
| create_customer | CUSTOMERS | | - |
|
||||
| edit_customer | CUSTOMERS | | - |
|
||||
| delete_customer | CUSTOMERS | | - |
|
||||
| view_invoice | INVOICE | | allows access to the invoice section |
|
||||
| create_invoice | INVOICE | | - |
|
||||
| view_invoice_template | INVOICE_TEMPLATE | | allows access to the invoice and invoice template section |
|
||||
| create_invoice_template | INVOICE_TEMPLATE | | - |
|
||||
| edit_invoice_template | INVOICE_TEMPLATE | | - |
|
||||
| delete_invoice_template | INVOICE_TEMPLATE | | - |
|
||||
| view_own_timesheet | TIMESHEET | X | - |
|
||||
| start_own_timesheet | TIMESHEET | | - |
|
||||
| stop_own_timesheet | TIMESHEET | | - |
|
||||
| create_own_timesheet | TIMESHEET | X | - |
|
||||
| edit_own_timesheet | TIMESHEET | X | - |
|
||||
| export_own_timesheet | TIMESHEET | | export your own timesheet in the timesheet panel |
|
||||
| delete_own_timesheet | TIMESHEET | | - |
|
||||
| view_other_timesheet | TIMESHEET_OTHER | | allows access to the complete timesheet view |
|
||||
| start_other_timesheet | TIMESHEET_OTHER | | - |
|
||||
| stop_other_timesheet | TIMESHEET_OTHER | | - |
|
||||
| create_other_timesheet | TIMESHEET_OTHER | | - |
|
||||
| edit_other_timesheet | TIMESHEET_OTHER | X | - |
|
||||
| export_other_timesheet | TIMESHEET | | export timesheet in the timesheet admin panel |
|
||||
| delete_other_timesheet | TIMESHEET_OTHER | | - |
|
||||
| view_rate_own_timesheet | RATE | | - |
|
||||
| edit_rate_own_timesheet | RATE | X | - |
|
||||
| view_rate_other_timesheet | RATE_OTHER | | - |
|
||||
| edit_rate_other_timesheet | RATE_OTHER | X | - |
|
||||
| view_export | EXPORT | | allows access to the export module|
|
||||
| create_export | EXPORT | | allows to create an export from the selected timesheet data |
|
||||
| edit_export_own_timesheet | EXPORT | X | set the export state of your own timesheet record |
|
||||
| edit_export_other_timesheet | EXPORT | X | set the export state of for other users timesheet records |
|
||||
| view_own_profile | PROFILE | | allows access to the own profile view - without this permission, users cannot access any of their profile settings or passwords ... |
|
||||
| edit_own_profile | PROFILE | | grants access to edit the own profile |
|
||||
| delete_own_profile | PROFILE | | grants access to delete the own profile |
|
||||
| password_own_profile | PROFILE | | grants access to change the own password |
|
||||
| roles_own_profile | PROFILE | | SECURITY ALERT: grants access to the own roles |
|
||||
| preferences_own_profile | PROFILE | | grants access to the own preferences |
|
||||
| api-token_own_profile | PROFILE | | grants access to change the own API token |
|
||||
| view_other_profile | PROFILE_OTHER | | - |
|
||||
| edit_other_profile | PROFILE_OTHER | | - |
|
||||
| delete_other_profile | PROFILE_OTHER | | - |
|
||||
| password_other_profile | PROFILE_OTHER | | allows to change the password for another user |
|
||||
| roles_other_profile | PROFILE_OTHER | | SECURITY ALERT: allows to change roles for other users |
|
||||
| preferences_other_profile | PROFILE_OTHER | | allows to change the preferences for another user |
|
||||
| api-token_other_profile | PROFILE_OTHER | | allows to set the API login token for other users |
|
||||
| hourly-rate_own_profile | - | | allows to edit the own user specific hourly rate |
|
||||
| hourly-rate_other_profile | - | | allows to edit other users specific hourly rate |
|
||||
| view_user | USER | X | allows to access the User administration and see the list of all users |
|
||||
| create_user | USER | | allows to create new users |
|
||||
| delete_user | USER | | allows to delete existing users |
|
||||
|
||||
## Configure permissions
|
||||
|
||||
Knowing that many companies need a different combination of allowed permissions than the default ones, you might also
|
||||
want to change the pre-configured permission.
|
||||
|
||||
You can do that in your [local.yaml](configurations.md). Define the permissions like we did in the above mentioned example,
|
||||
you might start by copying the default permissions from `kimai.yaml`.
|
||||
|
||||
Be aware: if you configure your own permission definition, you have to overwrite the complete
|
||||
node (`sets`, `maps` or`roles`) that you edited and define all SETS and/or ROLES.
|
||||
@@ -1,86 +0,0 @@
|
||||
# Theme
|
||||
|
||||
Kimai uses the [AdminLTE theme](https://github.com/kevinpapst/AdminLTEBundle/) which can be configured in the file `config/packages/admin_lte.yaml`.
|
||||
You find the theme specific documentation [here](https://github.com/kevinpapst/AdminLTEBundle/blob/master/Resources/docs/configurations.md).
|
||||
|
||||
All Kimai specific theme settings will be available in the twig templates with the global `kimai_context` key, e.g.
|
||||
|
||||
```twig
|
||||
{{ kimai_context.box_color }}
|
||||
```
|
||||
|
||||
## Searchable input types
|
||||
|
||||
The select boxes for customer, project and activity are by default the OS standard UI elements.
|
||||
This might be a limit for users with a long list of active and non-hidden elements.
|
||||
|
||||
Therefor a test is currently running, which can be activated setting the the following configuration:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
theme:
|
||||
select_type: selectpicker
|
||||
```
|
||||
|
||||
This will turn the select boxes into javascript elements with quick search option.
|
||||
|
||||
Why is this a beta test? It's not clear, if we keep on using this javascript library or activate it by default.
|
||||
Therefor your feedback is highly welcome, please post your opinion at GitHub.
|
||||
|
||||
## Active entries warning
|
||||
|
||||
A small colored warning sign will be shown, if a user has more than X active timesheet entries.
|
||||
|
||||
The amount `X` is configured in your `local.yaml` with the setting `timesheet.active_entries.soft_limit` (see [configurations.md](configurations.md)).
|
||||
|
||||
## Colors
|
||||
|
||||
Kimai allows you to configure colors in several places throughout the theme.
|
||||
|
||||
Possible values are:
|
||||
|
||||
- `aqua`
|
||||
- `black`
|
||||
- `blue`
|
||||
- `gray`
|
||||
- `green`
|
||||
- `purple`
|
||||
- `red`
|
||||
- `yellow`
|
||||
|
||||
### Fallback color
|
||||
|
||||
Whenever a color is required but none is configured, Kimai uses a fallback color from the config key `kimai.theme.box_color`.
|
||||
|
||||
You can change the default color `green` to any one from the above in your `local.yaml`:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
theme:
|
||||
box_color: 'blue'
|
||||
```
|
||||
|
||||
The fallback color should be applied whenever an optional color is configurable by the user:
|
||||
|
||||
```twig
|
||||
<div class="info-box bg-{{ color|default(kimai_context.box_color) }}"></div>
|
||||
```
|
||||
|
||||
## Icons
|
||||
|
||||
Kimai allows you to configure icons in several places (provided by [Font Awesome 5](https://fontawesome.com/icons)) and ships
|
||||
with a pre-defined list of icon aliases to guarantee a consistent look.
|
||||
|
||||
The pre-defined icons aliases are:
|
||||
|
||||
`activity`, `admin`, `calendar`, `customer`, `create`,`dashboard`, `delete`, `download`, `duration`, `edit`, `filter`,
|
||||
`help`, `invoice`, `list`, `logout`, `manual`, `money`, `print`, `project`, `repeat`, `start`, `start-small`, `stop`,
|
||||
`stop-small`, `timesheet`, `trash`, `user`, `visibility`
|
||||
|
||||
The full list can be found in this [TwigExtension](https://github.com/kevinpapst/kimai2/blob/master/src/Twig/Extensions.php).
|
||||
|
||||
Icon aliases can be used by applying the `icon` filter, e.g.
|
||||
|
||||
```
|
||||
<i class="{{ 'money'|icon }}"></i>
|
||||
```
|
||||
@@ -1,184 +0,0 @@
|
||||
# Timesheet
|
||||
|
||||
User manual on the timesheet tables and actions.
|
||||
|
||||
Kimai 2 provides also a [calendar view](calendar.md), which displays your timesheet entries in an easy readable format.
|
||||
|
||||
## Starting records
|
||||
|
||||
You can start new timesheet records like so:
|
||||
- Click the **redo** button in the "last activities" dropdown in the upper toolbar
|
||||
- Click the **redo** button from one of the activities in your timesheet
|
||||
- Start a completely new activity, by clicking the big **play** button in the toolbar
|
||||
|
||||
## Stopping records
|
||||
|
||||
You can stop timesheet records like so:
|
||||
- Click the **stop** button in the "active records" dropdown in the upper toolbar
|
||||
- Click the **stop** button from one of the running activities in your timesheet
|
||||
- Edit a running activity, add an end date and save
|
||||
|
||||
## Duration only mode
|
||||
|
||||
Kimai supports two modes for displaying and recording timesheet entries:
|
||||
|
||||
- `begin` and `end` time (default)
|
||||
- `date` and `duration` (the so called `duration_only` mode)
|
||||
|
||||
When activating the `duration_only` mode all timesheet tables will only display the `date` and `duration` of all records.
|
||||
In addition, the "edit timesheet" forms will be changed and instead of displaying the `end` date you will see a field for `duration`.
|
||||
The `start` date is only visible in these forms when editing an active or starting a new record.
|
||||
|
||||
You can activate the `duration_only` mode by switching the configuration key `kimai.timesheet.duration_only` to `true` in your `local.yaml`:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
timesheet:
|
||||
duration_only: true
|
||||
```
|
||||
|
||||
### Duration format
|
||||
|
||||
The `duration` field supports entering data in the following formats:
|
||||
|
||||
| Name | Format | Description | Examples |
|
||||
|---|---|---|---|
|
||||
| Colons | {hours}:{minutes}[:{seconds}] | Seconds are optional, overflow is supported for every field | `2:27` = 2 Hours, 27 Minutes / `3:143:13` = 5 Hours, 23 Minutes, 13 Seconds|
|
||||
| Natural | {hours}h{minutes}m[{seconds}s] | Seconds are optional, overflow is supported for every field | `2h27m` = 2 Hours, 27 Minutes / `3h143m13s` = 5 Hours, 23 Minutes, 13 Seconds |
|
||||
| Seconds | {seconds} | | `3600` = 1 Hour / `8820` = 2 Hours, 27 Minutes |
|
||||
|
||||
Please note: if time rounding is activated (which is the default behaviour), then your entered seconds might be removed after submitting the form.
|
||||
|
||||
## Limit active entries
|
||||
|
||||
To limit the amount of active entries each user can have, the configuration `active_entries` can be changed:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
timesheet:
|
||||
active_entries:
|
||||
soft_limit: 1
|
||||
hard_limit: 3
|
||||
```
|
||||
|
||||
The `soft_limit` is used as theme setting (formerly "kimai.theme.active_warning") to display a warning if the user has at least X active recordings.
|
||||
|
||||
The `hard_limit` is used to detect how many active records are allowed per user (by default 3 active time-records are allowed).
|
||||
If `hard_limit` is 1, the active record is automatically stopped when a new one is started.
|
||||
When `hard_limit` is greater than 1 and as soon as the limit is reached, the user has to manually stop at least one active
|
||||
entry (an error message is shown, indicating why it is not possible to start another one).
|
||||
|
||||
## Descriptions with Markdown
|
||||
|
||||
The description for every timesheet entry can be formatted in two different ways, configured with the `markdown_content` setting.
|
||||
|
||||
- `false` - simple newlines in the description box will be displayed in the frontend as well (default)
|
||||
- `true` - description will be rendered with a markdown engine, supporting simple lists and other HTML content
|
||||
|
||||
Allowing Markdown in timesheet descriptions is beautiful, but also could be a [security risk](https://github.com/erusev/parsedown/blob/master/README.md#security).
|
||||
Kimai will only apply the markdown in the user timesheet and not in the admin section as additional security measure.
|
||||
|
||||
## Rounding of begin, end and duration for timesheet records
|
||||
|
||||
Rounding rules are used to round the begin & end dates and the duration for timesheet records.
|
||||
|
||||
1. You can define as many rules as you want ("default" is only an example)
|
||||
2. Every matching rule will be applied, so be careful with overlapping rules
|
||||
3. The end_date of timesheet records will be used to match the day (think about entries which are recorded overnight)
|
||||
4. If you set one of "begin", "end", "duration" to 0 no rounding will be applied for that field and the exact time (including seconds) is used for calculation
|
||||
5. The values of the rules are minutes (not the minute of an hour), so 5 for "begin" means we round down to the previous multiple of five
|
||||
6. You can define different rules for different days of the week
|
||||
7. "begin" will always be rounded to the floor (down) and "end" & "duration" to the ceiling (up)
|
||||
8. Rounding rules will be applied on stopped timesheet records only, so you might see an un-rounded value for the start time and duration until you stop the record
|
||||
|
||||
You can configure your `rounding` rules by changing the configuration file [kimai.yaml](../../config/packages/kimai.yaml).
|
||||
|
||||
### Examples
|
||||
|
||||
A simple example to always charge at least 1 hour for weekend work (even if you only worked for 5 minutes) could look like this:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
timesheet:
|
||||
rounding:
|
||||
weekend:
|
||||
days: ['saturday','sunday']
|
||||
begin: 1
|
||||
end: 1
|
||||
duration: 60
|
||||
```
|
||||
|
||||
A rule which is often used is to round up to a mulitple of 10:
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
timesheet:
|
||||
rounding:
|
||||
workdays:
|
||||
days: ['monday','tuesday','wednesday','thursday','friday','saturday','sunday']
|
||||
begin: 10
|
||||
end: 10
|
||||
duration: 0
|
||||
```
|
||||
|
||||
## Rate calculation
|
||||
|
||||
There are two rate types:
|
||||
|
||||
- __Fixed rate__: the value will be used to set the records rate, no matter how long the duration is
|
||||
- __Hourly rate__: will be used to calculate the records rate by multiplying it with the duration (see below)
|
||||
|
||||
If any of the above is set to 0, the records rate will be set to 0.
|
||||
|
||||
While calculating the rate of a timesheet entry, the first setting that is found will be used (in order of appearance):
|
||||
|
||||
- Timesheet fixed rate
|
||||
- Activity fixed rate
|
||||
- Project fixed rate
|
||||
- Customer fixed rate
|
||||
- Timesheet hourly rate
|
||||
- Activity hourly rate
|
||||
- Project hourly rate
|
||||
- Customer hourly rate
|
||||
- Users hourly rate
|
||||
|
||||
If neither a fixed nor a hourly rate can be found, the users rate will be used to calculate the records rate.
|
||||
If that is the case and if the users rate is not set or equals 0, the records rate will be set to 0.
|
||||
|
||||
The calculation is based on the following formula:
|
||||
|
||||
- __Fixed rate__: `$fixedRate`
|
||||
- __Hourly rate__: `$hourlyRate * ($durationInSeconds / 3600) * $factor`
|
||||
|
||||
Please see below to see how you can apply configurable multiplying factors based on day and time.
|
||||
|
||||
### Rate multiplier for specific weekdays
|
||||
|
||||
If you want to apply different hourly rates multiplication `factor` for specific weekdays, you can use this `rates` configuration.
|
||||
|
||||
1. You can define as many rules as you want ("workdays" and "weekend" are only examples)
|
||||
2. Every matching rule will be applied, so be careful with overlapping rules
|
||||
3. The end_date of timesheet records will be used to match the day (think about entries which are recorded overnight)
|
||||
4. "days" is an array of weekdays, where the days need to be written in english and in lowercase
|
||||
5. "factor" will be used as multiplier for the applied hourly rate
|
||||
6. Rate rules will be applied on stopped timesheet records only, as it can't be calculated before
|
||||
7. There is no default rule active, by default the users hourly-rate is used for calculation
|
||||
|
||||
You can configure the `hourly_rate` rules by changing the configuration file [kimai.yaml](../../config/packages/kimai.yaml).
|
||||
|
||||
#### Examples
|
||||
|
||||
1. The "workdays" rule will use the default "hourly rate" for each timesheet entry recorded between "monday" to "friday" as a multiplication with 1 will not change the result
|
||||
2. The "weekend" rule will add 50% to each timesheet entry that will be recorded on "saturdays" or "sundays"
|
||||
|
||||
```yaml
|
||||
kimai:
|
||||
timesheet:
|
||||
rates:
|
||||
workdays:
|
||||
days: ['monday','tuesday','wednesday','thursday','friday']
|
||||
factor: 1
|
||||
weekend:
|
||||
days: ['saturday','sunday']
|
||||
factor: 1.5
|
||||
```
|
||||
@@ -1,54 +0,0 @@
|
||||
# Translations
|
||||
|
||||
We try to keep the number of language files small, in order to make it easier to identify the location of application messages and to unify the codebase.
|
||||
|
||||
- If you add a new key, you have to add it in every language file
|
||||
- Its very likely that you want to edit the file `messages` as it holds 90% of our application translations
|
||||
|
||||
The files in `translations/` as a quick overview:
|
||||
|
||||
- `exceptions` only holds translations of error pages and exception handlers
|
||||
- `flashmessages` hold all success and error messages, that will be shown as results from action calls after page reload
|
||||
- `messages` holds most of the visible application translations (like all the static UI elements and form translations)
|
||||
- `pagerfanta` includes the translations for the pagination component
|
||||
- `sidebar` holds all the translations of the right sidebar
|
||||
- `validators` only holds translations related to violations/validation of submitted form data (or API calls)
|
||||
- `invoice-calculator` holds translations of calculator types (see `Adding invoice calculator` in [developers](developers.md)-section)
|
||||
- `invoice-numbergenerator` holds translations of the invoice calculator (see `Adding invoice-number generator ` in [developers](developers.md)-section)
|
||||
- `invoice-renderer` holds translations of all invoice templates ([read more](invoices.md))
|
||||
|
||||
## Adding a new language
|
||||
|
||||
As example I choose a new hypothetical language with the locale `xx`.
|
||||
|
||||
Copy each translation file from `translations/*.en.xliff` and rename them to `translations/*.xx.xliff`.
|
||||
|
||||
Adjust the `target-language` in the file header, as example for the new file `exceptions.xx.xliff`:
|
||||
```yml
|
||||
<file date="2018-08-01T20:00:00Z" source-language="en" target-language="xx" datatype="plaintext" original="exceptions.en.xliff">`
|
||||
```
|
||||
|
||||
Adjust the file `config/packages/kimai.yaml` and add the language settings below the key `kimai.languages`:
|
||||
```yaml
|
||||
kimai:
|
||||
languages:
|
||||
xx:
|
||||
date: 'd.m.Y'
|
||||
# there are more settings, copy them from 'en'
|
||||
```
|
||||
|
||||
Append the new locale in the file `config/services.yaml` at `parameters.app_locales` divided by a pipe:
|
||||
|
||||
```yaml
|
||||
parameters:
|
||||
locale: en
|
||||
app_locales: en|de|ru|it|xx
|
||||
```
|
||||
|
||||
## Check for missing translations
|
||||
|
||||
When you search for missing keys, please use this command:
|
||||
```bash
|
||||
bin/console debug:translation --only-missing de
|
||||
```
|
||||
and replace `de` with your locale.
|
||||
@@ -1,37 +0,0 @@
|
||||
# Updating Kimai
|
||||
|
||||
> **NOTE**
|
||||
>
|
||||
> Don't forget that some tweaks may be necessary to these instructions if you are using FTP, developing or updating on your
|
||||
personal computer instead of a server. Read the [installation docu](installation.md) for more information.
|
||||
|
||||
**STOP**
|
||||
|
||||
1. It is important that you don't execute the installation steps before or after your update
|
||||
2. Make sure that you have a working database backup before you start the update
|
||||
3. Read the [UPGRADING](https://github.com/kevinpapst/kimai2/blob/master/UPGRADING.md) guide and the [release information](https://github.com/kevinpapst/kimai2/releases) to check if there are further steps required
|
||||
|
||||
**START**
|
||||
|
||||
Change into your Kimai 2 installation directory, then fetch the latest code and install all dependencies:
|
||||
|
||||
```bash
|
||||
git fetch --tags
|
||||
git checkout 0.8
|
||||
sudo -u www-data composer install --no-dev --optimize-autoloader
|
||||
```
|
||||
|
||||
Refresh your cache:
|
||||
|
||||
```bash
|
||||
sudo -u www-data bin/console cache:clear --env=prod
|
||||
sudo -u www-data bin/console cache:warmup --env=prod
|
||||
```
|
||||
|
||||
And upgrade your database:
|
||||
|
||||
```bash
|
||||
bin/console doctrine:migrations:migrate
|
||||
```
|
||||
|
||||
Done! You can use the latest version of Kimai 2.
|
||||
@@ -1,103 +0,0 @@
|
||||
# Users
|
||||
|
||||
## Roles
|
||||
|
||||
There are multiple pre-defined roles in Kimai, which define the ACLs/permissions.
|
||||
|
||||
| Role name | extends | Description |
|
||||
|---|---|---|
|
||||
| ROLE_CUSTOMER | - | Currently not used, reserved for future features |
|
||||
| ROLE_USER | ROLE_CUSTOMER | Normal user that wants to track working times |
|
||||
| ROLE_TEAMLEAD | ROLE_USER | This role manages teams of ROLE_USER (this feature is not yet implemented, but planned for the future) and has further permissions on invoices |
|
||||
| ROLE_ADMIN | ROLE_TEAMLEAD | Admins can do almost everything in Kimai, except some user specific tasks |
|
||||
| ROLE_SUPER_ADMIN | ROLE_ADMIN | Evey Super-Admin can do anything Kimai |
|
||||
|
||||
### Permissions
|
||||
|
||||
The permission system is configurable through a configuration file. You can find further information in the [permissions](permissions.md) chapter.
|
||||
|
||||
## Login
|
||||
|
||||
- User can login with username or email
|
||||
- If you activate the `Remember me` option, you can use use the most common functions within the next days without a new login
|
||||
|
||||
Kimai uses the FOSUserBundle for security related tasks like user management.
|
||||
Its configuration can be found in [fos_user.yaml](../../config/packages/fos_user.yaml).
|
||||
|
||||
### Remember me login
|
||||
|
||||
If you have chosen to login with the `Remember me` option, your login will be extended to one week (default value).
|
||||
After coming back and being remembered you have access to all the following features:
|
||||
|
||||
- view your own timesheet
|
||||
- start and stop new records
|
||||
- edit existing records
|
||||
|
||||
If you are an administrator, you will see all your allowed options in the menu, but will be redirected to the login
|
||||
form when you try to access them. This is a security feature to prevent abuse in case you forgot to logout in public
|
||||
environments.
|
||||
|
||||
The default period for the `Remember me` option can be changed in the config file [security.yaml](../../config/packages/security.yaml).
|
||||
|
||||
## User registration
|
||||
|
||||
User registration with instant approval is activated by default, so users can register and will be able to login and start time-tracking instantly.
|
||||
|
||||
If you want to disable the registration or enable email verification, read further below under _Configurations_.
|
||||
|
||||
### Email activation
|
||||
If you want your new users to use [email](emails.md) based activation add this to your `local.yaml`:
|
||||
|
||||
```yaml
|
||||
fos_user:
|
||||
registration:
|
||||
confirmation:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
### Disable user registration
|
||||
|
||||
If you want to disable the user registration, add this your `local.yaml`:
|
||||
```yaml
|
||||
kimai:
|
||||
user:
|
||||
registration: false
|
||||
```
|
||||
|
||||
If you only want to hide the link from the login form but keep the functionality, add this your `local.yaml`:
|
||||
```yaml
|
||||
admin_lte:
|
||||
routes:
|
||||
adminlte_registration: ~
|
||||
```
|
||||
|
||||
## Password reset
|
||||
|
||||
The reset password function is enabled by default, but you need to activate [email](emails.md) support if you want to use it.
|
||||
|
||||
If you want to deactivate this feature you have to change the following configs:
|
||||
|
||||
- in `config/packages/admin_lte.yaml` remove the route alias `admin_lte.routes.adminlte_password_reset` (this will remove the link from the login form)
|
||||
- in `config/routes.yaml` remove the block `fos_user_resetting` (this will deactivate the functionality)
|
||||
|
||||
If you want to configure the behaviour (like the allowed time between multiple retries) then configure the settings:
|
||||
|
||||
- in `config/packages/fos_user.yaml` the key below `fos_user.registration.resetting` (see [documentation](https://symfony.com/doc/current/bundles/FOSUserBundle/configuration_reference.html))
|
||||
- the values `retry_ttl` and `token_ttl` are configured in seconds (7220 = 2 hours)
|
||||
|
||||
### Disable password reset
|
||||
|
||||
If you want to disable the password reset, add this your `local.yaml`:
|
||||
```yaml
|
||||
kimai:
|
||||
user:
|
||||
password_reset: false
|
||||
```
|
||||
|
||||
If you only want to hide the link from the login form but keep the functionality, add this your `local.yaml`:
|
||||
```yaml
|
||||
admin_lte:
|
||||
routes:
|
||||
adminlte_password_reset: ~
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user