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 mir 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 musst du 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üf die Kimai-Versionshinweise des Plugins, bevor du mit einer anderen Methode installierst.

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 du ein eigenes Plugin brauchst, das es so noch nicht gibt: das ist mein Kerngeschäft.