README

梦申请 SDK 是 Dream Apply API 的客户端工具。

安装

自 3.0.0 版本起，SDK 已发布在 Packagist 上。

composer require dream-group/dream-apply-sdk

要求

PHP 5.5 或更高版本。

此库需要一个 PSR-18 或 HTTPlug 兼容的 HTTP 客户端才能运行。

推荐客户端

• (PHP >= 7.2) guzzlehttp/guzzle 版本 7 及以上
• (PHP >= 7.1) symfony/http-client
• (PHP >= 5.5) php-http/guzzle6-adapter

完整列表

• PSR-18 (推荐标准，PHP >= 7.0)
• HTTPlug

SDK 和 API 版本

支持的 SDK 和 API 版本

• SDK 版本 1 支持 API 版本 3
• SDK 版本 2 支持 API 版本 4
• SDK 版本 3 支持 API 版本 5

有关升级说明，请参阅 UPGRADE.md。

初始化

<?php
$client = new \Dream\Apply\Client\Client('https://instance.dreamapply.com/api/', 'abcdefghijklmnopqrstuvwxyz123456');

结构

对象层次结构尽可能接近 API URI 结构

<?php
$client->applicants[1]->documents[2]; // /applications/1/documents/2
$client->applications->offers->types; // /applications/offers/types

字段中使用 snake_case，URL 中使用 dash-case，对应对象的 camelCase 和属性

<?php
$client->applications[1]->academicTerm; // 'academic_term' from /applications/1
$client->academicTerms;                 // /academic-terms

处理集合

集合类似于 $client 或父集合/记录的属性。集合实现数组访问并可遍历。

<?php
$client->applicants[1];
foreach ($client->applicants as $applicantId => $applicant) {
    print "{$applicantId} email is {$applicant->email}";
}

$client->applicants->count();   // count items (sends HEAD request)
$client->applicants->exists(1); // existence check (sends HEAD request)
$client->applicants->toArray(); // convert to array

使用过滤器时，通过方法调用获取集合。请注意，记录获取和记录存在检查忽略集合的当前过滤器

<?php
// filters are required to iterate over applications
$applications = $client->getApplications(['byCommenceYear' => 2016, 'byStatuses' => 'Submitted']);

$inactive = $applications->filter(['byStatuses' => 'Inactive']); // add or override conditions in filter

$inactive->count();     // count filtered
$inactive->toArray();   // array of filtered items

记录和关联

<?php
// returned fields are properties 
$client->applicants[1]->email;
$client->applicants[1]->name['given'];

// all links between records are automatically resolved
$client->applicants[1]->trackers[1]->assigned; // get field of tracker association
$client->applicants[1]->trackers[1]->tracker;  // get actual tracker from association

// when iterating over collections, object properties are lazy loaded
// please note when calculating API request count
$applications = $client->getApplications(['byCommenceYear' => 2016, 'byStatuses' => 'Submitted']);

// one request
foreach ($applications as $id => $app) {
    var_dump($app->revised); // 'revised' is returned in collection
}

// collection request + 1 request per object
foreach ($applications as $id => $app) {
    var_dump($app->profile); // 'profile' is not returned in collection, we have to request it
}

二进制记录

某些请求（如申请人的照片和文件）返回文件。文件以二进制记录的形式返回，其行为与正常记录相同，但包含预定义字段。

<?php
$photo = $client->applicants[1]->photo;

$photo->name;       // file name
$photo->mime;       // mime type
$photo->size;       // file size
$photo->uploaded;   // file uploaded timestamp
$photo->content;    // file content, an instance of StreamInterface from PSR-7
$photo->expires;    // expiration timestamp (is set for reports)

file_put_contents("/tmp/{$photo->name}", $photo->content);

特殊操作

创建（POST）

标志、追踪器和申请人可以在 API 中创建

<?php

use Dream\Apply\Client\CreatableModels\Applicant;
use Dream\Apply\Client\CreatableModels\Flag;
use Dream\Apply\Client\CreatableModels\Tracker;

$newTracker     = $client->applicants->trackers->create(new Tracker([
    'code' => 'tracker code', 
    'notes' => 'notes',
]));
$newFlag        = $client->applications->flags->create(new Flag(['name' => 'flag name']));
$newApplicant   = $client->applicants->create(new Applicant([
    'email'         => 'email@example.com',
    'name_given'    => 'Name',
    'name_family'   => 'Surname',
]);

添加关联

标志和追踪器关联可以在 API 中创建

<?php
$client->applicants[1]->trackers->add($newTracker);     // add by associated object
$flagAssoc = $client->applications[1]->flags->add(123); // add by associated object id, get assoc instance

删除

标志、追踪器、它们的关联和发票可以在 API 中删除

<?php
$client->applications[1]->flags->delete(123);           // delete by id
$client->applications[1]->flags->delete($flagAssoc);    // delete by association object
$client->applications[1]->flags->delete($newFlag);      // delete by associated record

可设置的字段

API 允许设置一些字段，如报价的类型和任务状态

<?php
use Dream\Apply\Client\Models\Offer;

$client->applications[21]->tasks[4]->setStatus('This is an example status of a task.');
$client->applications[32]->offers[76]->setType(Offer::TYPE_ACCEPTED);

其他特殊情况

简单数组

某些请求返回简单数组，就像处理普通的 PHP 数组一样处理它们

<?php
$client->applications->statuses;
$client->applications->offers->types;
$client->classificators;
$client->invoices->series;

报告

报告对象有两个方法

<?php
// list all available reports
$client->reports->getAvailable();
// get report as binary record
$client->reports->getReport('ReportStatus', ['regions' => 1, 'academicTerm' => 1, 'institutions' => 1]);