ChurchTools bietet für den Datenaustausch eine REST-API an. Für die Verwendung der API in Programmcode sind allerdings viele immer wieder gleiche Schritte notwendig. HTTP-Anfrage senden, Status Code der Antwort prüfen, Daten parsen, prüfen ob alle Felder da sind und schließlich hat man die eine ID gefunden, die man sucht um mit dieser dann die nächste Anfrage zu starten.

Um diesen Aufwand bei der Verwendung der ChurchTools REST-API zu verringern, haben wir den ChurchTools-API Client für die Programmiersprache PHP entwickelt. Anstatt sich durch undurchsichtige Datenstrukturen zu wühlen kannst du damit direkt mit Objekten interagieren:

https://github.com/5pm-HDH/churchtools-api

Der Wrapper kann über Composer in deinem Projekt installiert werden. Siehe hierfür den Abschnitt Installation:

composer require 5pm-hdh/churchtools-api

Zunächst konfigurierst du deine ChurchTools Instanz und deine Zugangsdaten. Ich würde dir empfehlen dafür einen eigenen „API-Account“ anzulegen, dem du nur reduzierte Zugangsberechtigungen erteilst.

use \CTApi\CTConfig;

    //setzte URL deiner ChurchTools Instanz
    //Wichtig! ApiUrl muss eine Top-Level-Domain sein. Keine Pfade erlaubt.
CTConfig::setApiUrl("https://example.church.tools");

    //authentifiziere den Wrapper über E-Mail und Passwort
CTConfig::authWithCredentials(
    "example.email@gmx.de",
    "myPassword1234"
);

Das war bereits der gesamte Konfigurationsaufwand und schon kann es losgehen…

Beispiel: Personen abrufen

Der Wrapper bestehst aus zwei Arten von Klassen:

• Request: Über einen Request werden Anfragen an die ChurchTools-API versendet und empfangen. Zum Beispiel PersonRequest, EventRequest,
• Models: Repräsentieren die Daten und kapseln diese in ein Objekt. Wenn zum Beispiel über den PersonRequest alle Mitglieder abgerufen werden, ist jedes Mitglied in einem Person-Objekt (Model) gespeichert.

In folgendem Beispiel werden Personen-Daten aus ChurchTools über die Request-Facade abgerufen:

use CTApi\Requests\PersonRequest;

// abruf des eigenen Benutzer-Profils
$myself = PersonRequest::whoami();
echo "Hello ".$myself->getLastName() . $myself->getFirstName();

// rufe all verfügbaren Personen ab
$allPersons = PersonRequest::all();

// filter die Daten mit Where-Filter
$teenager = PersonRequest::where('birthday_before', '2007-01-01')
                    ->where('birthday_after', '2003-01-01')
                    ->orderBy('birthday')
                    ->get();
                    
foreach($teenager as $teenPerson){
    echo "Hello Teenager with E-Mail: ".$teenPerson->getEmail();
}

// Rufe spezifische Person mit ID "21" ab.
$personA = PersonRequest::find(21);     // returns "null", wenn Id ungültig
$personB = PersonRequest::findOrFail(22); // throws exception, wenn Id ungültig

Vielleicht auch interessant für dich: Code-Beispiel für Event-API https://github.com/5pm-HDH/churchtools-api#example-event-api

Request Facade vs. Request Builder

Intern arbeitet die Request Facade mit einem Builder-Pattern. Die Request-Builder sind ebenfalls, in den Models integriert und werden dort als „request“-Methoden zur Verfügung gestellt.

In folgendem Beispiel ist die Dienstzusage in $eventService Ausgangspunkt. Über die PersonRequest Facade kann die dazugehörende Person abgerufen werden. Einfacher ist es allerdings die Person über die „request“-Methode requestPerson abzurufen:

use CTApi\Models\EventService;
use CTApi\Requests\PersonRequest;

// Abruf der Person für Dienst über Facade
$eventService = /* ... */;
if($eventService->getPersonId() != null){
   $person = PersonRequest::find($eventService?->getPersonId());
}else{
   $person = null;
}

// Abruf der Person über Builder
$eventService = /* ... */;
$person = $eventService->requestPerson();

Dank dem Null-safe operator können mehrere „request“-Methoden hintereinander verwendet werden ohne, dass geprüft werden muss ob das Ergebnis null ist. Der Null coalescing operator (siehe die beiden Fragezeichen) prüft, ob das Ergebnis null ist. Wenn ja, wird ein leerer Array zurückgegeben:

// Abruf über Request-Builder (Null safe)
$eventService = /* ... */;
$personGroups = $eventService->requestPerson()?->requestGroups() ?? [];

Ein anderer Vorteil ergibt sich, wenn über die Request-Methode mehrere Objekte geladen werden (zu erkennen am Plural der Request-Methode z.B. requestSongs). Dann können zusätzlich auch Where-Filter und OrderBy-Kriterien angewendet werden:

$eventAgenda = /* ... */;

$songs = $eventAgenda->requestSongs()
      ->where('practice', true)
      ->orderBy('key')
      ->get();

Daten ändern

Zusätzlich zum Auslesen der Daten aus ChurchTools können auch Datensätze angelegt und verändert werden. Hierzu stellen die Request-Facaden entsprechende Funktionen zur Verfügung.

Anlegen / Update einer Person (Docs):

use CTApi\Models\Person;
use CTApi\Requests\PersonRequest;

// Person anlegen
$newPerson = new Person();
$newPerson->setFirstName("John")
    ->setLastName("Doe")
    ->setBirthName("Smith");
//add further attributes

PersonRequest::create($newPerson);

// Person editieren
$person = PersonRequest::findOrFail(21);
$person->setEmail('new-mail@example.com');

PersonRequest::update($person);

Personen zu Gruppe hinzufügen / entfernen (Docs):

use CTApi\Requests\GroupMemberRequest;

$groupId = 21;
$personId = 221;

// Create Group-Membership
$groupMember = GroupMemberRequest::addMember($groupId, $personId);

// Update Group-Membership
$groupMember->setComment("Add User via CT-Api.");
GroupMemberRequest::updateMember($groupId, $groupMember);

// Delete Group-Membership
GroupMemberRequest::removeMember($groupId, $personId);

Dateianhänge herunterladen / hochladen (Docs):

use CTApi\Models\File;
use CTApi\Requests\FileRequest;

// FileRequest-Typen:
FileRequest::forAvatar(21);
FileRequest::forGroupImage(21);
FileRequest::forLogo(21);
FileRequest::forAttatchment(21);
FileRequest::forHtmlTemplate(21);
FileRequest::forEvent(21);
FileRequest::forSongArrangement(21);
FileRequest::forImportTable(21);
FileRequest::forPerson(21);
FileRequest::forFamilyAvatar(21);

// Download File
$files = FileRequest::forAvatar(21)->get();

// Upload File
$newFile = FileRequest::forAvatar(21)->upload(__DIR__ . "/resources/avatar-1.png");

Umfang und Abdeckung

Der ChurchTools-API Client deckt einen Großteil der ChurchTools REST-API ab. Dazu zählen unter anderem…

• … Personen und Gruppen
• … Gruppen-Homepages
• … Kalender
• … Resourcen und Buchungen
• … Events und Dienste
• … Abwesenheiten
• … Song-Bibliothek (CCLI-Integration)
• … Wiki
• … Dateien (Anhänge, Avatar, Bilder, …)
• … Globale Suche

Eine Liste aller verfügbaren Requests und Models sind in den Docs enthalten:

https://github.com/5pm-HDH/churchtools-api#requests-and-models

Wenn du Vorschläge und Feature Requests hast oder Bugs findest, stell gern einen Issue auf GitHub ein oder schreibe mir direkt eine Mail.

Ich freue mich über dein Feedback!