Update SeptemberFirstProvider.php

Проверка на существование сообщения о ошибке в ответе.

.editorconfig

@@ -0,0 +1,16 @@
+# @see http://EditorConfig.org
+
+root = true
+
+[**]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[{src,tests}/**.php]
+tab_width = 4
+
+[*.{neon,xml,md}]
+tab_width = 4

.gitattributes

@@ -0,0 +1,43 @@
+# Common settings that generally should always be used with your language specific settings
+
+# Auto detect text files and perform LF normalization
+# http://davidlaing.com/2012/09/19/customise-your-gitattributes-to-become-a-git-ninja/
+# Handle line endings automatically for files detected as text
+# and leave all files detected as binary untouched.
+* text=auto
+
+# Git
+.gitattributes text
+.gitignore text
+.gitconfig text
+.gitmodules text
+
+# source code
+*.php diff=php
+
+*.json text
+*.markdown text
+*.md text
+*.neon.dist text
+*.xml text
+*.xml.dist text
+*README* text
+.editorconfig text
+AUTHORS text
+LICENSE text
+
+# Ignore export
+/.appveyor.yml export-ignore
+/.editorconfig export-ignore
+/.editorconfig export-ignore
+/.gitattributes export-ignore
+/.github export-ignore
+/.gitignore export-ignore
+/.gitignore export-ignore
+/SECURITY.md export-ignore
+/docs export-ignore
+/phpcs.xml.dist export-ignore
+/phpstan.neon.dist export-ignore
+/phpunit.xml.dist export-ignore
+/psalm.xml.dist export-ignore
+/tests export-ignore

.github/workflows/php.yml

@@ -0,0 +1,39 @@
+name: PHP Composer
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Validate composer.json and composer.lock
+      run: composer validate --strict
+
+    - name: Cache Composer packages
+      id: composer-cache
+      uses: actions/cache@v3
+      with:
+        path: vendor
+        key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-php-
+
+    - name: Install dependencies
+      run: composer install --prefer-dist --no-progress
+
+    # Add a test script to composer.json, for instance: "test": "vendor/bin/phpunit"
+    # Docs: https://getcomposer.org/doc/articles/scripts.md
+
+    - name: Run test suite
+      run: composer run test

.gitignore

@@ -1,5 +1,6 @@
 /build
 /vendor
+.phpunit.cache
 composer.phar
 composer.lock
 .DS_Store

README.md

@@ -5,15 +5,7 @@ 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:
+Just execute:
 ```sh
 composer require 1sept/oauth2-1sept
 ```
@@ -21,7 +13,7 @@ composer require 1sept/oauth2-1sept
 ## Usage
 
 ```php
-$provider = new Sept\OAuth2\Client\Provider\SeptemberFirst([
+$provider = new \Sept\OAuth2\Client\Provider\SeptemberFirstProvider([
     'clientId' => 'client_id',
     'clientSecret' => 'secret',
     'redirectUri' => 'https://example.org/oauth-endpoint',

composer.json

@@ -13,15 +13,19 @@
         "oauth2",
         "client",
         "authorization",
-        "authorisation",
+        "authorization",
         "1sept"
     ],
     "require": {
-        "php": "^5.6|^7.0",
+        "php": "^8.2",
         "league/oauth2-client": "^2.0"
     },
     "require-dev": {
-        "phpunit/phpunit": "~4.0"
+        "phpstan/extension-installer": "^1.3",
+        "phpstan/phpdoc-parser": "^1.29",
+        "phpstan/phpstan": "^1.10",
+        "phpstan/phpstan-strict-rules": "^1.5",
+        "phpunit/phpunit": "^11.1"
     },
     "autoload": {
         "psr-4": {
@@ -30,12 +34,25 @@
     },
     "autoload-dev": {
         "psr-4": {
-            "Sept\\OAuth2\\Client\\Test\\": "test/src/"
+            "Sept\\OAuth2\\Client\\Test\\": "tests"
         }
     },
     "extra": {
         "branch-alias": {
             "dev-master": "1.0.x-dev"
         }
+    },
+    "scripts": {
+        "test": [
+            "@phpunit",
+            "@phpstan"
+        ],
+        "phpunit": "vendor/bin/phpunit",
+        "phpstan": "vendor/bin/phpstan"
+    },
+    "config": {
+        "allow-plugins": {
+            "phpstan/extension-installer": true
+        }
     }
 }

phpstan.neon.dist

@@ -0,0 +1,5 @@
+parameters:
+    level: 8
+    paths:
+        - src
+        - tests

phpunit.xml

@@ -1,37 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<phpunit backupGlobals="false"
-         backupStaticAttributes="false"
-         bootstrap="vendor/autoload.php"
-         colors="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
-         processIsolation="false"
-         stopOnFailure="false"
-         syntaxCheck="false"
->
-    <logging>
-        <log type="coverage-html"
-                target="./build/coverage/html"
-                charset="UTF-8"
-                highlight="false"
-                lowUpperBound="35"
-                highLowerBound="70"/>
-          <log type="coverage-clover"
-                target="./build/coverage/log/coverage.xml"/>
-    </logging>
-    <testsuites>
-        <testsuite name="Package Test Suite">
-            <directory suffix=".php">./test/</directory>
-        </testsuite>
-    </testsuites>
-    <filter>
-        <whitelist>
-            <directory suffix=".php">./</directory>
-            <exclude>
-                <directory suffix=".php">./vendor</directory>
-                <directory suffix=".php">./test</directory>
-            </exclude>
-        </whitelist>
-    </filter>
-</phpunit>

phpunit.xml.dist

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.1/phpunit.xsd" bootstrap="vendor/autoload.php" executionOrder="depends,defects" beStrictAboutOutputDuringTests="true" failOnRisky="true" failOnWarning="true" colors="true" cacheDirectory=".phpunit.cache" requireCoverageMetadata="true" beStrictAboutCoverageMetadata="true">
+  <testsuites>
+    <testsuite name="Gos Test Suite">
+      <directory suffix=".php">tests</directory>
+    </testsuite>
+  </testsuites>
+  <source>
+    <include>
+      <directory suffix=".php">src</directory>
+    </include>
+  </source>
+</phpunit>

src/Provider/SeptemberFirstProvider.php

@@ -1,64 +1,100 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Sept\OAuth2\Client\Provider;
 
-use League\OAuth2\Client\Provider\AbstractProvider;
+use League\OAuth2\Client\Provider\Exception\IdentityProviderException;
+use League\OAuth2\Client\Provider\GenericProvider;
 use League\OAuth2\Client\Token\AccessToken;
 use League\OAuth2\Client\Tool\BearerAuthorizationTrait;
-use League\OAuth2\Client\Provider\Exception\IdentityProviderException;
 use Psr\Http\Message\ResponseInterface;
 
-class SeptemberFirstProvider extends AbstractProvider
+/**
+ * Провайдер данных Первого сентября
+ */
+class SeptemberFirstProvider extends GenericProvider
 {
     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';
-    const API_VERSION = '2.0';
 
-    public function getBaseAuthorizationUrl(): string
+    /**
+     * @var string[] Разрешения (scopes) по умолчанию
+     */
+    const SCOPES_DEFAULT = ['profile'];
+
+    /**
+     * @var string Разделитель перечня запрашиваемых разрешений
+     */
+    const SCOPES_SEPARATOR = ' ';
+
+    /**
+     * @var string Путь авторизации
+     */
+    const AUTHORIZE_PATH = '/oauth/authorize';
+
+    /**
+     * @var string Путь получения токена
+     */
+    const ACCESS_TOKEN_PATH = '/oauth/access_token';
+
+    /**
+     * @var string Путь получения данных пользователя
+     */
+    const USERINFO_PATH = '/2.0/userinfo';
+
+    /**
+     * Constructor
+     *
+     * @param mixed[] $options
+     * @param object[] $collaborators
+     */
+    public function __construct(array $options = [], array $collaborators = [])
     {
-        return static::AUTH_BASE.'/oauth/authorize';
+        $authBase = $options['authBase'] ?? static::AUTH_BASE;
+        $apiBase  = $options['apiBase']  ?? static::API_BASE;
+
+        $defaultOptions = [
+            'urlAuthorize' => $authBase.static::AUTHORIZE_PATH,
+            'urlAccessToken' => $apiBase.static::ACCESS_TOKEN_PATH,
+            'urlResourceOwnerDetails' => $apiBase.static::USERINFO_PATH,
+            'scopes' => static::SCOPES_DEFAULT,
+            'scopeSeparator' => static::SCOPES_SEPARATOR,
+        ];
+
+        parent::__construct(array_merge($defaultOptions, $options), $collaborators);
     }
 
-    public function getBaseAccessTokenUrl(array $params): string
+    /**
+     * Checks a provider response for errors.
+     *
+     * @param ResponseInterface $response
+     * @param mixed[]|string $data — Parsed response data
+     * @return void
+     *
+     * @throws IdentityProviderException
+     */
+    protected function checkResponse(ResponseInterface $response, $data): void
     {
-        return static::API_BASE.'/oauth/access_token';
-    }
-
-    public function getResourceOwnerDetailsUrl(AccessToken $token): string
-    {
-        return static::API_BASE.'/'.static::API_VERSION.'/userinfo';
-    }
-
-    public function getDefaultScopes(): array
-    {
-        return ['basic'];
-    }
-
-    protected function getScopeSeparator(): string
-    {
-        return ' ';
-    }
-
-    protected function checkResponse(ResponseInterface $response, $data)
-    {
-        if (!empty($data['error'])) {
-            throw new IdentityProviderException($data['error'].': '.$data['message'], null, $response);
+        if (isset($data['error'])) {
+            throw new IdentityProviderException($data['error']. (isset($data['message']) ? ': '.$data['message'] : ''), 0, $response);
         }
     }
 
+    /**
+     * Generates a resource owner object from a successful resource owner details request.
+     *
+     * @param mixed[] $response
+     * @param AccessToken $token
+     * @return SeptemberFirstUser
+     */
     protected function createResourceOwner(array $response, AccessToken $token): SeptemberFirstUser
     {
         return new SeptemberFirstUser($response);

src/Provider/SeptemberFirstUser.php

@@ -1,18 +1,23 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace Sept\OAuth2\Client\Provider;
 
 use League\OAuth2\Client\Provider\ResourceOwnerInterface;
 
+/**
+ * Пользователь Первого сентября
+ */
 class SeptemberFirstUser implements ResourceOwnerInterface
 {
-    /**
-     * @var array Массив с данными о пользователе
-     */
-    protected $data;
+    const AVATAR_BASE = 'https://avatar.1sept.ru';
 
     /**
-     * Конструктор
+     * @var mixed[] Массив с данными о пользователе
+     */
+    protected array $data;
+
+    /**
+     * @param mixed[] $response
      */
     public function __construct(array $response)
     {
@@ -20,38 +25,11 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * Значение массива (многомерного)
+     * Массив с данными о пользователе
      *
-     * @param string $key Ключ поля (например: `email` или `name.first` — вложенность оформляется точкой)
-     * @return mixed|null
+     * @return mixed[]
      */
-    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;
     }
@@ -60,6 +38,7 @@ class SeptemberFirstUser implements ResourceOwnerInterface
      * ID пользователя (UUID)
      *
      * @return string
+     * @example '1cc1632f-2349-4d00-8302-5c4c188469cc'
      */
     public function getId(): string
     {
@@ -68,7 +47,7 @@ class SeptemberFirstUser implements ResourceOwnerInterface
 
     /**
      * Устаревшие ID пользователя (UUID)
-     * Эти ID остаются после объединения уч. записей.
+     * (остаются после объединения уч. записей)
      *
      * @return array<string>
      */
@@ -78,7 +57,9 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Фамилия
+     *
+     * @return string|null
      */
     public function getLastName(): ?string
     {
@@ -86,7 +67,9 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Имя
+     *
+     * @return string|null
      */
     public function getFirstName(): ?string
     {
@@ -94,7 +77,9 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Отчество
+     *
+     * @return string|null
      */
     public function getMiddleName(): ?string
     {
@@ -102,7 +87,7 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * Девичья фамилия пользователя (только для женского пола)
+     * Девичья фамилия
      *
      * @return string|null
      */
@@ -112,7 +97,9 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Отображаемое имя
+     *
+     * @return string|null
      */
     public function getDisplayName(): ?string
     {
@@ -120,7 +107,9 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Пол
+     *
+     * @return 'male'|'female'|null
      */
     public function getSex(): ?string
     {
@@ -128,7 +117,29 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Регалии
+     *
+     * @return string|null
+     */
+    public function getRegalia(): string|null
+    {
+        return $this->getField('regalia');
+    }
+
+    /**
+     * Умер
+     *
+     * @return bool|null
+     */
+    public function isDied(): ?bool
+    {
+        return $this->getField('is_died');
+    }
+
+    /**
+     * Эл. адрес
+     *
+     * @return string|null
      */
     public function getEmail(): ?string
     {
@@ -136,72 +147,416 @@ class SeptemberFirstUser implements ResourceOwnerInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Дата рождения
+     *
+     * @return \DateTime|null
      */
     public function getBirthday(): ?\DateTime
     {
-        return !empty($this->data['birthday']) ? new \DateTime($this->data['birthday']) : null;
+        return isset($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
+     * URL аватарки (150x150)
      *
-     * @param bool $rejectEmptyAvatar Если true, то пустые аватарки (заглушки) не отдаются
+     * @param bool $rejectDefaultAvatar
+     * @return string|null
+     *
+     * @example https://avatar.1sept.ru/12121212-3456-7243-2134-432432144221.jpeg?v=12345
+     */
+    public function getAvatarUrl(bool $rejectDefaultAvatar = false): ?string
+    {
+        return ($rejectDefaultAvatar && ($this->isDefaultAvatar() ?? false)) ? null : $this->getField('avatar');
+    }
+
+    /**
+     * 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 getAvatar50Url(bool $rejectEmptyAvatar = false): ?string
+    public function getAvatarSizeUrl(int $size, int $ratioMultiplier = 1, bool $addVersion = true): ?string
     {
-        return $this->getAvatarUrl($rejectEmptyAvatar);
+        $ratio = ($ratioMultiplier > 1) ? '@' . $ratioMultiplier . 'x' : '';
+        $url = static::AVATAR_BASE .'/'. $this->getId() . (((bool) $size)? '.' : '') . $size . $ratio . '.jpeg';
+        return $url . ($addVersion ? $this->getAvatarVersionQuery() : '');
     }
 
     /**
-     * {@inheritdoc}
+     * 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 $addVersion Использовать версию аватарки для улучшенного кэширования
+     * @return string|null
+     *
+     * @example https://avatar.1sept.ru/12121212-3456-7243-2134-432432144221.max.jpeg?v=12345
+     */
+    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 bool|null
+     */
+    public function isDefaultAvatar(): ?bool
+    {
+        return (bool) $this->getField('avatar_default');
+    }
+
+    /**
+     * Query строка c версией аватарки (улучшает кэширование)
+     *
+     * @return string
+     * @example ?v=12345;
+     */
+    public function getAvatarVersionQuery(): string
+    {
+        $query = '';
+        $version = $this->getField('avatar_version');
+        if ((bool) $version) {
+            $query .= '?v=' . $version;
+        }
+        return $query;
+    }
+
+    /**
+     * URL публичной страницы профиля
+     *
+     * @return string|null
+     * @example https://vk.com/hello
      */
     public function getProfileUrl(): ?string
     {
-        return $this->getField('profile_url');
+        return $this->getField('link');
     }
 
     /**
-     * Номер телефона
+     * Номера телефонов
      *
-     * @return string|null
+     * @return array<int, array<string, string>>
+     * @example [
+     *   [
+     *     "canonical" => "+79161234567",
+     *     "number" => "+7 (916) 123-45-67",
+     *     "type" => "mobile"
+     *   ],
+     *   …
+     * ]
      */
-    public function getPhone(): ?string
+    public function getPhones(): ?array
     {
-        return null;
+        return $this->getField('phones');
     }
 
     /**
-     * Локаль
+     * СНИЛС
      *
      * @return string|null
+     * @example 123-456-789 01
+     */
+    public function getSnils(): ?string
+    {
+        return $this->getField('passport.snils');
+    }
+
+    /**
+     * Локаль (языковые и др. настройки)
+     *
+     * @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');
     }
+
+    /**
+     * ID адреса
+     *
+     * @return int|null
+     * @example 12345
+     */
+    public function getAddressID(): ?int
+    {
+        $id = $this->getField('address.id');
+        return ((bool) $id) ? ((int) $id) : null;
+    }
+
+    /**
+     * ID страны адреса
+     *
+     * @return string|null
+     * @example RU
+     */
+    public function getAddressCountryID(): ?string
+    {
+        return $this->getField('address.country_id');
+    }
+
+    /**
+     * ID региона страны адреса
+     *
+     * @return string|null
+     * @example MOW
+     */
+    public function getAddressRegionID(): ?string
+    {
+        return $this->getField('address.region_id');
+    }
+
+    /**
+     * Почтовый индекс
+     *
+     * @return string|null
+     * @example 123456
+     */
+    public function getAddressPostalcode(): ?string
+    {
+        return $this->getField('address.postal_code');
+    }
+
+    /**
+     * Район
+     *
+     * @return string|null
+     * @example Октябрьский район
+     */
+    public function getAddressArea(): ?string
+    {
+        return $this->getField('address.area');
+    }
+
+    /**
+     * Город
+     *
+     * @return string|null
+     * @example Муром
+     */
+    public function getAddressCity(): ?string
+    {
+        return $this->getField('address.city');
+    }
+
+    /**
+     * Улица
+     *
+     * @return string|null
+     * @example ул. Профсоюзная
+     */
+    public function getAddressStreet(): ?string
+    {
+        return $this->getField('address.street');
+    }
+
+    /**
+     * Здание, сооружение, дом, владение, объект незавершенного строительства
+     *
+     * @return string|null
+     * @example д. 5
+     */
+    public function getAddressHouse(): ?string
+    {
+        return $this->getField('address.house');
+    }
+
+    /**
+     * Строение
+     *
+     * @return string|null
+     * @example стр. 5
+     */
+    public function getAddressBuilding(): ?string
+    {
+        return $this->getField('address.building');
+    }
+
+    /**
+     * Помещение в пределах здания, сооружения (Квартира, офис, помещение и т.д.)
+     *
+     * @return string|null
+     * @example кв. 1б | оф. 13 | помещ. 17
+     */
+    public function getAddressFlat(): ?string
+    {
+        return $this->getField('address.flat');
+    }
+
+    /**
+     * До востребования
+     *
+     * @return boolean
+     * @example true
+     */
+    public function isAddressGeneralDelivery(): bool
+    {
+        return (bool) $this->getField('address.general_delivery');
+    }
+
+    /**
+     * Абонентский ящик (А/Я)
+     *
+     * @return string|null
+     * @example а/я 123
+     */
+    public function getAddressPostalBox(): ?string
+    {
+        return $this->getField('address.postal_box');
+    }
+
+    /**
+     * Организация по адресу
+     *
+     * @return string|null
+     * @example Школа №5
+     */
+    public function getAddressOrganization(): ?string
+    {
+        return $this->getField('address.organization');
+    }
+
+    /**
+     * Почтовый адрес в строку (без индекса)
+     *
+     * @return string|null
+     * @example ул. Гагарина, д.5, кв. 21, Нижний Новгород
+     */
+    public function getAddressInline(): ?string
+    {
+        return $this->getField('address.inline');
+    }
+
+    /**
+     * ID страны (анкета)
+     *
+     * @return string|null
+     * @example RU
+     */
+    public function getLocationCountryID(): ?string
+    {
+        return $this->getField('location.country_id');
+    }
+
+    /**
+     * Название страны (анкета)
+     *
+     * @return string|null
+     * @example Россия
+     */
+    public function getLocationCountryName(): ?string
+    {
+        return $this->getField('location.country_name');
+    }
+
+    /**
+     * Название страны по английски (анкета)
+     *
+     * @return string|null
+     * @example Russia
+     */
+    public function getLocationCountryNameEnglish(): ?string
+    {
+        return $this->getField('location.country_name_eng');
+    }
+
+    /**
+     * ID региона страны (анкета)
+     *
+     * @return string|null
+     * @example MOW
+     */
+    public function getLocationRegionID(): ?string
+    {
+        return $this->getField('location.region_id');
+    }
+
+    /**
+     * Название региона страны (анкета)
+     *
+     * @return string|null
+     * @example Москва
+     */
+    public function getLocationRegionName(): ?string
+    {
+        return $this->getField('location.region_name');
+    }
+
+    /**
+     * Название региона страны по английски (анкета)
+     *
+     * @return string|null
+     * @example Moscow
+     */
+    public function getLocationRegionNameEnglish(): ?string
+    {
+        return $this->getField('location.region_name_eng');
+    }
+
+    /**
+     * Элемент массива данных о пользователе
+     *
+     * @param string $key Ключ поля (например: email или name.first — вложенность оформляется точкой)
+     * @return mixed
+     */
+    protected function getField(string $key): mixed
+    {
+        return static::getFieldFromArray($key, $this->data);
+    }
+
+    /**
+     * Значение массива (многомерного)
+     *
+     * @param string $key Ключ поля (например: `email` или `name.first` — вложенность оформляется точкой)
+     * @param mixed[] $array
+     * @return mixed
+     */
+    public static function getFieldFromArray(string $key, ?array $array): mixed
+    {
+        if ((bool) 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;
+    }
 }

tests/UserTest.php

@@ -0,0 +1,22 @@
+<?php declare(strict_types=1);
+
+namespace Sept\OAuth2\Client\Test;
+
+use PHPUnit\Framework\Attributes\CoversMethod;
+use PHPUnit\Framework\TestCase;
+use Sept\OAuth2\Client\Provider\SeptemberFirstUser;
+
+#[CoversMethod(SeptemberFirstUser::class, 'getFirstName')]
+final class UserTest extends TestCase
+{
+    public function testCreate(): void
+    {
+        $name = 'Alex';
+        $user = new SeptemberFirstUser([
+            'personal_name' => [
+                'name' => $name,
+            ],
+        ]);
+        self::assertSame($name, $user->getFirstName());
+    }
+}