Wiki Ad libitum

Updater-Bundle

Adlib Updater Bundle

Ein schlankes Symfony-Bundle zum Prüfen und Ausführen von Updates in bestehenden Symfony-Projekten.

Installation (manuell, ohne Flex-Recipe)

  1. Das Repository in der composer.json deines Zielprojekts hinzufügen:
   "repositories": [
       {
           "type": "vcs",
           "url": "https://github.com/Odido/programname.git"
       }
   ],
  1. Vorab-Konfiguration anlegen (Wichtig!):
    Damit die Installation ohne Fehler durchläuft (wegen des automatischen cache:clear), erstelle zuerst die Datei config/packages/adlib_updater.yaml in deinem Projekt:
   adlib_updater:
     # MANDATORY: Die URL zu deinem GitHub Repository
     update_url: 'https://github.com/Odido/project-url' 

     # OPTIONAL: GitHub Token für private Repositories
     github_token: '%env(GITHUB_TOKEN)%' 

     # OPTIONAL: Pfade (Standardwerte werden hier gezeigt)
     target_dir: '%kernel.project_dir%'
     temp_dir: '%kernel.project_dir%/var/updater'

Die update_url ist die URL zu dem Projekt, das upgedated werden soll.

  1. Bundle installieren:
   composer require adlib/updater-bundle
  1. Bundle registrieren (falls keine Auto-Discovery/Flex):
   // config/bundles.php
   return [
       Adlib\UpdaterBundle\AdlibUpdaterBundle::class => ['all' => true],
   ];

Twig in deinem Template nutzen (Beispiel Header/Banner):

   {% if updater_has_update() %}
       <div class="alert alert-warning">
           Es ist eine neue Version {{ updater_remote_version() }} verfügbar.
           <form action="{{ path('adlib_updater_run') }}" method="post" style="display:inline;">
               <button class="btn btn-sm btn-primary">Update jetzt ausführen</button>
           </form>
       </div>
   {% endif %}

Funktionsweise (GitHub-Integration)

  • Version-Check: Das Bundle fragt die GitHub API (api.github.com/repos/.../tags) ab und vergleicht den neuesten Tag (z.B. v1.2.3) mit deiner VERSION in der .env.
  • Download: Bei einem Update wird das ZIP-Archiv des Tags von GitHub heruntergeladen (/archive/refs/tags/v{version}.zip).
  • Backup: Vor der Installation werden die Ordner src, templates, config, public, translations und assets sowie die .env in einen Zeitstempel-Ordner unter var/updater/backup_... gesichert.
  • Installation: Das ZIP wird entpackt und der Inhalt (Source-Code) über deine bestehenden Dateien drüberkopiert.
  • Rollback: Tritt beim Entpacken oder Kopieren ein Fehler auf, wird automatisch der Zustand aus dem Backup wiederhergestellt. Bei einem totalen Systemausfall kann das Rollback auch manuell über die Konsole gestartet werden: php bin/console adlib:updater:rollback.

Wie funktioniert’s?

  • Beim erfolgreichen Login löst UpdateCheckSubscriber eine Abfrage der Remote-Version aus (via GitHub API /tags).
  • Ist die Remote-Version (der neueste Tag) größer als VERSION aus deiner .env, wird in der Session ein Flag gesetzt.
  • Über die Twig-Extension kannst du den Status abfragen und einen Button anzeigen.
  • Der UpdateController startet den Update-Prozess (UpdateManager). Bei Fehlern wird automatisch ein Rollback versucht und alles geloggt.

Console-Befehle

Rollback (Manuell)

Sollte die Anwendung nach einem Update nicht mehr erreichbar sein, kann ein Rollback über die Kommandozeile durchgeführt werden.

php bin/console adlib:updater:rollback

Verhalten:

  • Ohne weitere Optionen sucht der Befehl automatisch nach dem aktuellsten Backup im konfigurierten temp_dir (Standard: var/updater/backup_...).
  • Es wird eine Sicherheitsabfrage angezeigt, bevor die Dateien wiederhergestellt werden.

Optionen:

  • --backup-dir=/pfad/zum/backup: Ermöglicht die Angabe eines spezifischen Backup-Ordners, falls nicht das aktuellste Backup verwendet werden soll.

Logging

Das Bundle nutzt den Standard-Logger von Symfony und verwendet einen eigenen Kanal namens updater. Dieser Kanal wird vom Bundle automatisch registriert.

Das symfony/monolog-bundle ist als Abhängigkeit definiert und wird automatisch mitinstalliert.

Konfiguration (Beispiel)

Um alle Meldungen des Updaters in eine separate Datei zu schreiben, kannst du in deiner config/packages/monolog.yaml einen neuen Handler hinzufügen. Achte hierbei auf den when@level:

monolog:
    handlers:
        updater:
            type: stream
            path: "%kernel.logs_dir%/updater.log"
            level: info
            channels: ["updater"]

Falls du keine separate Datei möchtest, stelle sicher, dass deine Standard-Handler den Kanal updater nicht ausschließen und das Log-Level auf info (oder niedriger) steht, besonders in der prod-Umgebung. Die Logdateien finden sich, wenn die Standardeinstellungen in config/packages/monolog.yaml nicht geändert wurden, unter var/log.

TODO / Erweiterungen

  • Implementierung des echten Download/Backup/Rollback-Flows (Tar/Zip), Checksummen, Wartungsmodus.
  • Ratenbegrenzung der Update-Prüfung (z.B. 1x pro Prozessstart o. Session).
  • Ausgelagerter Update-Status (Cache/DB) anstatt Session, wenn gewünscht.