README

ChurchTools-API客户端是基于PHP的ChurchTools API包装器，已与ChurchTools版本3.104.3进行了测试。

注意

已发布版本2，具有重构的代码库和许多新功能。如果您从版本1升级到2，请参阅升级指南。

安装

前往项目根目录，使用composer安装ChurchTools-API

composer require 5pm-hdh/churchtools-api

使用以下代码将所有依赖包加载到PHP项目中

<?php

include_once 'vendor/autoload.php';

用法

在您开始从API请求数据之前，您需要使用CTConfig接口配置CT-Client（教堂工具客户端）

use \CTApi\CTConfig;

    //set the url of your ChurchTools application api
    //important! ApiUrl must end with Top-Level-Domain. No paths allowed!
CTConfig::setApiUrl("https://example.church.tools");

    //authenticates the application and load the api-key into the config
CTConfig::authWithCredentials(
    "example.email@gmx.de",
    "myPassword1234"
);

// Multi-factor authentication:
CTConfig::authWithCredentials(
    "example.email@gmx.de",
    "myPassword1234",
    "291521"
);

有关更多信息，请访问CTConfig文档从现在起，所有ChurchTools-API功能均可用。

请求和模型

整个ChurchTools-API客户端都是建立在Requests和Models之上的。Requests提供了一种通过添加筛选、分页和排序来指定API调用的接口。模型代表请求检索的数据。更多详细信息请参阅文档。

所有API及其示例

以下简要示例展示了ChurchTools-API客户端的功能，并对其潜在用途提供了概述。

示例：Person-API

use CTApi\Models\Groups\Person\PersonRequest;

$myself = PersonRequest::whoami();
echo "Hello ".$myself->getLastName() . $myself->getFirstName();

// Retrieve all Persons
$allPersons = PersonRequest::all();

// Filter Data with Where-Clause
$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();
}

// Get specific Person
$personA = PersonRequest::find(21);     // returns "null" if id is invalid
$personB = PersonRequest::findOrFail(22); // throws exception if id is invalid

示例：Event-API

use CTApi\Models\Events\Event\EventAgendaRequest;use CTApi\Models\Events\Event\EventRequest;

// Retrieve all events
$allEvents = EventRequest::all();

// Get specific Event
$event = EventRequest::find(21);     // returns "null" if id is invalid
$event = EventRequest::findOrFail(22); // throws exception if id is invalid

// Filter events in period
$christmasServices = EventRequest::where('from', '2020-12-24')
                    ->where('to', '2020-12-26')
                    ->orderBy('id')
                    ->get();
  
$christmasService = $christmasServices[0];
  
// get the Agenda with event id...
$eventId = $christmasServices->getId();
$agenda = EventAgendaRequest::fromEvent($eventId)->get();

// ...or direct on event-Model
$agenda = $event->requestAgenda();

// Use Songs-API
$songsOnChristmas = $agenda->getSongs();

foreach($songsOnChristmas as $song){
    echo $song->getTitle() . " - (Key: " .$song->getKey() . ")";
}

示例：Wiki-API

use CTApi\Models\Wiki\WikiCategory\WikiCategoryRequest;

$wikiCategory = WikiCategoryRequest::find(21);

$rootNodeWiki = $wikiCategory->requestWikiPageTree();

echo "<h1>Table of content:</h1>";
echo "<ul class='first-level'>";
    // First Level
foreach($rootNodeWiki->getChildNodes() as $node){
    echo "<li>";
    echo $node->getWikiPage()->getTitle();
    
    echo "<ul class='second-level'>";
    foreach($node->getChildNodes() as $nodeSecondLevel){
        echo "<li>";
        echo $nodeSecondLevel->getWikiPage()->getTitle();
        echo "</li>";
    }   
    echo "</ul>";
    
    echo "</li>";

}
echo "</ul>";

结果

<h1>Table of content:</h1>
<ul class="first-level">
    <li>
        Instruments
        <ul class="second-level">
            <li>Piano</li>
            <li>Guitar</li>
        </ul>
    </li>
    <li>
        Chordsheets
    </li>
    <li>
        Groups
        <ul class="second-level">
            <li>Worship-Teams</li>
            <li>Service-Teams</li>
        </ul>
    </li>
</ul>

支持/贡献

我们欢迎您为此项目提供支持和贡献。

CTLog - 记录请求

CTLog提供了一种记录信息的门面。默认情况下，它在日志文件churchtools-api.log中记录所有重要信息、警告和错误。可以通过方法启用和禁用日志文件的创建。

use CTApi\CTLog;

CTLog::enableFileLog( false ); //disable logfile
CTLog::enableFileLog(); // enable logfile

默认情况下，控制台将显示错误、关键、警报和紧急级别的所有日志。如果您希望在控制台上显示更多日志级别，可以使用CTConfig-Debug选项或在CTLog门面中直接设置。

CTConfig::enableDebug();

//or use CTLog facade

CTLog::setConsoleLogLevelDebug();
CTLog::enableConsoleLog();

要记录一条消息，请使用getLog方法

use CTApi\CTLog;

CTLog::getLog()->debug("Hello World!");
CTLog::getLog()->error("Error accourd here!");

有关CTLog页面的更多信息

错误处理

API包装器提供了自定义异常。更多信息请参阅此页面：错误处理

单元测试和集成测试

要访问单元测试，请导航到“tests/unit”目录。您可以使用标准的PHPUnit\Framework\TestCase来测试代码的小部分，或者使用TestCaseHttpMocked来模拟HTTP请求。

对于集成测试，请求直接发送到教堂工具实例。在“integration-test-data.json”文件中包含所有可用的测试数据场景。所有集成测试都通过Github Actions自动执行。

文档生成器

文档生成器会解析所有文档文件并运行PHP代码示例以验证其有效性。有关更多信息，请参阅此页面：文档生成器

许可证

本项目采用MIT许可证，您可以自由使用或贡献。

展示

为了向您展示ChurchTools-API客户端的潜在用途，这里有一些示例。如果您正在处理一个项目，也请考虑贡献并添加到这个列表中

管理工具

ChurchTools-CLI 由 @5pm-HDH 提供：使用ChurchTools-CLI工具，您可以通过CLI应用程序直接访问您的ChurchTools应用程序实例的数据，使用简单易学的命令。此工具与Windows上的cmd、Mac上的终端和Linux上的bash兼容。
ChurchTools GroupMeetings 由 @a-schild 提供：创建团体会议的ical源
ChurchTools PDF Calendar 由 @a-schild 提供：从churchtools生成PDF月历
ECGPB Member List Administration 由 @stollr 提供：此应用程序是为基督教会Evangeliums-Christengemeinde e.V.编写的，其主要目的是管理其成员并生成可打印的成员名单。

Wordpress插件

ChurchTools WP Calendarsync 由 @a-schild 提供：此wordpress插件将从churchtools日历中的事件导入到wordpress中。
Wordpress Plugin für ChurchTools Anmeldungen 由 @5pm-HDH 提供：使用此Wordpress插件，您可以替换由ChurchTools提供的iFrame登记界面，使用基于模板的自己的方法。

其他应用程序

FreeScout Module 由 @churcholution 提供：使用ChurchTools凭据登录FreeScout并根据组/角色成员资格管理权限。

5pm-hdh / churchtools-api

维护者

详细信息