Kimai-Plugin installieren: Schritt für Schritt

Kimai-Plugins werden über Composer eingebunden. Die häufigste Fehlerquelle ist nicht das Plugin selbst, sondern eine übersprungene Reihenfolge bei Installation und Cache. Diese Anleitung zeigt den Ablauf, der bei uns in Kundenprojekten zuverlässig funktioniert.

1. Plugin-Verzeichnis vorbereiten

Kimai erwartet Plugins unterhalb von var/plugins/. Bei einer Composer-basierten Installation legt der Paket-Installer den Ordner automatisch an — bei manueller Installation per Git-Checkout müssen Sie ihn selbst anlegen und auf den passenden Nutzer (i. d. R. www-data) chownen.

mkdir -p var/plugins
chown -R www-data:www-data var/plugins

2. Composer-Installation

composer require kimai/ihr-plugin-name

Composer registriert das Plugin automatisch in der Kimai-Konfiguration. Bei älteren Kimai-Versionen (vor 2.0) ist stattdessen ein manueller Eintrag in config/packages/kimai.yaml nötig — prüfen Sie die Kimai-Versionshinweise des Plugins, bevor Sie mit einer anderen Methode installieren.

3. Migrationen ausführen

Die meisten Plugins bringen eigene Datenbank-Migrationen mit:

bin/console kimai:reload -n

Dieser Befehl leert außerdem den Symfony-Cache — ein separater cache:clear ist danach meist nicht mehr nötig, schadet aber auch nicht.

4. Rechte & Berechtigungen prüfen

Neue Plugins bringen oft eigene Berechtigungen mit (z. B. plugin_name.view). Diese müssen den passenden Rollen zugewiesen werden, sonst sehen selbst Admins die neue Funktion nicht:

Administration → Rollen → gewünschte Rolle → neue Berechtigung aktivieren.

5. Nach dem Update: Assets neu bauen

Bringt das Plugin eigenes CSS/JS mit, hilft im Zweifel:

bin/console assets:install --symlink

Typische Stolpersteine

Weißer Bildschirm nach der Installation → fast immer ein PHP-Versionskonflikt zwischen Kimai-Core und Plugin. Kompatibilitätstabelle des Plugins prüfen.
Plugin erscheint nicht im Menü → Berechtigung fehlt (siehe Schritt 4) oder der Cache wurde nicht wirklich geleert (Docker-Setups: Cache-Volume prüfen).
Migration schlägt fehl → meist ein Versionsversatz zwischen Plugin und Kimai-Core. Erst Kimai-Core aktualisieren, dann das Plugin.

Wenn Sie ein eigenes Plugin brauchen, das es so noch nicht gibt — das ist unser Kerngeschäft.