ezjscore-JSON-Endpunkte in PHP #

Diese Seite richtet sich an PHP-Entwickler, die ihrem eigenen JavaScript Daten oder Aktionen über HTTP bereitstellen: Autovervollständigung, Zähler, kleine Speichervorgänge. ezjscore (extension/ezjscore) ruft eine registrierte statische PHP-Methode auf und antwortet in JSON, XML oder Text. Die JavaScript-Seite und ein erstes Beispiel finden Sie unter JSON-Endpunkte mit ezjscore.

Inhalt #

1. Wie ein Aufruf Ihre Methode erreicht
2. Die Klasse registrieren
3. Die Methode
4. Berechtigungen
5. Schreibvorgänge
6. Mehrere Aufrufe in einer Anfrage
7. expservices: die strukturierte Form
8. Testen

Wie ein Aufruf Ihre Methode erreicht #

<root>/ezjscore/call/<name>::<function>[::<arg>[::<arg>...]]?ContentType=json

Der Router ezjscServerRouter (extension/ezjscore/classes/ezjscserverrouter.php) lehnt jeden Namen ohne Block [ezjscServer_<name>] ab, ruft <class>::<function>( array $args ) mit den durch :: getrennten Argumenten als Strings auf und verpackt den Rückgabewert:

{"error_text": "", "content": <what your method returned>}

Das Format folgt dem Header Accept oder ?ContentType=json|xml|text. Der Kernel liefert einen Testaufruf mit: <root>/ezjscore/call/ezjsc::time.

Die Klasse registrieren #

extension/acmereport/settings/ezjscore.ini.append.php:

<?php /* #?ini charset="utf-8"?
[ezjscServer_acmereport]
Class=acmeReportServerFunctions
Functions[]=acmereport
RequirePolicy=enabled
*/ ?>

Die Kommentare von [ezjscServer] in extension/ezjscore/settings/ezjscore.ini beschreiben jeden Schlüssel. Fügen Sie Ihren Eintrag zu [ezjscServer] FunctionList[] hinzu, wenn Sie Functions[] verwenden.

Die Methode #

<?php
class acmeReportServerFunctions
{
    /**
     * acmereport::count::<status>
     *
     * @param array $args the ::-separated arguments, as strings
     * @return array
     */
    public static function count( $args )
    {
        $access = eZUser::currentUser()->hasAccessTo( 'acmereport', 'read' );
        if ( $access['accessWord'] === 'no' )
            throw new Exception( 'Access denied' );

        $status = isset( $args[0] ) ? (string)$args[0] : '';
        if ( !in_array( $status, array( 'open', 'closed' ), true ) )
            throw new Exception( 'Unknown status' );

        return array( 'count' => (int)eZPersistentObject::count( acmeReportItem::definition(),
                                                                 array( 'status' => $status ) ) );
    }
}

• Jedes Argument ist ein String aus der URL: Casten Sie es und prüfen Sie es gegen eine Allow-Liste.
• Geben Sie Daten zurück (Arrays, Zahlen, Strings), kein HTML. Wenn Sie Markup zurückgeben müssen, maskieren Sie es.
• Eine Exception wird zum error_text der Antwort; halten Sie ihre Meldung frei von Interna.

Berechtigungen #

ezjscore/call prüft von sich aus keine Richtlinie für Ihre Funktion. Verwenden Sie beide Ebenen:

1. Functions[] mit RequirePolicy=enabled im Block, sodass ein Benutzer ohne die Richtlinie ezjscore/call für Ihren Eintrag abgelehnt wird, bevor Ihr Code läuft.
2. Eine Prüfung innerhalb der Methode auf die Modulrichtlinie, zu der die Daten gehören (hasAccessTo(), canRead() bei Knoten).

Schreibvorgänge #

Eine Methode, die Daten ändert, muss alles außer POST ablehnen und sich auf das Formular-Token verlassen:

if ( $_SERVER['REQUEST_METHOD'] !== 'POST' )
    throw new Exception( 'POST required' );
$http = eZHTTPTool::instance();
$title = trim( (string)$http->postVariable( 'title', '' ) );

Für angemeldete Benutzer prüft ezformtoken das Token bei jedem POST, bevor der Router läuft: Das JavaScript sendet es als Feld ezxform_token oder als Header X-CSRF-Token (CSRF-Schutz und ezformtoken).

Mehrere Aufrufe in einer Anfrage #

Ein POST von ezjscServer_function_arguments mit mehreren durch @SEPARATOR$ verbundenen Aufrufen führt sie in einer Anfrage aus. Jeder Aufruf wird wie ein einzelner geprüft.

expservices: die strukturierte Form #

Für Dienste, die Skripte, Apps und andere Frontends aufrufen (nicht nur Ihre eigenen Seiten), baut die Erweiterung expservices auf demselben Router auf, mit einer Klasse pro Domäne, die expServiceBase erweitert, einer deklarierten Liste public static $services, Auffindbarkeit (expservices::catalog), einer festen Hülle ({"ok": true, "data": ...}), Paging, Fehlercodes, API-Tokens und einem Audit-Ereignis für jeden Schreibvorgang (Backend-Dienste über ezjscore):

class expFooServices extends expServiceBase
{
    public static $services = array(
        'bar' => array( 'summary' => '...', 'access' => array( 'content', 'read' ),
                        'write' => false, 'args' => array( 'node_id' => 'int' ), 'returns' => '...' ) );

    public static function bar( $args )
    {
        self::guard( __FUNCTION__ );
        $node = self::node( self::arg( $args, 0, 'int' ) );
        return self::ok( array( 'name' => $node->attribute( 'name' ) ) );
    }
}

Deklarieren Sie $services als Wert der Eigenschaft im Klassenrumpf, niemals durch eine Zuweisung nach der Klasse: Ein persistenter Velocity-Worker setzt statische Eigenschaften zwischen Anfragen auf ihre deklarierten Werte zurück, und eine Zuweisung außerhalb der Klasse läuft nicht erneut (Fallen durch statischen Zustand).

Testen #

curl -s 'https://www.example.com/ezjscore/call/acmereport::count::open?ContentType=json'
php vendor/bin/phpunit tests/tests/extension/expservices/

Testen Sie die Methode selbst in einem Test ohne Datenbank, indem Sie sie mit einem Argument-Array aufrufen.

Verwandte Seiten #

• Referenz der ezjscore-Serverfunktionen
• Ajax mit ezjscore-Serverfunktionen
• REST und entfernte Dienste aus PHP
• Freie Dokumentation: diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.