Как мы приручили рутину в 1C-Битрикс: автоматизация разработки CLI-командами

use Bitrix\Main\Localization\Loc;
use NLMK\Bitrix\Mate\Action\Doc\OrmPlantUmlAction;
use RuntimeException;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Throwable;
 
class CreateOrmPlantUmlCommand extends Command
{
 
    protected function configure()
    {
        $this
            ->setName('doc:orm-plant-uml')
            ->setDescription('Генерирует plantuml')
            ->setHelp('Эта команда позволяет сгенерировать plantuml для orm')
            ->addArgument('path', InputArgument::REQUIRED, 'Путь до файла класса')
            ->addOption('recursive', 'r', InputOption::VALUE_NONE, 'Рекурсивно отразить все связи')
        ;
    }
 
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        try {
            $path = $input->getArgument('path');
            $isRecursive = $input->getOption('recursive') ?? false;
 
            if (!$path) {
                throw new RuntimeException('Path is required');
            }
 
            $filePath = (new OrmPlantUmlAction())->run($path, $isRecursive);
 
            $output->writeln(Loc::getMessage('NLMK_BITRIX_MATE_COMMAND_DOC_PLANT_UML_SUCCESS', [
                '#DOC_PATH#' => $filePath,
            ]));
 
            return Command::SUCCESS;
 
        } catch (Throwable $throwable) {
            $output->writeln(Loc::getMessage('NLMK_BITRIX_MATE_COMMAND_DOC_PLANT_UML_ERROR', [
                '#ERROR#' => $throwable->getMessage()
            ]));
        }
 
        return Command::FAILURE;
    }
 
}

use Bitrix\Main\Entity\ScalarField;
use Bitrix\Main\ORM\Data\DataManager;
use Bitrix\Main\ORM\Fields\Relations\Reference;
use NLMK\Bitrix\Mate\Service\PathService;
use RuntimeException;
 
class OrmPlantUmlAction
{
 
    protected PathService $pathService;
 
    public function __construct()
    {
        $this->pathService = new PathService();
    }
 
    public function run(string $pathClass, bool $isRecursive): string
    {
        //получаем полный путь к файлу
        $filePath = sprintf('%s/%s', $this->pathService->root(), $pathClass);
 
        if (!file_exists($filePath)) {
            throw new RuntimeException('The file does not exist');
        }
 
        require_once $filePath;
 
        //получаем класс из файла
        $classes = get_declared_classes();
        $className = end($classes);
 
        if (!is_subclass_of($className, DataManager::class)) {
            throw new RuntimeException('The file does not contain a DataManager class');
        }
 
        //собираем информацию о полях
        $entities = [$className => $this->processEntity($className)];
 
        $umlContent = ["@startuml"];
        $referenceContent = [];
        foreach ($entities as $content) {
            $umlContent = [...$umlContent, ...$content['structure']];
 
            if (!$isRecursive) {
                continue;
            }
 
            $this->processReferences(
                content: $content,
                umlContent: $umlContent,
                entities: $entities,
                referenceContent: $referenceContent
            );
        }
 
        $umlContent = [...$umlContent, ...$referenceContent];
 
        $umlContent[] = "@enduml";
 
        //puml складываем рядом с ORM-классом
        $outputPath = preg_replace('/\.php$/', '.puml', $filePath);
        file_put_contents($outputPath, implode("\n", $umlContent));
 
        return $outputPath;
    }
 
    protected function processEntity(string $className): array
    {
        /** @var DataManager $entity */
        $entity = new $className();
        $entityName = $entity::getTableName();
        $structure = ["entity $entityName {"];
        $references = [];
 
        foreach ($entity::getMap() as $field) {
            //собираем информацию об обычных полях
            if ($field instanceof ScalarField) {
                $fieldLine = "  {$field->getName()} : {$field->getDataType()}";
                if ($field->isPrimary()) {
                    $fieldLine .= " <<PK>>";
                }
                if (!$field->isNullable()) {
                    $fieldLine .= " <<Mandatory>>";
                }
                if (!$field->getTitle()) {
                    $fieldLine .= " -- {$field->getTitle()}";
                }
                $structure[] = $fieldLine;
                continue;
            }
 
            //собираем информацию о рефересных полях
            if ($field instanceof Reference) {
                $refEntity = $field->getRefEntity();
                $references[] = [
                    'class' => $refEntity->getDataClass(),
                    'field' => $field->getName(),
                    'thisEntity' => $entityName,
                    'refEntity' => $refEntity->getDataClass()::getTableName(),
                ];
            }
        }
 
        $structure[] = "}";
 
        return ['structure' => $structure, 'references' => $references];
    }
 
    protected function processReferences(array $content, array &$umlContent, array &$entities, array &$referenceContent): void
    {
        //проходимся по всем рефересным полям
        foreach ($content['references'] as $reference) {
            if (!isset($entities[$reference['class']])) {
                //получаем информацию о сущности
                $referenceEntityContent = $this->processEntity($reference['class']);
                //добавялем в общий массив чтобы так же отразить всю структуру и ее референсные сущности
                $entities[$reference['class']] = $referenceEntityContent;
                $umlContent = [...$umlContent, ...$entities[$reference['class']]['structure']];
                $this->processReferences($referenceEntityContent, $umlContent, $entities, $referenceContent);
            }
            $referenceContent[] = "{$reference['thisEntity']}::{$reference['field']} ||--|| {$reference['refEntity']}";
        }
    }
}

use Bitrix\Main\ORM\Data\DataManager;
use Bitrix\Main\ORM\Fields\IntegerField;
use Bitrix\Main\ORM\Fields\Relations\Reference;
use Bitrix\Main\ORM\Fields\StringField;
use Bitrix\Main\ORM\Query\Join;
 
class MyDictionaryEntityTable extends DataManager
{
    public static function getTableName()
    {
        return 'my_dictionary_entity';
    }
 
    public static function getMap()
    {
        return [
            (new IntegerField('ID'))->configurePrimary()->configureAutocomplete(),
            (new StringField('NAME'))->configureRequired()->configureTitle('Наименование'),
        ];
    }
}
 
class MyParentEntityTable extends DataManager
{
    public static function getTableName()
    {
        return 'my_parent_entity';
    }
 
    public static function getMap()
    {
        return [
            (new IntegerField('ID'))->configurePrimary()->configureAutocomplete(),
            (new StringField('NAME'))->configureRequired()->configureTitle('Наименование'),
            (new IntegerField('DICTIONARY_ID'))->configureNullable()->configureTitle('Справочник'),
            (new Reference(
                'DICTIONARY',
                MyDictionaryEntityTable::class,
                Join::on('this.DICTIONARY_ID', 'ref.ID')
            ))
        ];
    }
}
 
class MyChildEntityTable extends DataManager
{
    public static function getTableName()
    {
        return 'my_child_entity';
    }
 
    public static function getMap()
    {
        return [
            (new IntegerField('ID'))->configurePrimary()->configureAutocomplete(),
            (new StringField('NAME'))->configureRequired()->configureTitle('Наименование'),
            (new IntegerField('PARENT_ID'))->configureNullable()->configureTitle('Родитель'),
            (new Reference(
                'PARENT',
                MyParentEntityTable::class,
                Join::on('this.PARENT_ID', 'ref.ID')
            ))
        ];
    }
}

@startuml
entity my_child_entity {
  ID : integer <<PK>> <<Mandatory>> -- ID
  NAME : string <<Mandatory>> -- Наименование
  PARENT_ID : integer -- Родитель
}
entity my_parent_entity {
  ID : integer <<PK>> <<Mandatory>> -- ID
  NAME : string <<Mandatory>> -- Наименование
  DICTIONARY_ID : integer -- Справочник
}
entity my_dictionary_entity {
  ID : integer <<PK>> <<Mandatory>> -- ID
  NAME : string <<Mandatory>> -- Наименование
}
my_parent_entity::DICTIONARY ||--|| my_dictionary_entity
my_child_entity::PARENT ||--|| my_parent_entity
@enduml

<?php
 
namespace Nlmk\Components;

use Bitrix\Main\Engine\ActionFilter\HttpMethod;
use Bitrix\Main\Engine\ActionFilter\Csrf;
use Bitrix\Main\Engine\Contract\Controllerable;
use Bitrix\Main\Engine\Response\AjaxJson;
use Bitrix\Main\Error;
use Bitrix\Main\Errorable;
use Bitrix\Main\ErrorCollection;
use Bitrix\Main\Localization\Loc;
use CBitrixComponent;
use Throwable;
 
class Test extends CBitrixComponent implements Controllerable, Errorable
{
    protected ErrorCollection $errorCollection;
 
    public function __construct($component = null)
    {
        $this->errorCollection = new ErrorCollection();
        parent::__construct($component);
    }
     
    public function executeComponent(): void
    {
        try {
            //@TODO: your code
        } catch (Throwable $throwable) {
            //@TODO: log $throwable->getMessage()
            //@TODO $this->setError(Loc::getMessage('YOUR_SYSTEM_LANG_CODE');
        }
        if (!$this->errorCollection->isEmpty()) {
            $this->arResult['ERRORS'] = $this->getErrors();
        }
        $this->includeComponentTemplate();
    }
     
     public function configureActions(): array
    {
        return [
            /** @see self::getAction() */
            'get' => [
                'prefilters' => [
                    new HttpMethod([HttpMethod::METHOD_POST]),
                    new Csrf(),
                ],
            ],
        ];
    }
     
    public function getAction(): AjaxJson
    {
        $returnData = [];
        try {
            //@TODO: your code
        } catch (Throwable $throwable) {
            //@TODO: log $throwable->getMessage()
            //@TODO $this->setError(Loc::getMessage('YOUR_SYSTEM_LANG_CODE');
        }
 
        return $this->responseAjax($returnData);
    }
     
     /**
     * @param string $message
     *
     * @return void
     */
    protected function setError(string $message): void
    {
        $this->errorCollection->setError(new Error($message));
    }
     
    /**
     * @inheritDoc
     */
    public function getErrors(): array
    {
        return $this->errorCollection->toArray();
    }
 
    /**
     * @inheritDoc
     */
    public function getErrorByCode($code): Error
    {
        return $this->errorCollection->getErrorByCode($code);
    }
     
    protected function listKeysSignedParameters(): array
    {
        return [
            //@TODO your params
        ];
    }
     
    /**
     * @param array|null $data
     *
     * @return AjaxJson
     */
    protected function responseAjax(?array $data = []): AjaxJson
    {
        return new AjaxJson(
            $data,
            $this->errorCollection->isEmpty() ? AjaxJson::STATUS_SUCCESS : AjaxJson::STATUS_ERROR,
            $this->errorCollection
        );
    }
}