DatabaseDocCommand::configure() - Code Metrics - Inspection of "Documentation" - kitodo/kitodo-presentation - Measure and Improve Code Quality continuously with Scrutinizer

Passed
Pull Request — dev-extbase-fluid (#771)

unknown
created 2022-02-17 16:18 UTC
DatabaseDocCommand::configure() A

↳ Parent: DatabaseDocCommand
Complexity

Conditions	1
Paths	1
Size

Total Lines	13
Code Lines	10
Duplication

Lines	0
Ratio	0 %
Importance

Changes	1
Bugs	0	Features	0
Metric	Value
cc	1
eloc	10
c	1
b	0
f	0
nc	1
nop	0
dl	0
loc	13
rs	9.9332
<?php

/**
 * (c) Kitodo. Key to digital objects e.V. <[email protected]>
 *
 * This file is part of the Kitodo and TYPO3 projects.
 *
 * @license GNU General Public License version 3 or later.
 * For the full copyright and license information, please read the
 * LICENSE.txt file that was distributed with this source code.
 */

namespace Kitodo\Dlf\Command;

use Doctrine\DBAL\Schema\Table;
use Kitodo\Dlf\Command\BaseCommand;
use Kitodo\Dlf\Common\DbDocs\RstSection;
use Kitodo\Dlf\Common\Doc;
use Kitodo\Dlf\Common\Helper;
use Kitodo\Dlf\Domain\Model\Document;
use ReflectionClass;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;
use TYPO3\CMS\Core\Database\Schema\Parser\Parser;
use TYPO3\CMS\Core\Database\Schema\SqlReader;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Extbase\Configuration\ConfigurationManager;
use TYPO3\CMS\Extbase\Configuration\ConfigurationManagerInterface;
use TYPO3\CMS\Extbase\Object\ObjectManager;
use TYPO3\CMS\Extbase\Persistence\Generic\Mapper\DataMapper;
use TYPO3\CMS\Extbase\Reflection\DocCommentParser;
filter:
    dependency_paths: ["lib/*"]
use TYPO3\CMS\Extbase\Utility\LocalizationUtility;

/**
 * CLI command for generating database documentation.
 */
class DatabaseDocCommand extends BaseCommand
{
    /**
     * Default output path for generated documentation file.
     */
    protected $defaultOutputPath = 'EXT:dlf/Documentation/Developers/Database.rst';

    /**
     * @var ObjectManager
     */
    protected $objectManager;

    /**
     * @var DataMapper
     */
    protected $dataMapper;

    /**
     * Configure the command by defining the name, options and arguments
     */
    public function configure()
    {
        $this->objectManager = GeneralUtility::makeInstance(ObjectManager::class);
        $this->dataMapper = $this->objectManager->get(DataMapper::class);

        $this
            ->setDescription('Aggregate database documentation from doc-comments, SQL COMMENT fields and TCA labels')
            ->setHelp('')
            ->addOption(
                'output',
                'o',
                InputOption::VALUE_OPTIONAL,
                'Path of the output documentation file. Default: ' . $this->defaultOutputPath
            );
    }

    /**
     * Execute the command.
     */
    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $outputPath = $input->getOption('output') ?? GeneralUtility::getFileAbsFileName($this->defaultOutputPath);

        $io = new SymfonyStyle($input, $output);
        $io->title($this->getDescription());

        $tables = $this->collectTables();
        $page = $this->generatePage($tables);

        file_put_contents($outputPath, $page->render());

        $io->success('All done!');

        return 0;
    }

    /**
     * Collect information about relevant tables from `ext_tables.sql` and the
     * Extbase classmap.
     */
    protected function collectTables(): array
    {
        $sqlReader = GeneralUtility::makeInstance(SqlReader::class);
        $sqlCode = $sqlReader->getTablesDefinitionString(true);
        $createTableStatements = $sqlReader->getCreateTableStatementArray($sqlCode);

        $tableToClassName = $this->getTableClassMap();

        $result = [];

        foreach ($createTableStatements as $statement) {
            $parser = new Parser($statement);
            list($table) = $parser->parse();

            $tableName = $table->getName();
            if (!str_starts_with($tableName, 'tx_dlf_')) {
                continue;
            }

            $className = $tableToClassName[$tableName] ?? null;

            $result[] = $this->getTableInfo($table, $className);
        }

        return $result;
    }

    /**
     * Collect information about a single table.
     *
     * @param Table $table The table to be analyzed
     * @param string|null $className Fully qualified name of the domain model class
     */
    protected function getTableInfo(Table $table, ?string $className): object
    {
        $tableName = $table->getName();

        $isPrimary = [];
        if (!is_null($primaryKey = $table->getPrimaryKey())) {
            foreach ($primaryKey->getUnquotedColumns() as $primaryColumn) {
                $isPrimary[$primaryColumn] = true;
            }
        }

        $columns = [];
        foreach ($table->getColumns() as $column) {
            $columnName = $column->getName();

            $columns[$columnName] = (object) [
                'name' => $columnName,
                'type' => $column->getType(),
                'isPrimary' => isset($isPrimary[$columnName]),
                'sqlComment' => $column->getComment() ?? '',
                'fieldComment' => '',
                'feComment' => LocalizationUtility::translate($GLOBALS['TCA'][$tableName]['columns'][$columnName]['label'] ?? '') ?? '',
            ];
        }

        $result = (object) [
            'name' => $tableName,
            'columns' => $columns,
            'modelClass' => null,
            'sqlComment' => $table->getComment() ?? '',
            'classComment' => '',
            'feComment' => LocalizationUtility::translate($GLOBALS['TCA'][$tableName]['ctrl']['title'] ?? '') ?? '',
        ];

        // Integrate doc-comments from model class and its fields
        if ($className !== null) {
            $reflection = new ReflectionClass($className);

            $dataMap = $this->dataMapper->getDataMap($className);

            foreach ($reflection->getProperties() as $property) {
                $column = $dataMap->getColumnMap($property->getName());
                if ($column !== null) {
                    $result->columns[$column->getColumnName()]->fieldComment = $this->parseDocComment($property->getDocComment());
                }
            }

            $result->modelClass = $className;
            $result->classComment = $this->parseDocComment($reflection->getDocComment());
        }

        return $result;
    }

    protected function parseDocComment($docComment)
    {
        $fieldDocParser = new DocCommentParser();
        $fieldDocParser->parseDocComment($docComment);

        $text = $fieldDocParser->getDescription();
        $lines = explode("\n", $text);
        $lines = array_map(function ($line) {
            // There may be a single non-signifying space after the doc-comment asterisk
            return $line[0] === ' '
                ? substr($line, 1)
                : $line;
        }, $lines);
        $text = implode("\n", $lines);

        return $text;
    }

    /**
     * Get a map from database table names to their domain model class names.
     */
    protected function getTableClassMap(): array
    {
        Helper::polyfillExtbaseClassesForTYPO3v9();
        /** @scrutinizer ignore-deprecated */ Helper::polyfillExtbaseClassesForTYPO3v9();

        $configurationManager = $this->objectManager->get(ConfigurationManager::class);
        $configurationManager = /** @scrutinizer ignore-deprecated */ $this->objectManager->get(ConfigurationManager::class);
        $frameworkConfiguration = $configurationManager->getConfiguration(ConfigurationManagerInterface::CONFIGURATION_TYPE_FRAMEWORK);

        $result = [];

        foreach ($frameworkConfiguration['persistence']['classes'] as $className => $tableConf) {
            // Check that the class is ours. This is relevant if some other extension
            // such as slub_digitalcollections adds its own model of a tx_dlf_* table.
            if (!str_starts_with($className, 'Kitodo\\Dlf\\')) {
                continue;
            }

            $tableName = $tableConf['mapping']['tableName'];
            $result[$tableName] = $className;
        }

        return $result;
    }

    /**
     * Transform table structure into .rst page.
     */
    protected function generatePage(array $tables)
    {
        $page = new RstSection();
        $page->setHeader('Database Tables');
        $page->addText(<<<RST
This is a reference of all database tables defined by Kitodo.Presentation.

.. tip:: This page is auto-generated. If you would like to edit it, please use doc-comments in the model class, COMMENT fields in ``ext_tables.sql`` if the table does not have one, or TCA labels. Then, you may re-generate the page by running ``typo3 kitodo:dbdocs`` in an installation of Kitodo.Presentation (e.g., within a DDEV container).
RST);

        // Sort tables alphabetically
        usort($tables, function ($lhs, $rhs) {
            return $lhs->name <=> $rhs->name;
        });

        foreach ($tables as $tableInfo) {
            $section = $page->subsection();

            // Set header
            $header = $tableInfo->name;
            if (!empty($tableInfo->feComment)) {
                $header .= ': ' . $tableInfo->feComment;
            }
            $section->setHeader($header);

            // Set introductory text of subsection
            if ($tableInfo->modelClass) {
                $section->addText('Extbase domain model: ``' . $tableInfo->modelClass . '``');
            }
            $section->addText($tableInfo->classComment);
            $section->addText($tableInfo->sqlComment);

            // Generate main table
            $header = [[
                'field' => 'Field',
                'description' => 'Description',
            ]];

            $rows = array_map(function ($column) use ($page) {
                return [
                    'field' => (
                        $page->format($column->name, ['bold' => $column->isPrimary])
                        . "\u{00a0}\u{00a0}"
                        . $page->format($column->type->getName(), ['italic' => true])
                    ),

                    'description' => $page->paragraphs([
                        $page->format($column->feComment, ['italic' => true]),
                        $column->fieldComment,
                        $column->sqlComment,
                    ]),
                ];
            }, $tableInfo->columns);

            $section->addTable($rows, $header);
        }

        return $page;
    }
}

Scrutinizer GitHub App not installed

GitHub Access Token became invalid

Pull Request — dev-extbase-fluid (#771)

DatabaseDocCommand::configure() A

Complexity

Size

Duplication

Importance

kitodo / kitodo-presentation

Scrutinizer GitHub App not installed

GitHub Access Token became invalid

Pull Request — dev-extbase-fluid (#771)

DatabaseDocCommand::configure() A

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like
