Bitrix24 Apps & BITRIX24-PHP-SDK: “Текущее положение дел Разработчики из Битрикс24 релизят новые методы и…”

Текущее положение дел
Разработчики из Битрикс24 релизят новые методы и расширяют старые — добавляют в них поля

Задача
Сделать автоматическую проверку соответствия актуальности phpdoc документации во всех сущностях bitrix24-php-sdk.
Пример аннотации для контакта


/**
* @property-read array<int,int>|null $COMPANY_IDS
* @property-read int $CREATED_BY_ID
* @property-read CarbonImmutable $DATE_CREATE
* @property-read CarbonImmutable $DATE_MODIFY
* @property-read int|null $FACE_ID
* @property-read bool $EXPORT
* @property-read Email[] $EMAIL
* @property-read int $ID
* @property-read bool $HAS_EMAIL
*/

Эти аннотации используются в работе IDE и именно они обеспечивают полноту и правильность автокомплита.

Решение
Автоматическая сверка аннотаций с набором полей который возрващает Битрикс24.

Для чтения аннотаций в рантайме используется библиотека https://github.com/typhoon-php/typhoon

В phpunit добавлен кастомный ассерт


trait CustomBitrix24Assertions
{
    /**
     * @param array<int, non-empty-string> $fieldCodesFromApi
     * @param class-string $resultItemClassName
     * @return void
     */
    protected function assertBitrix24AllResultItemFieldsAnnotated(array $fieldCodesFromApi, string $resultItemClassName): void
    {
        sort($fieldCodesFromApi);

        // parse keys from phpdoc annotation
        $props = TyphoonReflector::build()->reflectClass($resultItemClassName)->properties();
        $propsFromAnnotations = [];
        foreach ($props as $meta) {
            if ($meta->isAnnotated() && !$meta->isNative()) {
                $propsFromAnnotations[] = $meta->id->name;
            }
        }
        sort($propsFromAnnotations);

        $this->assertEquals($fieldCodesFromApi, $propsFromAnnotations,
            sprintf('in phpdocs annotations for class %s we not found fields from actual api response: %s',
                $resultItemClassName,
                implode(', ', array_values(array_diff($fieldCodesFromApi, $propsFromAnnotations)))
            ));
    }
}

и теперь на любую сущность Битрикс24 можно навесить новый тип теста — проверка актуальности документации


public function testAllSystemFieldsAnnotated(): void
{
    $propListFromApi = (new Core\Fields\FieldsFilter())->filterSystemFields(array_keys($this->contactService->fields()->getFieldsDescription()));
    $this->assertBitrix24AllResultItemFieldsAnnotated($propListFromApi, ContactItemResult::class);
}