diff --git a/Classes/Command/DbDocs/Generator.php b/Classes/Command/DatabaseDocs/Generator.php similarity index 84% rename from Classes/Command/DbDocs/Generator.php rename to Classes/Command/DatabaseDocs/Generator.php index b8e7db5d7f..d30555ed39 100644 --- a/Classes/Command/DbDocs/Generator.php +++ b/Classes/Command/DatabaseDocs/Generator.php @@ -10,16 +10,14 @@ * LICENSE.txt file that was distributed with this source code. */ -namespace Kitodo\Dlf\Command\DbDocs; +namespace Kitodo\Dlf\Command\DatabaseDocs; use Doctrine\DBAL\Schema\Table; use ReflectionClass; use ReflectionProperty; -use RuntimeException; use TYPO3\CMS\Core\Database\Schema\Parser\Lexer; use TYPO3\CMS\Core\Database\Schema\Parser\Parser; use TYPO3\CMS\Core\Database\Schema\SqlReader; -use TYPO3\CMS\Core\Information\Typo3Version; use TYPO3\CMS\Core\Localization\LanguageService; use TYPO3\CMS\Core\Localization\LanguageServiceFactory; use TYPO3\CMS\Core\Utility\GeneralUtility; @@ -91,7 +89,9 @@ public function __construct() * Collect information about relevant tables from `ext_tables.sql` and the * Extbase classmap. * - * @return mixed[] Array of objects with table information + * @access public + * + * @return mixed[] An array of objects with table information */ public function collectTables(): array { @@ -122,6 +122,8 @@ public function collectTables(): array /** * Get a map from database table names to their domain model class names. * + * @access public + * * @return mixed[] Map from table name to fully qualified class name */ public function getTableClassMap(): array @@ -151,14 +153,15 @@ public function getTableClassMap(): array * @param Table $table The table to be analyzed * @param string|null $className Fully qualified name of the domain model class * - * @return object Object with table information + * @return object An object with table information */ protected function getTableInfo(Table $table, ?string $className): object { $tableName = $table->getName(); $isPrimary = []; - if (!is_null($primaryKey = $table->getPrimaryKey())) { + $primaryKey = $table->getPrimaryKey(); + if ($primaryKey != null) { foreach ($primaryKey->getUnquotedColumns() as $primaryColumn) { $isPrimary[$primaryColumn] = true; } @@ -216,6 +219,15 @@ protected function getTableInfo(Table $table, ?string $className): object return $result; } + /** + * Extract description from a property doc-comment. + * + * @access public + * + * @param string $docComment The doc-comment to be parsed + * + * @return string The extracted description + */ protected function parsePropertyDocComment(string $docComment): string { $lines = explode("\n", $docComment); @@ -230,6 +242,15 @@ protected function parsePropertyDocComment(string $docComment): string return ''; } + /** + * Extract description from a class doc-comment + * + * @access protected + * + * @param string $docComment The doc-comment to be parsed + * + * @return string The extracted description + */ protected function parseDocComment(string $docComment): string { // TODO: Consider using phpDocumentor (though that splits the docblock into summary and description) @@ -255,7 +276,9 @@ protected function parseDocComment(string $docComment): string /** * Transform table structure into .rst page. * - * @param mixed[] $tables Array of table information objects + * @access public + * + * @param mixed[] $tables An array of table information objects * * @return RstSection The generated .rst page */ @@ -270,9 +293,11 @@ public function generatePage(array $tables): RstSection RST); // Sort tables alphabetically - usort($tables, function ($lhs, $rhs) { - return $lhs->name <=> $rhs->name; - }); + usort( + $tables, function ($lhs, $rhs) { + return $lhs->name <=> $rhs->name; + } + ); foreach ($tables as $tableInfo) { $section = $page->subsection(); @@ -297,21 +322,25 @@ public function generatePage(array $tables): RstSection '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); + $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); } diff --git a/Classes/Command/DbDocs/RstSection.php b/Classes/Command/DatabaseDocs/RstSection.php similarity index 92% rename from Classes/Command/DbDocs/RstSection.php rename to Classes/Command/DatabaseDocs/RstSection.php index 1a08071d77..bbc348b25a 100644 --- a/Classes/Command/DbDocs/RstSection.php +++ b/Classes/Command/DatabaseDocs/RstSection.php @@ -10,7 +10,7 @@ * LICENSE.txt file that was distributed with this source code. */ -namespace Kitodo\Dlf\Command\DbDocs; +namespace Kitodo\Dlf\Command\DatabaseDocs; /** * Simple utility to write .rst (reStructuredText). @@ -36,6 +36,8 @@ class RstSection * * @access public * + * @static + * * @param string $text * @param array $format * @@ -59,15 +61,19 @@ public static function format(string $text, array $format = []): string * * @access public * + * @static + * * @param mixed[] $paragraphs * * @return string */ public static function paragraphs(array $paragraphs): string { - $paragraphs = array_values(array_filter($paragraphs, function ($entry) { - return !empty($entry); - })); + $paragraphs = array_values( + array_filter($paragraphs, function ($entry) { + return !empty($entry); + }) + ); return implode("\n\n", $paragraphs); } @@ -117,7 +123,7 @@ public function addText(string $text): void } /** - * Add a field list table to section. + * Add a field list table to the section. * * @access public * @@ -196,13 +202,13 @@ public function render(int $level = 0): string /** * Render header of given level. * - * @access protected + * @access private * * @param int $level * * @return string */ - protected function renderHeader(int $level): string + private function renderHeader(int $level): string { $result = ''; diff --git a/Classes/Command/DbDocsCommand.php b/Classes/Command/DatabaseDocsGenerateCommand.php similarity index 96% rename from Classes/Command/DbDocsCommand.php rename to Classes/Command/DatabaseDocsGenerateCommand.php index ad865ca07f..b763b3fa77 100644 --- a/Classes/Command/DbDocsCommand.php +++ b/Classes/Command/DatabaseDocsGenerateCommand.php @@ -12,7 +12,7 @@ namespace Kitodo\Dlf\Command; -use Kitodo\Dlf\Command\DbDocs\Generator; +use Kitodo\Dlf\Command\DatabaseDocs\Generator; use RuntimeException; use Symfony\Component\Console\Command\Command; use Symfony\Component\Console\Input\InputInterface; @@ -31,7 +31,7 @@ * * @access public */ -class DbDocsCommand extends Command +class DatabaseDocsGenerateCommand extends Command { protected Generator $generator; diff --git a/Configuration/Services.yaml b/Configuration/Services.yaml index 9a54f56f7b..23f1183893 100644 --- a/Configuration/Services.yaml +++ b/Configuration/Services.yaml @@ -7,10 +7,10 @@ services: Kitodo\Dlf\: resource: '../Classes/*' - Kitodo\Dlf\Command\DbDocsCommand: + Kitodo\Dlf\Command\DatabaseDocsGenerateCommand: tags: - name: console.command - command: 'kitodo:dbdocs' + command: 'kitodo:databaseDocsGenerate' description: 'Generate database rst file.' Kitodo\Dlf\Command\DeleteCommand: diff --git a/Documentation/Developers/Database.rst b/Documentation/Developers/Database.rst index 0fb2ae2e82..e57636319d 100644 --- a/Documentation/Developers/Database.rst +++ b/Documentation/Developers/Database.rst @@ -4,7 +4,7 @@ Database Tables 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 ``vendor/bin/typo3 kitodo:dbdocs`` from the composer-based TYPO3 install directory (not the Kitodo.Presentation source directory). +.. 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 ``vendor/bin/typo3 kitodo:databaseDocsGenerate`` from the composer-based TYPO3 install directory (not the Kitodo.Presentation source directory). tx_dlf_actionlog: Action protocol ================================= @@ -26,10 +26,10 @@ Extbase domain model: ``Kitodo\Dlf\Domain\Model\ActionLog`` :description: The id of the page the record is "stored". - :field: crdate  *integer* - :description: + :description: - :field: deleted  *smallint* - :description: + :description: - :field: user_id  *integer* :description: *User ID* @@ -69,25 +69,25 @@ Extbase domain model: ``Kitodo\Dlf\Domain\Model\Basket`` :description: The id of the page the record is "stored". - :field: tstamp  *integer* - :description: + :description: - :field: fe_user_id  *integer* :description: *FE user ID* - :field: deleted  *smallint* - :description: + :description: - :field: sys_language_uid  *integer* - :description: + :description: - :field: l18n_parent  *integer* - :description: + :description: - :field: l18n_diffsource  *blob* - :description: + :description: - :field: l10n_state  *text* - :description: + :description: - :field: label  *string* :description: *Basket* @@ -121,13 +121,13 @@ Domain model of the 'Collection'. :description: The id of the page the record is "stored". - :field: tstamp  *integer* - :description: + :description: - :field: crdate  *integer* - :description: + :description: - :field: cruser_id  *integer* - :description: + :description: - :field: fe_cruser_id  *integer* :description: *Frontend User* @@ -136,7 +136,7 @@ Domain model of the 'Collection'. :description: *Disallow frontend editing?* - :field: deleted  *smallint* - :description: + :description: - :field: sys_language_uid  *integer* :description: *Language* @@ -145,10 +145,10 @@ Domain model of the 'Collection'. :description: *Transl.Orig* - :field: l18n_diffsource  *blob* - :description: + :description: - :field: l10n_state  *text* - :description: + :description: - :field: hidden  *smallint* :description: *Hide* @@ -173,7 +173,7 @@ Domain model of the 'Collection'. - :field: thumbnail  *string* :description: *Thumbnail* - + thumbnail - :field: priority  *smallint* @@ -217,10 +217,10 @@ Domain model of the 'Document'. :description: *Created At* - :field: cruser_id  *integer* - :description: + :description: - :field: deleted  *smallint* - :description: + :description: - :field: hidden  *smallint* :description: *Hide* @@ -313,7 +313,7 @@ Domain model of the 'Document'. :description: *Owner* - :field: solrcore  *integer* - :description: + :description: - :field: status  *smallint* :description: *Status* @@ -350,35 +350,35 @@ For more information, see the documentation page on metadata. :description: The id of the page the record is "stored". - :field: tstamp  *integer* - :description: + :description: - :field: crdate  *integer* - :description: + :description: - :field: cruser_id  *integer* - :description: + :description: - :field: deleted  *smallint* - :description: + :description: - :field: type  *string* :description: *Format Name (e.g. in METS)* - + Name of the type that is used to reference it. - :field: root  *string* :description: *Root Element* - + The XML root element used by this format. - :field: namespace  *string* :description: *Namespace URI* - + The XML namespace URI used by this format. - :field: class  *string* :description: *Class Name* - + Fully qualified name of the PHP class that handles the format, or the empty string if no such class is configured. @@ -411,16 +411,16 @@ A library institution with the following use cases: :description: The id of the page the record is "stored". - :field: tstamp  *integer* - :description: + :description: - :field: crdate  *integer* - :description: + :description: - :field: cruser_id  *integer* - :description: + :description: - :field: deleted  *smallint* - :description: + :description: - :field: sys_language_uid  *integer* :description: *Language* @@ -429,10 +429,10 @@ A library institution with the following use cases: :description: *Transl.Orig* - :field: l18n_diffsource  *blob* - :description: + :description: - :field: l10n_state  *text* - :description: + :description: - :field: label  *string* :description: *Name* @@ -445,22 +445,22 @@ A library institution with the following use cases: - :field: contact  *string* :description: *Contact* - + Contact email address of the library (used as ``adminEmail`` in responses to OAI ``Identify`` requests). - :field: image  *string* :description: *Logo* - + image - :field: oai_label  *string* :description: *Open Archives Interface (OAI) Label* - + The label that is used as ``repositoryName`` in responses to OAI ``Identify`` requests - :field: oai_base  *string* :description: *Open Archives Interface (OAI) Base URL* - + OAI base URL used when harvesting the library via ``kitodo:harvest``. - :field: opac_label  *string* @@ -498,10 +498,10 @@ Extbase domain model: ``Kitodo\Dlf\Domain\Model\Mail`` :description: The id of the page the record is "stored". - :field: deleted  *smallint* - :description: + :description: - :field: sorting  *integer* - :description: + :description: - :field: mail  *string* :description: *Address* @@ -535,16 +535,16 @@ A metadata kind (title, year, ...) and its configuration for display and indexin :description: The id of the page the record is "stored". - :field: tstamp  *integer* - :description: + :description: - :field: crdate  *integer* - :description: + :description: - :field: cruser_id  *integer* - :description: + :description: - :field: deleted  *smallint* - :description: + :description: - :field: sys_language_uid  *integer* :description: *Language* @@ -553,10 +553,10 @@ A metadata kind (title, year, ...) and its configuration for display and indexin :description: *Transl.Orig* - :field: l18n_diffsource  *blob* - :description: + :description: - :field: l10n_state  *text* - :description: + :description: - :field: hidden  *smallint* :description: *Hide* @@ -572,7 +572,7 @@ A metadata kind (title, year, ...) and its configuration for display and indexin - :field: format  *integer* :description: *Data Format* - + The formats that encode this metadata (local IRRE field to ``tx_dlf_metadataformat``). - :field: default_value  *string* @@ -637,40 +637,40 @@ This contains the xpath expressions on the model 'Metadata'. :description: The id of the page the record is "stored". - :field: tstamp  *integer* - :description: + :description: - :field: crdate  *integer* - :description: + :description: - :field: cruser_id  *integer* - :description: + :description: - :field: deleted  *smallint* - :description: + :description: - :field: l10n_state  *text* - :description: + :description: - :field: parent_id  *integer* :description: UID of the ``tx_dlf_metadata`` that is encoded by this metadata entry. - :field: encoded  *integer* :description: *Encoding* - + UID of the ``tx_dlf_format`` in which this metadata entry is encoded. - :field: xpath  *string* :description: *XPath (relative to //dmdSec/mdWrap/xmlData/root and with namespace) or JSONPath (relative to resource JSON object)* - + XPath/JSONPath expression to extract the metadata (relative to the data format root). - :field: xpath_sorting  *string* :description: *XPath / JSONPath for sorting (optional)* - + XPath/JSONPath expression to extract sorting variant (suffixed ``_sorting``) of the metadata. - :field: subentries  *integer* - :description: + :description: - :field: mandatory  *smallint* :description: *Mandatory field?* @@ -704,28 +704,28 @@ This contains the xpath expressions on the model 'Metadata'. :description: The id of the page the record is "stored". - :field: parent_id  *integer* - :description: + :description: - :field: tstamp  *integer* - :description: + :description: - :field: crdate  *integer* - :description: + :description: - :field: cruser_id  *integer* - :description: + :description: - :field: deleted  *smallint* - :description: + :description: - :field: sys_language_uid  *integer* - :description: + :description: - :field: l18n_parent  *integer* - :description: + :description: - :field: l18n_diffsource  *blob* - :description: + :description: - :field: label  *string* :description: *Display Label* @@ -765,7 +765,7 @@ Extbase domain model: ``Kitodo\Dlf\Domain\Model\Printer`` :description: The id of the page the record is "stored". - :field: deleted  *smallint* - :description: + :description: - :field: print  *string* :description: *CLI command(##fileName##)* @@ -788,22 +788,22 @@ Pivot table for many-to-many relations between tables. In particular, this is us :description: Description - :field: **uid**  *integer* - :description: + :description: - :field: uid_local  *integer* - :description: + :description: - :field: uid_foreign  *integer* - :description: + :description: - :field: tablenames  *string* - :description: + :description: - :field: sorting  *integer* - :description: + :description: - :field: sorting_foreign  *integer* - :description: + :description: - :field: ident  *string* :description: An identifier to describe which tables are matched. @@ -830,28 +830,28 @@ In particular, this holds the index name of the used Solr core. :description: The uid of the record. The uid is only unique in the context of the database table. - :field: pid  *integer* - :description: + :description: - :field: tstamp  *integer* - :description: + :description: - :field: crdate  *integer* - :description: + :description: - :field: cruser_id  *integer* - :description: + :description: - :field: deleted  *smallint* - :description: + :description: - :field: label  *string* :description: *Display Label* - + Label of the core that is displayed in the backend. - :field: index_name  *string* :description: *Solr Core* - + The actual name of the Solr core. @@ -877,16 +877,16 @@ Domain model of 'Structure'. :description: The id of the page the record is "stored". - :field: tstamp  *integer* - :description: + :description: - :field: crdate  *integer* - :description: + :description: - :field: cruser_id  *integer* - :description: + :description: - :field: deleted  *smallint* - :description: + :description: - :field: sys_language_uid  *integer* :description: *Language* @@ -895,10 +895,10 @@ Domain model of 'Structure'. :description: *Transl.Orig* - :field: l18n_diffsource  *blob* - :description: + :description: - :field: l10n_state  *text* - :description: + :description: - :field: hidden  *smallint* :description: *Hide*