Meine erste Skript-Bibliothek

Lange Vorrede …

IPS Skripte oder PHP-Skripte sind eigentlich kleine Code-Snipplets, welche mit Hilfe des von Symcon bereitgestellte PHP-SDKs irgendwas am System manipulieren. Das kann eine einfache Werteänderung von Variablen sein bis hin zu einer kompletten Gerätesteuerung eines Drittanbieters (wird heute meistens per Modul gelöst).
Für den eigenen Gebrauch ist da auch schnell was programmiert und funktioniert auch soweit tadellos. Will man jetzt aber ein Skript der Allgemeinheit zur Verfügung stellen wird der Supportaufwand schnell recht groß – Variablen IDs hier, Profile da – und so geht es schnell vom Hundertsten ins Tausendste.
Um sowohl für mich als auch später für alle anderen den Aufwand so gering wie möglich zu halten, habe ich für mich den sogenannten „OnePager“ ins Leben gerufen bzw. aus dem Forum übernommen. D.h. im Skript befindet sich neben der eigentlichen Automatisierung auch die gesamte Konfiguration und Initialisierung – angefangen von der Erstellung alle notwendigen Variablen, Funktionen, Profile bis hin zu den Events und Timer’n!

// Erzeugt eine Variable unterhalb {id} mit dem Namen {name} vom Typ {type}
// Existiert die Variable schon wird diese zurückgeliefert.
// {type}   : 0 = Boolean, 1 = Integer, 2 = Float, 3 = String
// {pos}    : 0 gleich Standardposition, sonst neue Sortierreihenfolgenummer 
// [icon}   : Zuweisung eines Icons mit dem Namen {icon}
// {profil} : leer für kein Profil, sonst Profilnamen 
// {action} : Script-ID für Auslösung via Webfront 
function CreateVariableByName($id, $name, $type, $pos = 0, $icon = '', $profile = '', $action = null) 
{
    $vid = @IPS_GetVariableIDByName($name, $id); 
    if($vid===false) {
        $vid = IPS_CreateVariable($type); 
        IPS_SetParent($vid, $id); 
        IPS_SetName($vid, $name); 
        IPS_SetPosition($vid, $pos); 
        IPS_SetIcon($vid, $icon);
        if($profile !== '') { 
            IPS_SetVariableCustomProfile($vid, $profile); 
        }
        if($action != null) {
            IPS_SetVariableCustomAction($vid, $action);
        }
    }
    return $vid; 
}

Beispiel für eine Konfigurationsfunktion: CreateVariableByName

All diese Funktionaltäten für die Konfiguration wurden über spezielle Funktionen gekapselt, damit man immer gleiche Dinge nicht x-mal neu programmieren muss. Über die Zeit entstand somit eine kleine aber feine Funktionsbibliothek.
Mit zunehmender Anzahl an solchen Skripten duplizierten sich dann auch in jedem Skript die benötigten Funktionen. Musste man jetzt was erweitern oder anpassen – musste man durch alle Skripte durchgehen und den Patch nachziehen 🙁

Und was machen wir jetzt?

Aus diesem Grund habe ich mich vor einiger Zeit entschieden diese wiederkehrenden Funktionen auszulagern und über die __autoload.php meinem System zur Verfügung zu stellen. Dies hat leider zur Folge das man jetzt die Skripte nicht mehr einfach so der Allgemeinheit zur Verfügung stellen kann. Aber bekanntlich muss man ja einen Tod sterben!

<?php
################################################################################
# Script:   __autoload.php
# Version:  1.0.20210609
# Author:   Heiko Wilknitz (@Pitti)
#
# Um Funktionen, Konstanten usw. global über alle Skripte hinweg zur Verfügung
# zu stellen müssen diese in der Datei "__autoload.php" definiert werden. 
# Diese muss sich im "IP-Symcon/scripts"-Ordner befinden.
#
# Innerhalb der "__autoload.php" können dann weitere Dateien eingelesen werden.
#
# ------------------------------ Changelog -------------------------------------
#
# 09.06.2021 - Initalversion (v1.0)
#
################################################################################

require_once(IPS_GetKernelDir() . "/scripts/System.Functions.ips.php");

Inhalt von __autoload.php

Angenehmer Nebeneffekt

Das schöne an der ganzen Sache ist, man kann das inkludierte Skript wieder direkt in der Console von IP_Symcon bearbeiten. In meinem Fall habe ich das Script über die Skriptverwaltung in System.Functions.ips.php umbenannt!

D.h. man kann alle Funktionen an einer zentralen Stelle pflegen und man muss auch nicht über das Dateisystem gehen um Dinge anzupassen bzw. zu erweitern. Das heißt man kann auch alle Änderungen sofort testen und muss auch nicht irgendwas Reloaden usw..

Der Kreis schließt sich

Wenn man alles eingerichtet hat und alles reibungslos funktioniert ist das eine feine Sache, aber wie kommt man dahin? Dafür habe ich schon vor geraumer Zeit die Grundlagen gelegt 🙂 In meinem Blog-Artikel Versionierung von Skripten habe ich (m)einen Weg aufgezeigt wie man alles unter einen Hut bekommt.

Dementsprechend habe ich eine Bibliothek, welche die initialen Skripte beinhaltet in ein github Repository eingecheckt. Zusätzlich noch eine Skriptvorlage als Rahmen für eigene Automation. Diese beinhaltet extra einen Kommentar mit den entsprechenden Hinweis zur Verwendung der Bibliothek.

Hinweis in der Vorlage
# Requires include of the global function script via autoload (__autoload.php)
# or direct in the script (uncomment next line)!
# require_once(IPS_GetKernelDir().“scripts“.DIRECTORY_SEPARATOR.’System.Functions.ips.php‘);
# You can download it from here https://github.com/wilkware/ips-scripts

Zusammenfassung

Wie geschrieben, schließt sich für mich hier der Kreis und bietet eine charmante Lösung für eine klar definierte Aufgabenstellung. Für andere ist das vielleicht zu viel Overengineering. Aber auch die können mit wenigen Anpassungen (Repo-Dateien runterladen, Skript in IPS anlegen und alles reinkopieren und autoload.php erweitern) in den Genuss der/einer zentralen Funktions-Bibliothek kommen.

Fazit
Es gibt wie immer viele Wege nach Rom. Aber der hier vorgestellte vereint alle Vorteile einer (semi)professionellen Programmierung, inklusive Versionierung, Wiederverwendung und Sicherheit.