Доработана работа с аватаркой пользователя

[feature] Добавлена возможность получения URL аватарки произвольных размеров.
[feature] Поддержка версий аватарок для улучшенного кэширования.
[bugfix] Исправлено определение заглушечных аватарок.

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,21 +4,285 @@ namespace Sept\OAuth2\Client\Provider;
 
 use League\OAuth2\Client\Provider\ResourceOwnerInterface;
 
+/**
+ * Пользователь Первого сентября
+ */
 class SeptemberFirstUser implements ResourceOwnerInterface
 {
+    const AVATAR_BASE = 'https://avatar.1sept.ru';
+
     /**
-     * Массив с данными о пользователе
+     * @var array Массив с данными о пользователе
      */
     protected $data;
 
-    /**
-     * Конструктор
-     */
     public function __construct(array $response)
     {
         $this->data = $response;
     }
 
+    /**
+     * Массив с данными о пользователе
+     *
+     * @return array
+     */
+    public function toArray(): array
+    {
+        return $this->data;
+    }
+
+    /**
+     * ID пользователя (UUID)
+     *
+     * @return string
+     * @example '1cc1632f-2349-4d00-8302-5c4c188469cc'
+     */
+    public function getId(): string
+    {
+        return $this->getField('id');
+    }
+
+    /**
+     * Устаревшие ID пользователя (UUID)
+     * (остаются после объединения уч. записей)
+     *
+     * @return array<string>
+     */
+    public function getIdAlt(): array
+    {
+        return $this->getField('id_alt') ?? [];
+    }
+
+    /**
+     * Фамилия
+     *
+     * @var string|null
+     */
+    public function getLastName(): ?string
+    {
+        return $this->getField('personal_name.surname');
+    }
+
+    /**
+     * Имя
+     *
+     * @var string|null
+     */
+    public function getFirstName(): ?string
+    {
+        return $this->getField('personal_name.name');
+    }
+
+    /**
+     * Отчество
+     *
+     * @var string|null
+     */
+    public function getMiddleName(): ?string
+    {
+        return $this->getField('personal_name.patronymic');
+    }
+
+    /**
+     * Девичья фамилия
+     *
+     * @return string|null
+     */
+    public function getMaidenName(): ?string
+    {
+        return null;
+    }
+
+    /**
+     * Отображаемое имя
+     *
+     * @return string|null
+     */
+    public function getDisplayName(): ?string
+    {
+        return $this->getField('display_name');
+    }
+
+    /**
+     * Пол
+     *
+     * @return 'male'|'female'|null
+     */
+    public function getSex(): ?string
+    {
+        return $this->getField('sex');
+    }
+
+    /**
+     * Умер
+     *
+     * @return bool|null
+     */
+    public function isDied(): ?bool
+    {
+        return $this->getField('is_died');
+    }
+
+    /**
+     * Эл. адрес
+     *
+     * @return string|null
+     */
+    public function getEmail(): ?string
+    {
+        return $this->getField('email');
+    }
+
+    /**
+     * Дата рождения
+     *
+     * @return \DateTime|null
+     */
+    public function getBirthday(): ?\DateTime
+    {
+        return !empty($this->data['birthday']) ? new \DateTime($this->data['birthday']) : null;
+    }
+
+    /**
+     * URL аватарки (150x150)
+     *
+     * @param bool $addVersion Использовать версию аватарки для улучшенного кэширования
+     * @return string|null
+     */
+    public function getAvatarUrl(bool $addVersion = true): ?string
+    {
+        return $this->getField('avatar') . ($addVersion ? $this->getAvatarVersionQuery() : '');
+    }
+
+    /**
+     * URL аватарки определённого размера (<img src="…" width="size" height="size">)
+     *
+     * @param int $size Размер от 1 до 1990 ($size x $size — квадрат)
+     * @param int $ratioMultiplier Множитель разрешения картинки: 1 (по умолчанию), 2 или 3
+     * @param bool $addVersion Использовать версию аватарки для улучшенного кэширования
+     * @return string|null
+     */
+    public function getAvatarSizeUrl(int $size, int $ratioMultiplier = 1, bool $addVersion = true): ?string
+    {
+        $ratio = ($ratioMultiplier > 1) ? '@' . $ratioMultiplier . 'x' : '';
+        $url = static::AVATAR_BASE .'/'. $this->getId() . ($size ? '.' : '') . $size . $ratio . '.jpeg';
+        return $url . ($addVersion ? $this->getAvatarVersionQuery() : '');
+    }
+
+    /**
+     * URL аватарки для экранов разных разрешений (<img srcset="…" width="size" height="size">)
+     *
+     * @param int $size Размер от 1 до 1990 ($size x $size — квадрат)
+     * @param bool $addVersion Использовать версию аватарки для улучшенного кэширования
+     * @return string
+     */
+    public function getAvatarSetSizeUrl(int $size, bool $addVersion = true): string
+    {
+        return $this->getAvatarSizeUrl($size, 1, $addVersion) . ' 1x, '
+             . $this->getAvatarSizeUrl($size, 2, $addVersion) . ' 2x, '
+             . $this->getAvatarSizeUrl($size, 3, $addVersion) . ' 3x';
+    }
+
+    /**
+     * URL аватарки c максимальным размером
+     *
+     * @param bool $useVersion Использовать версию аватарки для улучшенного кэширования
+     * @return string|null
+     */
+    public function getAvatarMaxUrl(bool $addVersion = false): ?string
+    {
+        return $this->getField('avatar_max') . ($addVersion ? $this->getAvatarVersionQuery() : '');
+    }
+
+    /**
+     * Версия аватарки
+     * Изменение версии сигнализирует об обновлении аватарки.
+     *
+     * @return int | null
+     */
+
+    public function getAvatarVersion(): ?int
+    {
+        return $this->getField('avatar_version');
+    }
+
+    /**
+     * Является ли аватарка заглушкой
+     *
+     * @return boolean
+     */
+    public function isDefaultAvatar(): bool
+    {
+        return $this->getField('avatar_default');
+    }
+
+    /**
+     * Query cтрока c версией аватарки (улучшает кэширование)
+     *
+     * @return string
+     */
+    public function getAvatarVersionQuery(): string
+    {
+        $url = '';
+        if ($version = $this->getField('avatar_version')) {
+            $url .= '?v=' . $version;
+        }
+        return $url;
+    }
+
+    /**
+     * URL публичной страницы профиля
+     *
+     * @return string|null
+     */
+    public function getProfileUrl(): ?string
+    {
+        return $this->getField('link');
+    }
+
+    /**
+     * Номер телефона
+     *
+     * @return string|null
+     */
+    public function getPhone(): ?string
+    {
+        return $this->getField('phone');
+    }
+
+    /**
+     * Локаль (языковые и др. настройки)
+     *
+     * @return string|null
+     * @example ru_RU
+     */
+    public function getLocale(): ?string
+    {
+        return $this->getField('locale');
+    }
+
+    /**
+     * Имя временной зоны
+     *
+     * @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);
+    }
+
     /**
      * Значение массива (многомерного)
      *
@@ -34,161 +298,4 @@ class SeptemberFirstUser implements ResourceOwnerInterface
 
         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()
-    {
-        return $this->data;
-    }
-
-    /**
-     * ID пользователя
-     */
-    public function getId(): ?string
-    {
-        return $this->getField('id');
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getLastName(): ?string
-    {
-        return $this->getField('personal_name.surname');
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getFirstName(): ?string
-    {
-        return $this->getField('personal_name.name');
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getMiddleName(): ?string
-    {
-        return $this->getField('personal_name.patronymic');
-    }
-
-    /**
-     * Девичья фамилия пользователя (только для женского пола)
-     *
-     * @return string|null
-     */
-    public function getMaidenName(): ?string
-    {
-        return null;
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getDisplayName(): ?string
-    {
-        return $this->getField('display_name');
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getSex(): ?string
-    {
-        return $this->getField('sex');
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getEmail(): ?string
-    {
-        return $this->getField('email');
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getBirthday(): ?\DateTime
-    {
-        return !empty($this->data['birthday']) ? new \DateTime($this->data['birthday']) : null;
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getAvatarUrl(bool $rejectEmptyAvatar = false): ?string
-    {
-        if (empty($this->data['avatar']) or ((!isset($this->data['has_avatar']) or !$this->data['has_avatar']) and $rejectEmptyAvatar)) {
-            return null;
-        }
-
-        return $this->getField('avatar');
-    }
-
-    /**
-     * Адрес аватарки 50x50
-     *
-     * @param bool $rejectEmptyAvatar Если true, то пустые аватарки (заглушки) не отдаются
-     * @return string|null
-     */
-    public function getAvatar50Url(bool $rejectEmptyAvatar = false): ?string
-    {
-        return $this->getAvatarUrl($rejectEmptyAvatar);
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getProfileUrl(): ?string
-    {
-        return $this->getField('profile_url');
-    }
-
-    /**
-     * Номер телефона
-     *
-     * @return string|null
-     */
-    public function getPhone(): ?string
-    {
-        return null;
-    }
-
-    /**
-     * Локаль
-     *
-     * @return string|null
-     */
-    public function getLocale(): ?string
-    {
-        return null;
-    }
-
-    /**
-     * Имя временной зоны (от -24 до 24)
-     * @example Europe/Moscow
-     *
-     * @return string|null
-     */
-    public function getTimezone(): ?string
-    {
-        return $this->getField('timezone');
-    }
 }