paresy/gist:236bfbfcb26e6936eaae919b3cfdfc4f

## gistfile1.md

      
    Raw
  

              gistfile1.md
            
          
    Best Practice zur PHP-Modul Erstellung


Generelle Entwicklung

Module sollten grundsätzlich auf Englisch erstellt und ins Deutsche übersetzt werden
Fehlermeldungen dürfen mit @ nur verdeckt werden, wenn der Rückgabewert überprüft wird und bei einem echten Fehlerfall dies dem Nutzer mitgeteilt wird. Andernfalls findet man im Fehlerfall den Verursacher niemals heraus. Sichtbare Fehler können behoben werden. Unsichtbare Fehler bringen inkonsistentes Verhalten und frustrieren nur alle beteiligten.
Daten, welche der Benutzer nicht benötigt, sollten auch nicht in Variablen erscheinen (z.B. irgendwelche Puffer / Temporäre Inhalte in String Variablen). Dafür bietet das SDK die SetBuffer/GetBuffer Funktionen, welches über eine JSON Kodierung auch mehrere Elemente enthalten können.
Der Inhalt der library.json / module.json darf nur die von der Dokumentation definierten Felder enthalten. Andere Felder können in zukünftigen Version seitens IP-Symcon verwendet werden und sind vollständig reserviert.
Module mit externen Abhängigkeiten müssen diese vollständig im speziell erlaubten libs Ordner mitliefern.
Ein Modul darf niemals Abhängigkeiten aus einer anderen Bibliothek erfordern, sodass das Modul (ohne diese Bibliothek) "kaputt" ist (z.B. ein include auf eine benötigte PHP Datei). Eine Bibliothek muss immer in sich geschlossen und funktionsfähig sein. Optionale Funktionen können durch zusätzlich installierte Bibliotheken freigeschaltet werden. (Randfall: Ein Modul kann ohne sinvolle Funktion sein, solange keine anderen installierten Bibliotheken vorhanden sind. Sie muss aber darauf Hinweisen und trotzdem fehlerfrei installierbar sein. Sobald weitere unterstützte Bibliothken installiert werden, erweitert sich der Funktionsumfang)
Objekte dürfen niemals über den Namen gefunden werden. Es muss immer ein Ident gesetzt und dafür verwendet werden.
Insbesondere in überschriebenen Create und ApplyChanges Funktion, welche beim Start von IP-Symcon aufgerufen werden, sollte nicht darauf vertraut werden, dass andere Instanzen verfügbar sind, da dieser in zufälliger Reihenfolge erstellt werden können. Die Fehlermeldung "InstanceInterface is not available" kommt ansonsten zum Vorschein. Es sollte somit immer überprüft werden, ob der Kernel Runlevel gleich KR_READY ist. Alternativ ist auch Möglich per RegisterMessage und MessageSink auf die Nachricht IPS_KERNELSTARTED zu reagieren. Diese Einschränkung betrifft ebenfalls den Datenfluss, sodass keine SendDataToParent / SendDataToChildren Funktionen verwendet werden dürfen.
Die seit IP-Symcon 5.0 enthaltene RequestAction Funktion löst in weiten Teilen die früher benötigten Public-Funktionen zum Schalten ab. Es ist somit nicht mehr erforderlich Public-Funktionen zum Schalten anzubieten.


Die Hoheit des Benutzers wahren

Eine Instanz sollte niemals automatisch Variablen im Archiv aktivieren. Dies ist allein die Entscheidung vom Benutzer, welcher dies explizit tun kann und soll. Bei einem Modul mit sehr vielen Variablen kann ein zusätzlicher Button im Aktionsbereich des Konfigurationsformulars platziert werden, welcher explizit gedrückt werden muss um diesen Vorgang zu automatisieren.
Eine Instanz sollte im Normalfall die Sichtbarkeit/Bedienbarkeit nicht verändern. Wenn es dies tut, sollte die Dokumentation darauf hinweisen, dass diese Eigenschaften für die jeweiligen Objekte nicht dem Benutzer zur Verfügung stehen.
Der Name/Position einer Variable darf nur über die RegisterVariable* Funktionen vorgegen werden. Nachträgliche Änderung und Sortierung obliegt vollständig dem Benutzer.
Ein Modul darf niemals automatisch andere Instanzen erstellen. Ausnahmen bilden die RequireParent/ConnectParent/ForceParent Funktionen, welche automatisch die Datenflusskette erstellen. Wenn Instanzen automatisiert erstellt werden sollen, passiert dies nur über einen Button im Aktionsbereich der Konfigurationsformulare, sodass der Benutzer die vollständige Kontrolle hat, wann neue Instanzen erstellt werden. Bevorzugt wird das Erstellen von einzelnen Instanzen über das Konzept der Konfiguratoren.
Eigenschaften (Properties) dienen zur Konfiguration durch den Benutzer. Ein Modul sollte sich niemals selber umkonfigurieren (z.B. über IPS_SetProperty oder IPS_SetConfiguration). Ebenfalls ein Aufruf aus einem Splitter Modul (siehe 5.1) ist nicht gestattet. Sollen Instanzen vorkonfiguriert erstellt werden, muss dazu ein Konfigurator erstellt werden, über den der Benutzer passende Instanzen erstellen kann.


Profile

Profile sollten mit PREFIX.NAME erstellt werden. (IP-Symcon und unsere Modul halten sich noch nicht daran - ich würde dies gerne als Konvention zur Diskussion in den Raum stellen)


Datenfluss korrekt verwenden

Um die Belastung im System gering zu halten, wird empfohlen die entsprechenden Data Filter zu setzen (SetReceiveDataFilter, SetForwardDataFilter)
Siehe auch 5.1


Kompatibilität für Sandboxing von Instanzen

Es gibt nur wenige Ausnahmen, in denen eine Instanz eine anderen Instanz aufrufen darf. Insbesondere zum Übermitteln von Daten oder Schaltbefehlen zu anderen selbst erstellten Instanzen muss der offizielle Datenfluss genutzt werden. Eine andere Instanz darf nur angesprochen werden, wenn der Benutzer diese explizit im Konfigurationsformular ausgewählt hat. (z.B. wie im Shutter Control oder im USB Mapper (https://github.com/paresy/SymconMisc/blob/master/USBMapper/module.php), wo der Benutzer die zu verändernde Instanz angibt).
Eine Instanz darf nur Objekte direkt unterhalb sich selbst verändern. Es ist niemals erlaubt z.B. andere Variablen von anderen Instanzen über SetValue zu verändern. Sollten weitere Instanzen unterhalb dieser Instanz platziert worden sein (Misachtung von Punkt 6.1) kann diese Instanz und alles unterhalb ebenfalls nicht verändert werden. Weiteres Beispiel: Ein Splitter darf niemals die Variablen der verknüpften Instanzen verändern. Dazu ist der Datenfluss zu verwenden.


Usability

Eine Instanz sollte Objekte nur direkt unter sich selbst erstellen. Weitere Verschachtelungen sind z.B. für die mobile Ansicht problematisch und sollten vermieden werden.
Das Verlinken von Objekten unterhalb einer Instanz sollte, seit dem Vorhandensein der Listen, nicht mehr verwendet werden.
Vorhandene Schaltmöglichkeiten (PHP-Befehle) sollten so gut wie möglich über den Aktionsbereich im Konfigurationsformular getestet werden können.


Dokumentation

Im Hauptverzeichnis sollte eine README vorhanden sein, welche auf die in der Bibliothek vorhandene Module mit einer kleinen Beschreibung verweist. (Beispiel: https://github.com/paresy/SymconMisc)
Für jedes Modul sollte eine README vorhanden sein, welche mindestens folgende Punkte enthält

Funktionsumfang, welches erklärt was dieses Modul überhaupt kann
Voraussetzungen, z.B. die IP-Symcon Version
Kompatibilität, z.B. welche Geräte unterstützt werden
Die Modul-URL z.B. zu GitHub
Einstellmöglichkeiten der Konfigurationsseite
Exportiere PHP-Befehle


Style Guide

Um die Formatierung vom Code so konsistent wie möglich zu gestalten, sollte der PHP-CS-Fixer mit den Regeln aus folgendem Repository verwendet werden: https://github.com/symcon/StylePHP. Über GitHub Actions kann dies als Check vollautomatisch verifiziert werden: https://github.com/symcon/SymconStubs/blob/master/.github/workflows/style.yml


Automatisierte Tests

Unser Symcon Stubs Repository (https://github.com/symcon/SymconStubs) bietet eine gute Grundlage, um Module automatisiert zu testen. Insbesondere eine Basis-Validierung prüft die library.json und module.json der einzelnen Module und wird sehr empfohlen. (Beispiel: https://github.com/symcon/SymconStubs/blob/master/tests/CoreStubsValidationTest.php). Über GitHub Actions kann dies als Check vollautomatisch geprüft werden: https://github.com/symcon/SymconStubs/blob/master/.github/workflows/tests.yml