kneu/api

KNEU REST API 服务 PHP 客户端

维护者

详细信息

github.com/berejant/kneu-api

源代码

问题

安装: 26

依赖: 0

建议者: 0

安全: 0

星星: 0

关注者: 1

分支: 0

开放问题: 0

语言:API 蓝图

v1.1.2 2022-08-06 10:10 UTC

Requires

MIT 3d1fd21f91511bc51d32c75afe50f3cce5e461d4

  • Anton Berezhnoj <berejant.woop@gmail.com>

This package is auto-updated.

Last update: 2024-09-06 14:35:30 UTC

README

这个 PHP 库提供了一个程序化的用户友好接口，用于操作 KNEU RESTful API 和 OAuth 2.0。

这个 PHP 库提供了一个程序化的用户友好接口，用于操作 KNEU RESTful API 和 OAuth 2.0。

安装

使用 Composer 将库添加到您的项目中

composer require kneu/api

方法描述

$api = Kneu\Api::createWithOauthToken($client_id, $client_secret, $code, $redirect_uri): Kneu\Api

完成 oauth 流程 - 在基于从客户端获得的 code 获取 access_token。

  • 参数

    • $client_id — int — 由管理员提供的应用 ID
    • $client_secret — string — 由管理员提供的应用密钥
    • $code — string — 从浏览器用户那里获得的代码
    • $redirect_uri — string — 外部应用程序的 URL (域名)，其中进行了带有 code 的重定向

  • 返回值: \Kneu\Api - 用于后续 API 调用的 \Kneu\Api 类对象

  • 异常

    • Kneu\CurlException
    • Kneu\JsonException
    • Kneu\ApiException

$api = Kneu\Api::createWithServerToken($client_id, $client_secret): Kneu\Api

授权外部服务器以使用 API（导入院系、系、教师、学术小组、专业）。

  • 参数
    • $client_id — int — 由管理员提供的应用 ID
    • $client_secret — string — 由管理员提供的应用密钥
  • 返回值: \stdClass - 用于后续 API 调用的 \Kneu\Api 类对象

getAccessToken(): ?string

获取在 createWithServerToken 或 createWithOauthToken 之后获得的 access_token。

setReturnAssociative()

默认情况下，方法返回数据作为 stdClass 对象。方法 setReturnAssociative() 允许将数据类型更改为关联数组。

$facultyStdClassObject = $api->getFaculty(1);
var_dump($facultyStdClassObject, $facultyStdClassObject->name);
<<<DUMP
object(stdClass)#2 (2) {
  ["id"]=> int(1)
  ["name"]=> string(44) "Економіки та управління"
}
string(44) "Економіки та управління"
DUMP;

$api->setReturnAssociative();
$facultyAssocArray = $api->getFaculty(1);
var_dump($facultyAssocArray, $facultyAssocArray['name']); =>
<<<DUMP
array(2) {
  ["id"]=> int(1)
  ["name"]=> string(44) "Економіки та управління"
}
string(44) "Економіки та управління"
DUMP;

getUser()

使用当前的 access_token 获取当前用户的信息。只有在调用 oauthToken() 之后，用户信息才可用。在服务器授权（serverToken()）的情况下，不提供用户信息。

  • 返回值: \stdClass — 具有属性
    • id - integer - 用户标识符,
    • email - string,
    • last_name - string,
    • first_name - string,
    • middle_name - string,
    • type - enum("student", "teacher", "simple")
    • student_id - null|integer - 学生账户标识符（不是学生证号码）
    • group_id - null|integer - 学生学术小组标识符
    • teacher_id - null|integer - 教师标识符
    • department_id - null|integer - 教师所属系的标识符
    • sex - null|enum("male", "female") - 性别（男性/女性），仅对学生可用

getFaculties([array $filters = [],] [[integer $offset = null,] integer $limit = null]): Generator

获取院系列表

$api->getFaculties();
$api->getFaculties($limit);
$api->getFaculties($offset, $limit);
<<<EXAMPLE
[
    {
        "id": 1,
        "name": "Економіки та управління"
    },
    ...
]
EXAMPLE;

getDepartments([array $filters = [],] [[integer $offset = null,] integer $limit = null]): Generator

获取院系列表。允许获取院系列表。提供以下列表：

  • 所有院系按 id 排序。
  • 所选院系 faculty_id 的院系按名称排序。

学院对象与关联的学院对象一起提供。

$api->getDepartments(); // all
$api->getDepartments(['faculty_id' => 999]); // by faculty id
$api->getDepartments($filters);
$api->getDepartments($filters, $limit);
$api->getDepartments($filters, $offset, $limit);
$api->getDepartments($offset, $limit);
$api->getDepartments($limit);

<<<EXAMPLE
[
    {
        "id": 53,
        "faculty_id": 3,
        "name": "Адміністративного та фінансового права",
        "faculty": {
            "id": 3,
            "name": "Юридичний інститут"
        }
    },
    {
        "id": 57,
        "faculty_id": 3,
        "name": "Іноземних мов юридичного інституту",
        "faculty": {
            "id": 3,
            "name": "Юридичний інститут"
        }
    },
    ...
]
EXAMPLE;

getTeachers([array $filters = [],] [[integer $offset = null,] integer $limit = null]): Generator

允许获取教师列表。提供以下列表：

  • 所有按ID排序的教师。
  • 按字母顺序排列的特定系faculty_id或学院department_id的教师。教师对象提供与关联对象学院和用户（User）的关联数据。

注意！User对象是可选的。仅在教师已在网站上注册的情况下存在。

方法内部实现会自动向服务器发出必要的查询次数，以获取完整的教师列表。

$api->getTeachers(); // all teachers
$api->getTeachers(['faculty_id' => 999]); // by faculty
$api->getTeachers(['department_id' => 999]); // by department
$api->getTeachers($filters);
$api->getTeachers($filters, $limit);
$api->getTeachers($filters, $offset, $limit);
$api->getTeachers($offset, $limit);
$api->getTeachers($limit);

<<<EXAMPLE
[
    {
        "id": 1105,
        "department_id": 21,
        "name": "Іваненко Іван Іванович",
        "first_name": "Іван",
        "middle_name": "Іванович",
        "last_name": "Іваненко",
        "image_url": "https:\/\/kneu.edu.ua\/files\/teacher\/teacher_photo\/thumbnail_1113333.jpg",
        "user": {
            "id": 5019,
            "login": "example@gmail.com"
        },
        "department": {
            "id": 21,
            "faculty_id": 3,
            "name": "Цивільного та трудового права"
        }
    },
    ...
]
EXAMPLE;

getSpecialties([array $filters = [],] [[integer $offset = null,] integer $limit = null]): Generator

允许获取专业列表。提供以下列表

  • 按ID排序的所有专业
  • 特定系faculty_id的专业按名称排序。

与关联对象学院的数据一起提供。方法内部实现会自动向服务器发出必要的查询次数，以获取完整的专业列表。

$api->getSpecialties(); // all specialties
$api->getSpecialties(['faculty_id' => 999]); // by faculty
$api->getSpecialties($filters);
$api->getSpecialties($filters, $limit);
$api->getSpecialties($filters, $offset, $limit);
$api->getSpecialties($offset, $limit);
$api->getSpecialties($limit);
<<<EXAMPLE
[
     {
        "id": 131,
        "faculty_id": 9,
        "code": "6701",
        "name": "Безпепека інформаційних і комунікаційних систем",
        "faculty": {
            "id": 9,
            "name": "Інститут інформаційних технологій в економіці"
        }
    },
    {
        "id": 173,
        "faculty_id": 9,
        "code": "6.051",
        "name": "Економіка",
        "faculty": {
            "id": 9,
            "name": "Інститут інформаційних технологій в економіці"
        }
    },
    ...
]
EXAMPLE;

getGroups([array $filters = [],] [[integer $offset = null,] integer $limit = null]): Generator

允许获取学术小组列表。提供以下列表

  • 按ID排序的所有学术小组
  • 特定专业specialty_id或系faculty_id的学术小组按专业名称和小组名称排序

小组对象与关联对象专业一起提供。

$api->getGroups(); // all groups
$api->getGroups(['faculty_id' => 999]); // by faculty
$api->getGroups(['specialty_id' => 999]); // by specialty
$api->getGroups($filters);
$api->getGroups($filters, $limit);
$api->getGroups($filters, $offset, $limit);
$api->getGroups($offset, $limit);
$api->getGroups($limit);
<<<EXAMPLE
[
    {
        "id": 13293,
        "specialty_id": 33,
        "course": 2,
        "name": "ПР.-201",
        "specialty": {
            "id": 33,
            "faculty_id": 18,
            "code": "7.03040101",
            "name": "Правознавство"
        }
    },
    {
        "id": 13297,
        "specialty_id": 36,
        "course": 2,
        "name": "ОА.-201",
        "specialty": {
            "id": 36,
            "faculty_id": 18,
            "code": "7.03050901",
            "name": "Облік і аудит"
        }
    }
    ...
]
EXAMPLE;

getStudents([array $filters = [],] [[integer $offset = null,] integer $limit = null]): Generator

允许获取学生列表。提供以下列表

  • 按ID排序的所有学生
  • 特定学术小组group_id的学生按姓氏字母顺序排序

如果学生已在网站上注册，则还会添加有关关联实体用户（User）的信息。如果学生未注册，则结果中不包含User信息。方法内部实现会自动向服务器发出必要的查询次数，以获取完整的组列表。

$api->getStudents(); // all students
$api->getStudents(['group_id' => 999]); // by group and order by name 
$api->getStudents($filters);
$api->getStudents($filters, $limit);
$api->getStudents($filters, $offset, $limit);
$api->getStudents($offset, $limit);
$api->getStudents($limit);

<<<EXAMPLE
[
    {
      "id": 444,
      "group_id": 123,
      "gradebook_id": "999999",
      "sex": "male",
      "name": "Іваненко Павло Володимирович",
      "first_name": "Павло",
      "middle_name": "Володимирович",
      "last_name": "Іваненко",
      "birthdate": "1992-07-13",
      "user": {
         "id": 32664,
         "login": "example@gmail.com"
      }
    },
    ...
]
EXAMPLE;
  • 参数
    • $filters — array — 用于选择特定对象的过滤器
    • $offset — integer — 查询中对象的偏移量。类似于 SQL LIMIT [offset], [limit];
    • $limit — integer — 查询中的对象数量（MAX = 2000）。类似于 SQL LIMIT [offset], [limit];
  • 返回值： array
  • 异常
    • Kneu\CurlException
    • Kneu\JsonException
    • Kneu\ApiException

getFaculty(integer $id)

获取指定id的学院

getDepartment(integer $id)

获取指定id的学院

getTeacher(integer $id)

获取指定id的教师

getSpecialty(integer $id)

获取指定id的专业

getGroup(integer $id)

获取指定id的小组

getStudent(integer $id)

获取指定id的学生

request($method, array $params = array())

调用任意的API方法。

  • 参数
    • $method — string — 方法地址
    • $params — array — POST参数
  • 返回值： \stdClass|array
  • 异常
    • Kneu\CurlException
    • Kneu\JsonException
    • Kneu\ApiException

getContentRange($key)

允许获取关于特定实体的对象总数（例如教师、专业、学院等）的元信息。信息来自Content-Range标题，因此只有在执行获取特定实体对象列表的方法（查询）之后，getContentRange()方法才能提供信息。例如，在调用getTeachers()、getGroups()、getSpecialities()等方法之后，可以调用getContentRange()方法。以下代码示例（在服务器授权和数据导入部分）中说明了getContentRange()方法的应用。

  • 参数： $key — string — enum("total", "start", "end")
    • total - 对象的总数（数据库中的总数）
    • start - 从开始偏移数据的位置（从0开始）。类似于 SQL LIMIT [start], 100。换句话说，- 是最后一个查询中在总列表中的第一个对象索引。
    • end - 数据滚动的结束。 [end] = [start] + [limit] - 1，类似于SQL中的LIMIT [start], [limit]。换句话说，就是最后一个查询对象在对象列表中的索引。
    • 如果未设置 $key 的值，则方法将返回包含键 start、end、total 的数组。
  • 返回值： array|integer|null

使用示例

用户认证及用户数据导入

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

$api = Kneu\Api::createWithOauthToken(__CLIENT_ID__, __CLIENT_SECRET__, filter_input(INPUT_GET, 'code'), $redirect_uri);
/*
    $redirect_uri - як правило це current url без параметрів code та scope.
    Якщо використаний фреймворк не дозволяє побудувати штатними засобами $redirect_uri,
    то його можна отримати наступним чином:

    $isSsl = (!empty($_SERVER['HTTPS']) && $_SERVER['HTTPS'] != 'off')
          || ($_SERVER['SERVER_PORT'] ?? $_SERVER['HTTP_X_FORWARDED_PORT'] ?? null) == 443;

    $redirect_uri = 'http' . ($isSsl ? 's' : '') . '://' . $_SERVER['HTTP_HOST']
                  . rtrim(preg_replace('#(code|state)=.*?($|\&)#', '', $_SERVER['REQUEST_URI']), '?');
*/

$user = $api->getUser();
var_dump($user);
/*
object(stdClass) (9) {
  ["id"] => int(999)
  ["email"] => string(18) "sample@exampla.com"
  ["last_name"] => string(6) "Іванов"
  ["first_name"] => string(4) "Іван"
  ["middle_name"] => string(8) "Іванович"

  ["type"] => string(6) "simple"

  ...

  ["type"] => string(7) "student"
  ["student_id"] => int(99999)
  ["group_id"] => int(9999)
  ["sex"] => string(4) "male"

  ...

  ["type"] => string(7) "teacher"
  ["teacher_id"] => int(9999)
  ["department_id"] => int(99)

}
*/

if('student' == $user->type) {
    $group = $api->getGroup($user->group_id);
    var_dump($group);

    /*
    object(stdClass) (5) {
      ["id"] => int(999)
      ["name"] => string(10) "ЕЕЕ-999"
      ["course"] => int(5) // п'ятий курс
      ["specialty"] => object(stdClass) (3) {
        ["id"] => int(214)
        ["code"] => string(5) "8.122"
        ["name"] => string(85) "Комп’ютерні науки та інформаційні технології"
      }
      ["faculty"] => object(stdClass) (2) {
        ["id"] => int(9)
        ["name"] => string(63) "Інформаційних систем і технологій"
      }
    }
    */

} elseif ('teacher' == $user->type) {
    $teacher = $api->getTeacher($user->teacher_id);
    var_dump($teacher);
    /*
    object(stdClass)#4 (5) {
      ["id"] => int(999)
      ["department_id"] => int(43)
      ["first_name"] => string(4) "Іван"
      ["middle_name"] => string(8) "Іванович"
      ["last_name"] => string(6) "Іванов"
      ["user"]=> object(stdClass)#5 (2) {
         ["id"] => int(5019)
         ["login"] => string(19) "example@gmail.com"
      }
      ["department"]=> object(stdClass)#6 (3) {
         ["id"] => int(21)
         ["faculty_id"] => int(3)
         ["name"] => string(55) "Цивільного та трудового права"
      }
    }
    */

    $department = $api->getDepartment($user->department_id); // or $teacher->department_id
    var_dump($department);
    /*
    object(stdClass) (3) {
      ["id"] => int(99)
      ["faculty_id"] => int(9)
      ["name"] => string(61) "Інформаційних систем в економіці"
      ["faculty"]=> object(stdClass)#3 (2) {
        ["id"] => int(3)
        ["name"] => string(35) "Юридичний інститут"
      }
    }
    */

服务器认证及数据库导入

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

$api = Kneu\Api::createWithServerToken(__CLIENT_ID__, "__CLIENT_SECRET__")

try {

     foreach($api->getDepartments(['faculty_id' => 3]) as $teacher) {
         // do anything with $teacher...
     }
     

     /** @var stdClass $teacher */
     foreach($api->getTeachers(['department_id' => 21]) as $teacher) {
         // do anything with $teacher...
     }
     
     
     /** @var stdClass $student */
     foreach($api->getStudents(['group_id' => 17867]) as $student) {
         // do anything with $teacher...
     }


/* Обробка помилок - або кожну помилку окремо або один єдиний блок catch(\Exception $e) */
} catch (\Kneu\CurlException $e) {
    var_dump($e);

} catch (\Kneu\JsonException $e) {
    var_dump($e);

} catch (\Kneu\ApiException $e) {
    var_dump($e);

/*  або замість трьох блоків catch - один, який перехоплює будь-які виключення Exception */
} catch (\Exception $e) {
    var_dump($e);
}