Документирование кода

README.md

@@ -5,6 +5,15 @@ This package provides [September First](https://api.1sept.ru) integration for [O
 
 ## Installation
 
+Add to `composer.json`:
+```
+"repositories": [{
+    "type": "vcs",
+    "url": "https://github.com/1sept/oauth2-1sept"
+}],
+```
+
+Then execute:
 ```sh
 composer require 1sept/oauth2-1sept
 ```

composer.json

@@ -17,7 +17,7 @@
         "1sept"
     ],
     "require": {
-        "php": "^5.6|^7.0",
+        "php": "^7.0",
         "league/oauth2-client": "^2.0"
     },
     "require-dev": {

src/Provider/SeptemberFirstProvider.php

@@ -8,57 +8,81 @@ use League\OAuth2\Client\Tool\BearerAuthorizationTrait;
 use League\OAuth2\Client\Provider\Exception\IdentityProviderException;
 use Psr\Http\Message\ResponseInterface;
 
+/**
+ * Провайдер данных Первого сентября
+ */
 class SeptemberFirstProvider extends AbstractProvider
 {
     use BearerAuthorizationTrait;
 
     /**
-     * Личный кабинет Первое сентября
-     *
-     * @var string
+     * @var string Сервер аутентификации (Личный кабинет Первое сентября)
      */
     const AUTH_BASE = 'https://my.1sept.ru';
 
     /**
-     * API Первое сентября
-     *
-     * @var string
+     * @var string API Первое сентября
      */
     const API_BASE = 'https://api.1sept.ru';
+
+    /**
+     * @var string Версия API
+     */
     const API_VERSION = '2.0';
 
+    /**
+     * @inheritDoc
+     */
     public function getBaseAuthorizationUrl(): string
     {
         return static::AUTH_BASE.'/oauth/authorize';
     }
 
+    /**
+     * @inheritDoc
+     */
     public function getBaseAccessTokenUrl(array $params): string
     {
         return static::API_BASE.'/oauth/access_token';
     }
 
+    /**
+     * @inheritDoc
+     */
     public function getResourceOwnerDetailsUrl(AccessToken $token): string
     {
         return static::API_BASE.'/'.static::API_VERSION.'/userinfo';
     }
 
+    /**
+     * @inheritDoc
+     */
     public function getDefaultScopes(): array
     {
-        return ['basic'];
+        return ['profile'];
     }
 
+    /**
+     * @inheritDoc
+     */
     protected function getScopeSeparator(): string
     {
         return ' ';
     }
 
-    protected function checkResponse(ResponseInterface $response, $data)
+    /**
+     * @inheritDoc
+     */
+    protected function checkResponse(ResponseInterface $response, $data): void
     {
         if (!empty($data['error'])) {
             throw new IdentityProviderException($data['error'].': '.$data['message'], null, $response);
         }
     }
 
+    /**
+     * @inheritDoc
+     */
     protected function createResourceOwner(array $response, AccessToken $token): SeptemberFirstUser
     {
         return new SeptemberFirstUser($response);

src/Provider/SeptemberFirstUser.php

@@ -4,68 +4,57 @@ namespace Sept\OAuth2\Client\Provider;
 
 use League\OAuth2\Client\Provider\ResourceOwnerInterface;
 
+/**
+ * Пользователь Первого сентября
+ */
 class SeptemberFirstUser implements ResourceOwnerInterface
 {
     /**
-     * Массив с данными о пользователе
+     * @var array Массив с данными о пользователе
      */
     protected $data;
 
-    /**
-     * Конструктор
-     */
     public function __construct(array $response)
     {
         $this->data = $response;
     }
 
     /**
-     * Значение массива (многомерного)
-     *
-     * @param string $key Ключ поля (например: `email` или `name.first` — вложенность оформляется точкой)
-     * @return mixed|null
-     */
-    public static function getFieldFromArray(string $key, ?array $array)
-    {
-        if (strpos($key, '.')) { // key.subKey.subSubKey
-            list ($key, $subKey) = explode('.', $key, 2);
-            return isset($array[$key]) ? static::getFieldFromArray($subKey, $array[$key]) : null;
-        }
-
-        return isset($array[$key]) ? $array[$key] : null;
-    }
-
-    /**
-     * Элемент массива данных о пользователе
-     *
-     * @param string $key Ключ поля (например: email или name.first — вложенность оформляется точкой)
-     * @return mixed|null
-     */
-    protected function getField(string $key)
-    {
-        return static::getFieldFromArray($key, $this->data);
-    }
-
-    /**
-     * Данные о пользователе в виде массива
+     * Массив с данными о пользователе
      *
      * @return array
      */
-    public function toArray()
+    public function toArray(): array
     {
         return $this->data;
     }
 
     /**
-     * ID пользователя
+     * ID пользователя (UUID)
+     *
+     * @return string
+     * @example '1cc1632f-2349-4d00-8302-5c4c188469cc'
      */
-    public function getId(): ?string
+    public function getId(): string
     {
         return $this->getField('id');
     }
 
     /**
-     * {@inheritdoc}
+     * Устаревшие ID пользователя (UUID)
+     * (остаются после объединения уч. записей)
+     *
+     * @return array<string>
+     */
+    public function getIdAlt(): array
+    {
+        return $this->getField('id_alt') ?? [];
+    }
+
+    /**
+     * Фамилия
+     *
+     * @var string|null
      */
     public function getLastName(): ?string
     {
@@ -73,7 +62,9 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Имя
+     *
+     * @var string|null
      */
     public function getFirstName(): ?string
     {
@@ -81,7 +72,9 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Отчество
+     *
+     * @var string|null
      */
     public function getMiddleName(): ?string
     {
@@ -89,7 +82,7 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * Девичья фамилия пользователя (только для женского пола)
+     * Девичья фамилия
      *
      * @return string|null
      */
@@ -99,7 +92,9 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Отображаемое имя
+     *
+     * @return string|null
      */
     public function getDisplayName(): ?string
     {
@@ -107,7 +102,9 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Пол
+     *
+     * @return 'male'|'female'|null
      */
     public function getSex(): ?string
     {
@@ -115,7 +112,19 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Умер
+     *
+     * @return bool|null
+     */
+    public function isDied(): ?bool
+    {
+        return $this->getField('is_died');
+    }
+
+    /**
+     * Эл. адрес
+     *
+     * @return string|null
      */
     public function getEmail(): ?string
     {
@@ -123,7 +132,9 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Дата рождения
+     *
+     * @return \DateTime|null
      */
     public function getBirthday(): ?\DateTime
     {
@@ -131,7 +142,10 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * URL картинки
+     *
+     * @param bool $rejectEmptyAvatar Если true, то пустые аватарки (заглушки) не отдаются
+     * @return string|null
      */
     public function getAvatarUrl(bool $rejectEmptyAvatar = false): ?string
     {
@@ -154,11 +168,13 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * URL публичной страницы профиля
+     *
+     * @return string|null
      */
     public function getProfileUrl(): ?string
     {
-        return $this->getField('profile_url');
+        return $this->getField('link');
     }
 
     /**
@@ -168,27 +184,55 @@ class SeptemberFirstUser implements ResourceOwnerInterface
      */
     public function getPhone(): ?string
     {
-        return null;
+        return $this->getField('phone');
     }
 
     /**
-     * Локаль
+     * Локаль (языковые и др. настройки)
      *
      * @return string|null
+     * @example ru_RU
      */
     public function getLocale(): ?string
     {
-        return null;
+        return $this->getField('locale');
     }
 
     /**
-     * Имя временной зоны (от -24 до 24)
-     * @example Europe/Moscow
+     * Имя временной зоны
      *
      * @return string|null
+     * @example Europe/Moscow
      */
     public function getTimezone(): ?string
     {
         return $this->getField('timezone');
     }
+
+    /**
+     * Элемент массива данных о пользователе
+     *
+     * @param string $key Ключ поля (например: email или name.first — вложенность оформляется точкой)
+     * @return mixed|null
+     */
+    protected function getField(string $key)
+    {
+        return static::getFieldFromArray($key, $this->data);
+    }
+
+    /**
+     * Значение массива (многомерного)
+     *
+     * @param string $key Ключ поля (например: `email` или `name.first` — вложенность оформляется точкой)
+     * @return mixed|null
+     */
+    public static function getFieldFromArray(string $key, ?array $array)
+    {
+        if (strpos($key, '.')) { // key.subKey.subSubKey
+            list ($key, $subKey) = explode('.', $key, 2);
+            return isset($array[$key]) ? static::getFieldFromArray($subKey, $array[$key]) : null;
+        }
+
+        return isset($array[$key]) ? $array[$key] : null;
+    }
 }