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（ChurchTools客户端）。

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之上。请求通过添加过滤、分页和排序来指定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请求。

对于集成测试，请求将直接发送到ChurchTools实例。“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 成员列表管理 由 @stollr 提供：此应用程序是为基督教教会 Evangeliums-Christengemeinde e.V. 编写的，其主要目的是管理其成员并生成可打印的成员列表。

Wordpress 插件

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

其他应用

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

5pm-hdh / churchtools-api

维护者

详细信息