jjsm01/kimai2
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

removed inline documentation (#624)

Browse Source
This commit is contained in:
Kevin Papst
2019-03-11 15:10:51 +01:00
committed by GitHub
parent 3ac72a5c89
commit 0f6334314e
43 changed files with 17 additions and 2235 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
var/docs/README.md
View File

@@ -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

52
var/docs/calendar.md
View File

@@ -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'
```

78
var/docs/configurations.md
View File

@@ -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.

17
var/docs/customer.md
View File

@@ -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
```

126
var/docs/dashboard.md
View File

@@ -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!

245
var/docs/developers.md
View File

@@ -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`.

23
var/docs/developers_api.md
View File

@@ -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).

85
var/docs/docker.md
View File

@@ -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))

55
var/docs/emails.md
View File

@@ -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.

20
var/docs/export.md
View File

@@ -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!

60
var/docs/faq.md
View File

@@ -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.

269
var/docs/installation.md
View File

@@ -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
[![Install kimai2 with YunoHost](https://install-app.yunohost.org/install-with-yunohost.png)](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.

17
var/docs/internal.md
View File

@@ -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)

223
var/docs/invoices.md
View File

@@ -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)
'
```

29
var/docs/migration_v1.md
View File

@@ -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.

120
var/docs/permissions.md
View File

@@ -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.

86
var/docs/theme.md
View File

@@ -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>
```

184
var/docs/timesheet.md
View File

@@ -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
```

54
var/docs/translations.md
View File

@@ -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.

37
var/docs/updates.md
View File

@@ -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.

103
var/docs/users.md
View File

@@ -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: ~
```