smadeira/ministry-platform-api

Ministry Platform REST API 的 PHP API 封装器

维护者

详情

github.com/smadeira/ministry-platform-api

源代码

问题

安装: 386

依赖项: 0

建议者: 0

安全: 0

星标: 10

关注者: 6

分支: 7

公开问题: 5

v5.1.0 2022-06-14 14:14 UTC

Requires

MIT 2bc3516d7083d13184d7836ff5d18a03c3b26782

  • Scott Madeira <scott.woop@codeflaretech.com>

This package is auto-updated.

Last update: 2024-09-14 19:25:56 UTC

README

为了支持 Laravel 8，您需要下载 API 封装器的 v5.x 版本。

为了支持 dotenv 4.x（包括 Laravel 7.x），您需要下载 API 封装器的 v4.x 版本。

关于 v3 版本：此 API 封装器已更新以支持 dotenv 版本 3.0（2019 年 7 月）和新的 Ministry Platform oAuth 变更（2018 年春季）。

这是一个用于访问 Ministry Platform (MP) REST API 的 PHP 封装器。本版本已更新以包括 2018 年初推出的新的 oAuth 认证变更。请注意，使用 API 需要了解 MP 数据模型。API 允许您访问数据库中的每个表。您需要自行提取正确的数据（或将正确的数据 POST 到表中），然后进行任何连接。

例如，您可以使用 API 创建组，然后可以使用 API 创建参与者。完成这些操作后，您可以创建 Group Participants 来将您的参与者添加到组中。因为 Group Participants 依赖于组和参与者的 ID，所以添加数据的顺序很重要。

安装

包含包

此包通过 Composer 安装，以下假设您已安装并初始化了 Composer。有关安装 Composer 和创建初始 composer.json 的帮助，请参阅Composer 网站。

要向您的项目添加 Ministry Platform API，只需引入此包

composer require smadeira/ministry-platform-api

或者，您可以直接编辑 composer.json 文件以添加 Ministry Platform API

"require": {
        "php": ">=8.0.0",
        "smadeira/ministry-platform-api": "^5"
    },

更新包

在通过 Composer 包含 API 封装器后，执行 composer update 以下载 API 封装器功能所需的依赖项。

composer update

更新命令将下载所有依赖项（包括 API 封装器代码）到 vendor 目录。完成后，您就可以开始开发了。

注意：定期运行 "composer update" 以下载 API 封装器及其所有依赖项的最新版本是个好主意。这就是 Composer 的美妙之处。它为您管理所有这些，您无需自己处理。

配置

要配置 API 封装器以在您的环境中运行，需要进行一些操作。

连接参数

此包使用 vlucas/phpdotenv 管理配置变量。在您的项目根目录中创建一个 .env 文件，并包含以下内容。确保您使用的是正确的 URI、客户端 ID 和密钥。

# Current System Info
MP_API_ENDPOINT="https://connect.example.com/ministryplatformapi"
MP_OAUTH_DISCOVERY_ENDPOINT="https://connect.example.com/ministryplatform/oauth"
MP_API_SCOPE="http://www.thinkministry.com/dataplatform/scopes/all"

# Data from Ministry Platform API Client
MP_CLIENT_ID="churchapi"
MP_CLIENT_SECRET="4064ec5d-f9e6-secret-code-89406642abc7"
MP_OAUTH_REDIRECT_URL="https://example1.com/oAuth"

加载 API 封装器

在代码顶部，您需要做一些操作以访问 API 封装器。您需要包含自动加载功能并从 .env 文件加载配置设置

以下是一个示例，展示了如何使用 Table API 和存储过程 API 的脚本。

require_once __DIR__ . '/vendor/autoload.php';

use MinistryPlatformAPI\MinistryPlatformTableAPI as MP;
use MinistryPlatformAPI\MinistryPlatformProcAPI as PROC;

// Get environment variables
$dotenv = Dotenv\Dotenv::createUnsafeImmutable(__DIR__);
$dotenv->load();

使用

对于客户端凭据流，使用非常简单。进行身份验证并执行您的请求。
注意：如果您使用 Laravel 和授权代码流，请查阅文档文件夹中的 Laravel 文档，以获取工作代码示例。

身份验证

假设您的 .env 参数正确，这将验证您的代码。

// For the Table API enpoints 
$mp = new MP();
$mp->authenticate();    

// For the Procedures API endpoint
$proc = new PROC();
$mp->authenticate();

执行选择查询

API包装器使用与swagger页面相同的语法。您可以定义表格、选择语句、过滤和orderBy子句。这将返回一个事件数组，并将其输出到屏幕。注意，数据使用熟悉的MP品牌SQL，与平台保持一致。

// Get all Approved events happening in the next 30 days that are not cancelled and order by the Event Start Date
$events = $mp->table('Events')
         ->select("Event_ID, Event_Title, Event_Start_Date, Meeting_Instructions, Event_End_Date, Location_ID_Table.[Location_Name], dp_fileUniqueId AS Image_ID")
         ->filter('Events.Event_Start_Date between getdate() and dateadd(day, 30, getdate()) AND Featured_On_Calendar = 1 AND Events.[_Approved] = 1 AND ISNULL(Events.[Cancelled], 0) = 0')
         ->orderBy('Event_Start_Date')
         ->get();
         
print_r($events);

整个脚本

以下是一个获取未来30天内事件的整个脚本。

<?php

require_once __DIR__ . '/vendor/autoload.php';

use MinistryPlatformAPI\MinistryPlatformTableAPI as MP;


// Get environment variables
$dotenv = Dotenv\Dotenv::createUnsafeImmutable(__DIR__);
$dotenv->load();


// Attempt to authenticate to the MP API
$mp = new MP();
$mp->authenticate();

$events = $mp->table('Events')
             ->select("Event_ID, Event_Title, Event_Start_Date, Meeting_Instructions, Event_End_Date, Location_ID_Table.[Location_Name], dp_fileUniqueId AS Image_ID")
             ->filter('Events.Event_Start_Date between getdate() and dateadd(day, 30, getdate()) AND Featured_On_Calendar = 1 AND Events.[_Approved] = 1 AND ISNULL(Events.[Cancelled], 0) = 0')
             ->orderBy('Event_Start_Date')
             ->get();

print_r($events);

使用POST获取

如果您的GET查询字符串太长，您可以通过使用POST动词来绕过长度限制进行GET。postGet()将返回所有符合标准的行（可能是数千行。）

$idList = [385423, 385424];
$sel = "Donation_Date, Donor_ID_Table_Contact_ID_Table.Display_Name, Donation_Amount, Payment_Type_ID_Table.[Payment_Type]";
$filter = "Donation_Date > '2022-05-01' AND Donations.Payment_Type_ID <> 6 and Donations.Domain_ID = 1";

$donations = $mp->table('Donations')
  ->select($sel)
  ->filter($filter)
  ->orderBy('Donation_Amount')
  ->ids($idList)
  ->postGet();

POST新记录

可以通过HTTP POST请求将数据写入数据库。新数据指定在记录中，所有必需字段都必须提供。记录是一个数组数组（二维数组），因此可以在一个API调用中创建多行。注意，即使您只创建一行数据，记录数据也必须是一个二维数组。

此示例将为活动添加两个参与者，每个参与者的状态为02已注册。

// Create the array of records to POST
$rec = [];
$rec[] = ['Event_ID' => 12910, 'Participant_ID' => 46616, 'Participation_Status_ID' => 2];
$rec[] = ['Event_ID' => 12910, 'Participant_ID' => 46617, 'Participation_Status_ID' => 2];

$event = $mp->table('Event_Participants')
		->select("Event_Participant_ID, Event_ID, Participant_ID, Participation_Status_ID")
		->records($rec)			
		->post();

通过PUT更新记录

可以通过HTTP PUT请求更新现有数据。要更新的数据需要行的ID（例如，Event_ID）和要更新的字段。新数据指定在记录中。记录是一个数组数组（二维数组），因此可以在一个语句中执行多个更新。注意，即使您只更新一行数据，记录数据也必须是一个二维数组。此PUT将更新参与状态为03已参加。

$rec = [];
$rec[] = ['Event_Participant_ID' => 278456, 'Participation_Status_ID' => 3];

$event = $mp->table('Event_Participants')
		->select("Event_Participant_ID, Event_ID, Participant_ID, Participation_Status_ID")
		->records($rec)			
		->put();

注意，在POST和PUT中，API将返回结果记录。如果您只想获取特定字段而不是整个记录，可以在select()方法中指定这些字段。实际上，API正在执行POST或PUT，然后在一个操作中返回GET的所有结果。

删除记录

警告：删除可能会对您的数据库造成严重影响。在沙盒中测试！自行承担风险。一旦删除，就无法恢复。

可以通过调用delete方法并传递要删除的行的ID来删除现有的表行。例如，要删除具有contact_id 24599的联系人，请执行此命令

$contact = $mp->table('Contacts')->delete(24599);

删除多条记录

可以使用deleteMultiple()方法批量删除现有行。

// IDs are Event_Participant_IDs (primary Key)
$rec = ['IDs' => [309599,309598] ];

$ep = $mp->table('Event_Participants')
             ->records($rec)
             ->deleteMultiple();

执行存储过程

可以使用存储过程API端点执行存储过程。此示例使用为我们的PCO集成编写的自定义过程获取所选联系人。

<?php

require_once __DIR__ . '/vendor/autoload.php';

use MinistryPlatformAPI\MinistryPlatformProcAPI as PROC;

// Get environment variables
$dotenv = Dotenv\Dotenv::createUnsafeImmutable(__DIR__);
$dotenv->load();


// Attempt to authenticate to the MP API

$mp = new PROC();
$mp->authenticate();

$input = ['@SelectionID' => 26918];
$contacts = $mp->proc('api_MYGCC_PCOGetSelectedContacts')             
             ->procInput($input)
             ->exec();

print_r($contacts);

文件端点

API包装器现在支持文件API操作。要加载Files API包装器，可以这样做

require_once __DIR__ . '/vendor/autoload.php';

use MinistryPlatformAPI\MinistryPlatformFileAPI as MP;

// Get environment variables
$dotenv = Dotenv\Dotenv::createUnsafeImmutable(__DIR__);
$dotenv->load();

列出记录的文件

提供表名和record_id以获取每个文件的信息

// Get metadata for the file(s) based on table and record id
   $fm = $mp->table('Contacts')->recordID(55309)->get();
   $metadata = json_decode($fm, true);
   print_r($metadata);

下载记录的文件

使用FileId或UniqueFileId，您可以下载文件。API将文件作为流返回，您可以将它保存到本地文件。

// Get metadata for the file(s) based on table and record id
$fm = $mp->table('Contacts')->recordID(55309)->get();
$metadata = json_decode($fm, true);

// Loop through the metadata and retrieve each file
foreach ($metadata as $fileData) {

	echo 'Saving file: ' . $fileData['FileName'] . "\n";
	$fileID = $fileData['FileId'];

	$file = $mp->fileID($fileID)->get();
	$outfile = 'D:/Temp/' . $fileData['FileName'];

	file_put_contents($outfile, $file);
}

上传文件

您可以将文件和元数据上传到表/记录。此示例包括一些额外的属性。

$filename = 'D:/Pictures/Profile_Picture.jpg';

$response = $mp->table('Contacts')
            ->recordID(55309)
            ->file($filename)
            ->default()
            ->longestDimension(300)
            ->description('New Picture 2020')
            ->post();

修改文件

您可以修改现有的文件（包括更换图片）。

$file = $mp->fileId(63793)
              ->description('Second Picture From 2019')
              ->put();

删除文件

传递文件的FileID并删除它

$result = $mp->delete(63792);