Wire up orm:mapping:describe command

[stlgaits]

Feature Request / RFC

Not sure whether this belongs here in DoctrineBundle or in ORM repo but I was wondering whether people were interested in adding a simple debug / info console command which prints out Doctrine Entities field mapping.

As far as I'm aware, the only related debug commands currently available are :

• bin/console doctrine:mapping:info which outputs a basic list of mapped entities
• bin/console orm:mapping:describe <EntityClassName> (https://github.com/doctrine/orm/blob/3.3.x/src/Tools/Console/Command/MappingDescribeCommand.php) which provides complete metadata (including field mapping) for a specific entity. However, this command iis not shipped by default with Symfony DoctrineBundle and must be manually registered in the project’s service container.

Proposal

I would like to add an 'in-between' command which would return a simplified list of entity field mappings - i.e. field names and their types, as I find the orm:mapping:describe command way too verbose for my use case and would prefer a lighter alternative.

Motivation

I originally came up with this idea while frequently switching between files in my project just to check an entity's fields when writing Doctrine queries (especially with QueryBuilder), which becomes cumbersome when working with value objects, embedded fields, etc.
Having a lightweight console command would be a quick win to enhance DX and save time.

Implementation

I've implemented a prototype for this command (with some inspiration from the 2 commands mentioned above) in a work project. It allows you to pass a specific entity class name as an argument, or list all entities if no argument is given. Here is my current implementation :

use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\Console\Attribute\Argument;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Style\SymfonyStyle;

#[AsCommand(
    name: 'app:debug-doctrine-mapping',
    description: 'Displays mapped fields of a Doctrine entity.',
)]
final class DebugDoctrineEntitiesCommand extends Command
{
    public function __construct(
        private readonly EntityManagerInterface $entityManager
    ) {
        parent::__construct();
    }

    public function __invoke(
        SymfonyStyle $io,
        #[Argument(description: 'The fully qualified class name of the entity', name: 'entity')]
        string|null $entityClass = null,
    ): int {
        $io->title('Debug Doctrine Entity Field Mapping');

        if (null !== $entityClass) {
            if (!class_exists($entityClass)) {
                $io->error(sprintf('Class: %s does not exist', $entityClass));

                return Command::FAILURE;
            }
            $io->text(sprintf('Listing properties for entity: %s', $entityClass));

            $this->renderEntityMapping($io, $entityClass);

            return Command::SUCCESS;
        }

        $driver = $this->entityManager->getConfiguration()->getMetadataDriverImpl();

        if (null === $driver) {
            $io->error('No metadata driver configured.');

            return Command::FAILURE;
        }

        $io->text('Listing properties for all mapped Doctrine entities...');

        $entityClasses = $driver->getAllClassNames();

        if (!$entityClasses) {
            $io->getErrorStyle()->caution(
                [
                    'You do not have any mapped Doctrine ORM entities according to the current configuration.',
                    'If you have entities or mapping files you should check your mapping configuration for errors.',
                ],
            );

            return Command::FAILURE;
        }

        foreach ($entityClasses as $entityClass) {
            try {
                $this->renderEntityMapping($io, $entityClass);
            } catch (\Exception $exception) {
                $io->error($exception->getMessage());
            }
        }

        return Command::SUCCESS;
    }

    private function renderEntityMapping(SymfonyStyle $io, string $entityClass): void
    {
        /** @var class-string<object> $entityClass */
        $metadata = $this->entityManager->getClassMetadata($entityClass);

        $io->section(sprintf('Entity: %s', $entityClass));

        $rows = [];
        foreach ($metadata->fieldMappings as $field => $mapping) {
            $rows[] = [
                $field,
                $mapping['type'] ?? 'N/A',
            ];
        }

        $io->table(['Field', 'Type'], $rows);
    }
}

Example outputs

• List all :
  
• Describe one :
  
• Entity does not exist error :
  

I would love people's thoughts and suggestions on this idea.

[greg0ire]

Hi and thanks for the detailed RFC!

From what I understand, the part that would be the most useful for you in your use case would be the "Describe one" part, and comes from the lack of auto-complete when using query builder with a string that looks like ->select('a.<cursor here>')

It would be interesting to know why orm:mapping:describe was never shipped with the bundle. Do you think its output could be simplified depending on the current verbosity, so that when -vvv is specified, the current output is shown, and when -v is specified, it looks like the output of your command? I think it would be less confusing for people if there was just one command for describing a mapping instead of 2.

I think both orm:mapping:describe and your command would be easier to use if https://symfony.com/blog/new-in-symfony-5-4-console-autocompletion was leveraged to provide autocomplete for entity names.

[stof]

@greg0ire not shipping mapping:describe in the bundle is probably just a mistake. This command was added later than the others (in doctrine/orm#1165). I think the need for a follow-up PR in the bundle was forgotten.

Having a debug command that shows only the type of fields without other mapping information would be quite inconsistent with what the various debug:* commands of Symfony look like. My vote would be to register only the mapping:describe command of the ORM (and maybe improving a bit its output to make it easier to read)

I think both orm:mapping:describe and your command would be easier to use if https://symfony.com/blog/new-in-symfony-5-4-console-autocompletion was leveraged to provide autocomplete for entity names.

Implementing completion support in the mapping:describe command looks like a good idea of contribution for the ORM.

[loic425]

I agree with @greg0ire, we could use verbosity to bring more details instead of that huge details that are hard to read.
And yes, having only one Debug command is important.
We discussed about this need yesterday with @stlgaits and feel that the existing one (found after) was too much verbose in our use case. That's why she decided to open that RFC.

[greg0ire]

OK so we can already work on 2 items:

1. improving orm:mapping:describe
2. once it's stable registering it in the bundle

Having a debug command that shows only the type of fields without other mapping information would be quite inconsistent with what the various debug:* commands of Symfony look like

Does that mean that orm:mapping:describe should not be changed to fit the output proposed by @stlgaits , or do you also mean that no command contributed to this bundle should ever have such an output?

[stof]

@greg0ire have a debug command that shows only the list of fields with their type without any other mapping information looks like a very narrow use case (which would not be a fit for a debug:* command btw, as commands with that name in Symfony are exposing as much debugging info as possible about the scope they are about).
I think mapping:describe should be improved. Having a single table as output mixing info about the entity-level config and the list of fields was probably not a good idea. We should have a separate section in the output handling the list of fields, to make it more readable, thanks to structuring the output (and maybe this will be enough for @stlgaits then).

Btw, I would not add a command that has those "describe all" and "describe one" behaviors mixed. We already have mapping:info for the list of entities (and the use case of @stlgaits does not involve it anyway, but justifies only the "describe one" behavior).

[stof]

Btw, the fact that orm:mapping:describe writes this description to STDERR is weird to me. the mapping description is the main output of the command.

[greg0ire]

Ah yes, the stderr thing was me going overboard with doctrine/orm#10162, I will partially revert it.

We should have a separate section in the output handling the list of fields, to make it more readable, thanks to structuring the output (and maybe this will be enough for @stlgaits then).

How about we introduce a --format=json option? That way, @stlgaits could pipe the output into jq and write a jq filter that only retains the parts that she's interested in.

[stof]

supporting a json format in mapping:describe also makes sense.

[greg0ire]

Great. Then we have an acceptable solution. @stlgaits if you're OK with this plan, next steps for you could be to:

1. Take an example output of orm:mapping:describe, and specify what the json equivalent of that should look like.
2. Check that with an example json document corresponding to the output, you can easily produce something useful to your use case with e.g. jq

If that works, then you can work on any of those items, ranked by order of usefulness to your use case:

• contribute support for a json format
• contribute the registration of the command in the bundle (Register doctrine:mapping:describe command #1892)
• contribute support for auto-completion (Add console completion for entityName param of orm:mapping:describe c… orm#12037)

[stlgaits]

Awesome, thank you so much for the detailed feedback, very much appreciated ! I will give it a go to see how far I can contribute, I'm pretty busy in the next few weeks but I'll keep you posted if I get something done.