Download the PHP package kneu/api without Composer

PHP client for KNEU RESTful API Service

This PHP Library provide programmatic user-friendly interface to work with the KNEU RESTful API and OAuth 2.0.

Ця PHP-бібліотека забезпечує зручний програмний інтерфейс для роботи з КНЕУ RESTful API та протоколом OAuth 2.0.

Встановлення

Додати бібліотеку до Вашого проекту за допомогою Composer

composer require kneu/api

Опис методів

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

Завершити процедуру oauth - отримати access_token на основі отриманого від клієнта значення code.

• Parameters:
  • $client_id — int — ID додатку, який надається адміністратором
  • $client_secret — string — Секрет додатку, який надається адміністратором
  • $code — string — Код отриманий з браузера користувача
  • $redirect_uri — string — URL стороннього додатку (домену), на який була виконана переадресація з параметром code.

• Returns: \Kneu\Api - об'єкт классу \Kneu\Api для подальших викликів API

• Exceptions:
  • Kneu\CurlException
  • Kneu\JsonException
  • Kneu\ApiException

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

Авторизація стороннього серверу для роботи з API (імпорту списку факультетів, кафедр, викладачів, академічних груп, спеціальностей).

• Parameters:
  • $client_id — int — ID додатку, який надається адміністратором
  • $client_secret — string — Секрет додатку, який надається адміністратором
• Returns: \stdClass - об'єкт классу \Kneu\Api для подальших викликів API

getAccessToken(): ?string

Отримати access_token, який був отриманний після createWithServerToken або createWithOauthToken.

setReturnAssociative()

За замовчуванням, методи повертають дані як об'єкти stdClass. Метод setReturnAssociative() дозволяє змінити тип данних на асоціативний массив.

getUser()

Отримати інформацію про поточного користувача з поточним access_token. Інформація про користувача доступна лише після виклику oauthToken(). При використанні авторизації серверу (serverToken()) - інформація про користувача не надається.

• Returns: \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

Отримати перелік факультетів

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

Отримати перелік кафедр Дозволяє отримати перелік кафедр. Надає перелік:

• всіх кафедр відсортованних за id.
• кафедр вибраного факультету faculty_id відсортованних за назвою.

Об'єкт Кафедра надається разом з даними по зв'язанному об'єкту Факультет.

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

Дозволяє отримати перелік викладачів. Надає перелік:

• всіх викладачів відсортаванних за id.
• викладачів певного факультету faculty_id або кафедри department_id в алфавітному порядку за прізвищем. Об'єкт викладач надається разом даними зв'язаних об'єктів Кафедра та Користувач (User).

Увага! Обєкт User є необов'язковий. Присутний лише в разі, коли викладач вже зар'єструвався на сайті.

Внутрішня реалізація метода автоматично робить потрібну кількисть запитів до сервера, щоб отримати повний список викладачів.

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

Дозволяє отримати перелік спеціальностей. Надає перелік:

• всіх спеціальностей сортованних за id
• спеціальностей певного факультету faculty_id сортованних за назвою.

Надається разом із даними зв'язаного об'єкту Факультет. Внутрішня реалізація метода автоматично робить потрібну кількисть запитів до сервера, щоб отримати повний список спеціальностей.

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

Дозволяє отримати перелік академічних груп. Надає перелік:

• всіх академічних груп відсортованних за id;
• академичніних груп певної спеціальності specialty_id або факультету faculty_id відсортованних за назвою спеціальності та назвою групи

Об'єкт група надається разом із зв'заним об'єктом спеціальність.

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

Дозволяє отримати перелік студентів. Надає перелік:

• всіх студентів, відсортованних за id
• студентів певної академічної групи group_id підсортованих в алфавітному порядку за прізвищем

Якщо студент зарєстрованний на сайті, додатково до додається інформацію про звязанну сутність користувач (User). Якщо студент не зарєстрованний на сайті - інформація про User відсутня у результаті. Внутрішня реалізація метода автоматично робить потрібну кількисть запитів до сервера, щоб отримати повний список груп.

• Parameters:
  • $filters — array — фільтр для вибірки певних об'єктів
  • $offset — integer — зсув об'єктів у видачі. Аналог SQL LIMIT [offset], [limit];
  • $limit — integer — кількість об'єктів у видачі (MAX = 2000). Аналог SQL LIMIT [offset], [limit];
• Returns: array
• Exceptions:
  • 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-методу.

• Parameters:
  • $method — string — адреса методу
  • $params — array — POST параметри
• Returns: \stdClass|array
• Exceptions:
  • Kneu\CurlException
  • Kneu\JsonException
  • Kneu\ApiException

getContentRange($key)

Дозволяє отримати Meta-інформацію про загальну кількість об'єктів певної сутності (для переліку викладачів, спеціальностей, факультетів тощо). Інформація надається із заголовку Content-Range, тому метод getContentRange() може надати інформацію лише після виконання методу (запиту) на отримання переліку об'єктів певної сутності. Наприклад, метод getContentRange() доцільно викликати після виконання методів getTeachers(), getGroups(), getSpecialities() тощо. Детальніше застосування методу getContentRange() подано в прикладі коду нижче (у розділі Авторизація серверу та імпорт бази даних).

• Parameters: $key — string — enum("total", "start", "end")
  • total - загальна кількість об'єктів (total count from database)
  • start - початок зсуву даних починаючи під початку (від 0). Аналог SQL LIMIT [start], 100. Іншими словам - індексу першого об'єкту з останнього запиту в загальному переліку об'єктів.
  • end - кінець зсуву даних. [end] = [start] + [limit] - 1 за аналогією з SQL LIMIT [start], [limit]. Іншими словам - індексу останнього об'єкту з останнього запиту в загальному переліку об'єктів.
  • Якщо значення $key не задано, то метод поверне масив з ключами start, end, total.
• Returns: array|integer|null

Приклад використання

Авторизація користувача та імпорт даних про користувача

Авторизація серверу та імпорт бази даних