Bitte Dokumentation bewerten

[Linuchs]

Liebe Forum-Teilnehmer,

ich habe erstmalig eine API geschrieben und die Anwendung dokumentiert.

Es geht um die Integration von Kalenderdaten in das eigene HTML-Dokument. Das Verfahren mit iframe wird häufig genutzt, ich möchte den Teilnehmern die API schmackhaft machen.

Belastet meinen Server weniger, da nur eine CSV-Datei ausgegeben wird statt einer kompletten HTML-Seite.

Könnt ihr bitte das Kapitel 4. Kalender mit PHP selbst gestalten lesen und rückmelden, ob es gut verständlich ist?

Danke.

Linuchs

[Auge]

Hallo

Könnt ihr bitte das Kapitel 4. Kalender mit PHP selbst gestalten lesen und rückmelden, ob es gut verständlich ist?

• „Der "Zugriff auf entfernte Dateien" (allow_url_fopen) muss erlaubt sein.“ Soll es nur Zugriff auf diesem Wege geben? Ich vermute dass der Zugriff über CURL oder file_get_contents (funktioniert auch nur, wenn allow_url_fopen erlaubt ist) ebenfalls funktioniert. Es wird ja nur eine URL aufgerufen. Wenn ja, sollten auch die anderen Zugriffsarten dokumentiert werden.
• Erkläre dem Leser bitte, was bei „speichere sie als remso_api_csv.php im include-Verzeichnis deines Servers.“ das include-Verzeichnis des Servers ist.
• Dokumentiere bitte die möglichen URL-Parameter der Anfrage und welche Werte bzw. Wertebereiche erlaubt sind. Dokumentiere ebenfalls die Vorgabewerte der Parameter, so welche vorhanden sind, nicht nur in einem Code-Kommentar (z.B. in „Schritt 3“ der Parameter „posi“ mit dem Vorgabewert „10“).

Tschö, Auge

[chorn]

Auf mich wirkt das eher unbeholfen. Da ist halt viel "Geschwafel", zumindest für jemanden der schonmal mit APIs gearbeitet hat. Ich sehe erstmal nicht, wo diese remso_api_csv.php herkommen soll, wird erst ganz unten verlinkt. Und warum muss ich die umbenennen? Rechtsklick => speichern unter, oder entsprechende header mitsenden ist praktischer, auch deswegen:

Datei ".$url." kann **nicht** geöffnet werden.

Ausserdem verschmutzen die Funktionen meinen globale Scope. PHP sollte auch immer mit <?php explizit eingeläutet werden, sonst gibts Kompatibilitätsprobleme. Und wenn abstrahiert, dann echte Funktionen bereitstellen, mit echten Parametern, und nicht nur irgendwas das eine URL entgegennimmt. Schlimmer noch: deine Beispiele sind kaputt

$$arr_felder

Der Profi würde das dann noch auf GitHub, ggf. sogar per Composer bereitstellen ;)

[Matthias Apsel]

Hallo chorn,

$$arr_felder

Variable Variablen?

Bis demnächst
Matthias

[chorn]

grundsätzlich ja, aber

Notice: Undefined variable: arr_felder

wenn man es wie im Beispiel macht.

[Julius]

Hallo chorn, @Linuchs

Auf mich wirkt das eher unbeholfen. Da ist halt viel "Geschwafel", zumindest für jemanden der schonmal mit APIs gearbeitet hat.

Also vielleicht lieber eine Kurz-Version mit Beispiel und dazugehöriger Ausgabe und dann eine ausführlichere Version für die, die es ausführlicher haben wollen.

Ausserdem verschmutzen die Funktionen meinen globale Scope.

Dagegen dürfte Objektorientierung helfen, beispielsweise so:

// Datei mit der passenden includen:
require('RemsoKalender.php');

$kalender = new RemsoKalender();
$kalender->loadFromURL('http://example.org');
$kalender->setTemplate('<tr><td>[titel]</td><td>[datum]</td></tr>');
while($kalender->hasEntries())
{
  echo $kalender->render();
}

Vielleicht solltest du die Daten (auch) als JSON übertragen, das ist besser standardisiert, verbereiteter und vor allem leichter zu parsen als CSV. In PHP gibt es auch gleich passende Funktionen.

Außerdem wäre eine Flexibilisierung schön, wenn deine Funktionen beispielsweise auch optional ein Array zurückgeben können. Beispielsweise könnte jemand auf seine andere Template-Engine (z. b. Mustache oder Twig) als auf deine setzen wollen.

Außerdem solltest du vielleicht einen Cache implementieren, damit nicht bei jedem Skript-Aufruf die Daten von dir geholt werden, sondern vielleicht für 5 - 10 Minuten auf dem Server des Nutzers deines Skripts zwischengespeichert wird. Das senkt die Belastung deines Servers und erhöht die durchschnittliche Auslieferungsgeschwindigkeit der Seite, da PHP nicht immer erst auf die Daten von deinem Server warten muss. Dann sollte die Erneuerung des Chaches vielleicht auch so gehandhabt werden, dass bei einer fälligen Erneuerung erst die Daten von deinem Server geholt werden und erst bei erfolgreichem Download der Cache überschrieben wird. So sorgst du dafür, dass die von anderen Seiten eingebundenen Kalender auch dann noch funktionieren, wenn deine Seite mal kurz nicht funktionieren sollte. Dass die Daten, die der Nutzer in dem Fall zu Gesicht bekommt, dann ein paar Minuten älter sind, ist besser als eine Fehlermeldung.

PHP sollte auch immer mit <?php explizit eingeläutet werden, sonst gibts Kompatibilitätsprobleme.

Das <? verträgt sich beispielsweise nicht mit XML und PHP parallel. Außerdem kann es sein, dass auf die Servern der Nutzer so konfiguriert wurden, dass PHP nicht auf <? reagiert.

Und wenn abstrahiert, dann echte Funktionen bereitstellen, mit echten Parametern, und nicht nur irgendwas das eine URL entgegennimmt.

@chorn Meinst du, dass das die Funktion einen Dateihandler oder direkt den Inhalt statt der URL entgegennehmen soll?

Gruß
Julius

[chorn]

ich meine, dass ich der Funktion erstmal einfach sagen kann was ich haben will, und die konkrete URL wegabstrahiert wird

function get_data($VIP, $lang = 'de', $format = 'csv', ...){}

wobei dein OOP natürlich zu bevorzugen ist.

[Julius]

Hallo chorn,

ich meine, dass ich der Funktion erstmal einfach sagen kann was ich haben will, und die konkrete URL wegabstrahiert wird

function get_data($VIP, $lang = 'de', $format = 'csv', ...){}

Danke, ich verstehe jetzt, was du meinst. Das ist sehr elegant, sollte auch in der Klasse so gemacht werden – die komplette URL kann man fest in der Klasse verdrahten, weil die ja sowieso Remso-Spezifisch sein wird.

Gruß
Julius

[Linuchs]

Hallo chorn,

erstmal danke für die investierte Zeit.

remso_api_csv.php herkommen soll, wird erst ganz unten verlinkt. Und warum muss ich die umbenennen?

Eine *.php Datei kann man nicht herunterladen, der Server versucht, sie zu interpretieren. Deshalb heisst sie remso_api_csv.php.txt

Rechtsklick => speichern unter,

Danke, habe ich als Erklärung eingebaut.

Datei ".$url." kann **nicht** geöffnet werden.

Beim Download der remso_api_csv.php.txt?

Ausserdem verschmutzen die Funktionen meinen globale Scope.

Bitte näher erläutern.

PHP sollte auch immer mit <?php explizit eingeläutet werden, sonst gibts Kompatibilitätsprobleme.

Habe ich korrigiert.

Und wenn abstrahiert, dann echte Funktionen bereitstellen, mit echten Parametern,

Also echter geht's doch nicht. Eine Dokumentation, die sich "life" Beispiele zieht uhd anzeigt.

und nicht nur irgendwas das eine URL entgegennimmt.

Nicht verstanden, was du damit sagen willst.

Schlimmer noch: deine Beispiele sind kaputt

$$arr_felder

Schönheitsfehler, tritt in einem Kommentar auf.

Der Profi würde das dann noch auf GitHub, ggf. sogar per Composer bereitstellen ;)

Ich schrieb ja, dass ich das zum ersten Mal mache. Kannst du Tipps geben?

Danke.

Linuchs

[chorn]

zu 1. bau dir nen Wrapper, der die richtigen Header für einen Dateidownload setzt und dann den eigentlichen PHP-String aus einer anderen Datei durchleitet. Für das Umbenennen sehe ich erstmal keine Notwendigkeit. Dann kannst du nämlich für 2. auch content-type inkl. charset setzen und mein Browser zeigt keine Grütze an die dann auch noch mit falschen Sonderzeichen in meiner Datei landet.

<?php

header('content-type: ... ; charset: ...');
readfile('quellcode.phps');

zum Scope siehe Anwort von @Julius bzgl. das in eine Klasse zu packen, ggf. mit Namespaces.

Mit Parametern meine ich sowas hier

function get_data($VIP, $lang = 'de', $format = 'csv', ...){}

sich da selbst eine URL zusammenzukleben macht m.M.n. keinen Sinn wenn deine App bestimmte Parameter einfach erwartet ohne die sie nicht funktioniert. Dann lieber gleich schön verpacken, dann gibt's auch gleich Fehlermeldungen beim Einbinden. Siehe dazu nochmal den Hinweis auf die Klasse von @Julius.

Es ist kein Schönheitsfehler wenn es einen Parseerror erzeugt :) für mich jedenfalls nicht, und die Leute die das einbinden wollen werden auch erstmal grimmig gucken, dass du kaputte Beispiele lieferst. Das sind erstmal meine Tipps.

[Camping_RIDER]

Aloha ;)

zu 1. bau dir nen Wrapper, der die richtigen Header für einen Dateidownload setzt und dann den eigentlichen PHP-String aus einer anderen Datei durchleitet. Für das Umbenennen sehe ich erstmal keine Notwendigkeit. Dann kannst du nämlich für 2. auch content-type inkl. charset setzen und mein Browser zeigt keine Grütze an die dann auch noch mit falschen Sonderzeichen in meiner Datei landet.

Es geht eventuell noch einfacher - heute erst gelernt:

<a href="/PFAD/remso_api_csv.php.txt" download="remso_api_csv.php">…</a>

Wenn man nicht grad mit einem IE daherkommt sollte das genügen.

Grüße,

RIDER

[Julius]

Hallo Linuchs,

remso_api_csv.php herkommen soll, wird erst ganz unten verlinkt. Und warum muss ich die umbenennen?

Eine *.php Datei kann man nicht herunterladen, der Server versucht, sie zu interpretieren. Deshalb heisst sie remso_api_csv.php.txt

Du kannst den Webserver anweisen, in bestimmten Verzeichnissen (beispielsweise den „Downloads“-Ordner) keine php-Dateien durch den PHP-Interpreter zu jagen.

Datei ".$url." kann **nicht** geöffnet werden.

Beim Download der remso_api_csv.php.txt?

Ja, mein Browser interpretiert die als ISO-irgendwas statt UTF-8. Alternativen:

• Dateien in ein ZIP-Archiv packen (als Bonus kannst du ein paar Beispiel-Dateien und eine separate readme.txt beifügen), würde ich so machen
• PHP-Code als HTML-Datei in ein pre packen und dann mit Copy ’n’ Paste arbeiten.

Ausserdem verschmutzen die Funktionen meinen globale Scope.

Bitte näher erläutern.

Du erzeugst Variablen, die mit anderen Variablen im Programm kollidieren können. Objektorientierung würde das alles in ein Objekt packen und damit die Kollisionsgefahr verringern – und damit letztlich auch die Wiederverwendbarkeit deines Codes verbessern.

Der Profi würde das dann noch auf GitHub, ggf. sogar per Composer bereitstellen ;)

Ich schrieb ja, dass ich das zum ersten Mal mache. Kannst du Tipps geben?

GitHub ist zu empfehlen, weil…

• Nutzer sich deine Dateien mit Syntax-Highlighting anschauen können
• GitHub auch einen „Download als Zip“-Button bereitstellt
• Nutzer können mit einem GitHub-Account ganz unkompliziert Fehler melden und Änderungsvorschläge einreichen, die du per Klick übernehmen kannst
• Entwickler sind GitHub gewohnt
• durch die Versionskontrolle können Änderungen an deinem Code leicht nachverfolgt werden

Composer ist praktisch ein Paketmanagement (wie apt) für PHP.

Gruß
Julius

[chorn]

GitHub auch einen „Download als Zip“-Button bereitstellt

und Raw-Download mit UTF-8 Headern :)

[Julius]

Hallo chorn,

GitHub auch einen „Download als Zip“-Button bereitstellt

und Raw-Download mit UTF-8 Headern :)

Stimmt, man kann dem Webserver (meist ja ein Apachen) bestimmt auch beibringen, dass er plain-Textdateien immer als UTF-8 ausliefern soll. Wenn man dann nur UTF-8-Dateien auf dem Server bzw. im betreffenden Verzeichnis hat, ist das die eleganteste Lösung.

Gruß
Julius

[TS]

Hello,

Eine *.php Datei kann man nicht herunterladen, der Server versucht, sie zu interpretieren. Deshalb heisst sie remso_api_csv.php.txt

im Downloadverzeichnis eine .htaccess ablegen mit dem Inhalt

php_flag engine off

Dann kannst Du in dem Verzeichnis auch PHP-Dateien zum Download anbieten.

Liebe Grüße
Tom S.

[dedlfix]

Tach!

im Downloadverzeichnis eine .htaccess ablegen mit dem Inhalt

php_flag engine off

Geht nur, wenn PHP als Apache-Modul eingebunden ist. Das will man nur auf einem Server, der sonst keine Webanwendung nebenher laufen hat.

Zielführender ist es, die Endung .php in diesem Verzeichnis nicht an den PHP-Handler weiterzureichen. Wie das auszuklammern geht, kann man nicht pauschal sagen, sondern muss zu der individuellen Konfiguration passen, wie .php an den konkret verwendeten PHP-Handler geleitet wird.

dedlfix.

[RR]

Hallo,

da könnte (beim Apachen) die Direktive RemoveHandler helfen.

LG
Robert R

[dedlfix]

Tach!

da könnte (beim Apachen) die Direktive RemoveHandler helfen.

Ja, das ist eine der Möglichkeiten. Aber auch RemoveType kann infrage kommen. Und ich sehe auch grade, dass beim Entfernen nur die Extension angegeben werden muss. Beim Hinzufügen muss man neben der Extension auch noch den genauen Namen des Handlers wissen. Dann ist das Wegkonfigurieren doch einfacher als ich erst angenommen hatte.

Eine <Files>- oder <FilesMatch>-Sektion zusammen mit SetHandler none, falls es mit Set/AddHandler konfiguriert wurde, wäre auch noch eine Möglichkeit.

dedlfix.

[Auge]

Hallo

Auf mich wirkt das eher unbeholfen. Da ist halt viel "Geschwafel", zumindest für jemanden der schonmal mit APIs gearbeitet hat.

Die Doku wendet sich an „Webmaster“ und nicht an „richtige“ Programmierer. Der Sprachstil kann zwar tatsächlich etwas gestrafft werden, aber grundsätzlich würde ich aufgrund des (vermutlichen) Zielpublikums nicht einen so hohen Maßstab ansetzen.

Der Profi würde das dann noch auf GitHub, ggf. sogar per Composer bereitstellen ;)

Kann man machen, muss man aber nicht.

Tschö, Auge

[pl]

Verständlich schon aber ziemlich umständlich. CORS könnte die Sache erheblich vereinfachen und in Verbindung mit einer geeigneten TemplateEngine bräuchte der Anwender nur noch ein Template zu gestalten. MfG

[Julius]

Hallo pl,

Verständlich schon aber ziemlich umständlich. CORS könnte die Sache erheblich vereinfachen

Das ist PHP, die Same Origin Policy ist hier nicht relevant.

und in Verbindung mit einer geeigneten TemplateEngine bräuchte der Anwender nur noch ein Template zu gestalten.

Ein Template und die dazu passende Template-Engine hat er doch bereits:

<div class="position">
  <p>[wochentag], [tt].[mm].   [hh]:[mi]<br>
  <a href="http://remso.eu/?TID=[TID]" title="TID=[TID]">[titel]</a></p>
  <p>[land_kz]-[ort_plz] [ort_name]<br>
  gemeldet von [melder]</p>
</div>

Gruß
Julius

[pl]

Das ist PHP, die Same Origin Policy ist hier nicht relevant.

Ja.

Ein Template und die dazu passende Template-Engine hat er doch bereits:

Ja.

Und nun? Guckst Du Dir am Besten noch einmal meinen Vorschlag an, der eine Alterntive Lösung beschreibt, die für den Anwender wesentlich einfacher zu verstehen und umzusetzen ist ohne in serverseitige Prozesse eingreifen zu müssen was auch ein explizites Download und die Installation von PHP Skriptn überflüssig macht.

In Fakt würde der Anwender lediglich ein Template (nicht PHP sondern Javascript) in seine eigene Seite einbauen, was der beliebig gestalten kann. Er muss dazu nur die Namen der Platzhalter kennen.

MfG

[JürgenB]

Hallo,

In Fakt würde der Anwender lediglich ein Template (nicht PHP sondern Javascript) in seine eigene Seite einbauen, was der beliebig gestalten kann. Er muss dazu nur die Namen der Platzhalter kennen.

das geht auch noch einfacher: im HTML ein Platzhalterelement und dann dem Javascript beim Aufrufen dessen ID sowie die weiteren Informationen als Parameter mitgeben:

<section id="Kalender"></section>
<script src="https://.../Kalender.js?id=Kalender;VIP=603;zp=p591b;lg=de;posi=25"></script>

Gruß
Jürgen

[pl]

Ja 😉

Wenn man lange genug darüber nachdenkt geht so ziemlich alles einfacher zu machen. Schon allein die Themenstellung "Bitte Dokumentation bewerten" zeigt ja, dass nachgedacht wird und auch alternative Vorschläge hierzu passen. Der Anwender muss ja schließlich auch nachdenken und da kommts auch darauf an, wie weit er dazu willig ist und was er selbst dazu einbringen kann. Ich meine, beim Thema API kommts darauf an, es dem Anwender so einfach wie möglich zu machen. Ein PHP-Script-Download passt da nicht so richtig.

MfG