Do not use nowdocs by default or provide an option to opt-out

[theofidry]

Feature Request

Q	A
New Feature	no
RFC	no
BC Break	no
Version	3.9.0+

Summary

With #1473 the result if a regular diff (bin/console doctrine:migration:diff) is now:

<?php

declare(strict_types=1);

namespace DoctrineMigrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

/**
 * Auto-generated Migration: Please modify to your needs!
 */
final class Version20250530065231 extends AbstractMigration
{
    public function getDescription(): string
    {
        return '';
    }

    public function up(Schema $schema): void
    {
        // this up() migration is auto-generated, please modify it to your needs
        $this->addSql(<<<'SQL'
            ALTER TABLE platform ADD test_number INT NOT NULL
        SQL);
    }

    public function down(Schema $schema): void
    {
        // this down() migration is auto-generated, please modify it to your needs
        $this->addSql(<<<'SQL'
            ALTER TABLE platform DROP test_number
        SQL);
    }
}

There is a --formatted that, AFAIU, was providing this functionality. So now effectively what we have is:

• an option that is not deprecated but provide no value
• the default behaviour that changed to the formatted behaviour
• no way to opt out of it

Solution

I don't know if reverting it is desired and personally I understand the appeal of promoting type-checkable* statements as the default. Personally I find it's a bit too much especially for simple statements, if statements were grouped I think it would make it more readable, but that cannot be done with prepared statements.

However I think it's important to have a way to opt-out to this. Maybe via a new option and a corresponding config setting in the bundle.

*: Referring to the fact that adding 'SQL' tags to the nowdocs the IDE can pick it up and syntax check/highlight it and even match against the DB schema.

[theofidry]

/cc @vinise

[theofidry]

Ah #1504 was already created for this

[florentdestremau]

wouldn't it be easier to have a setting in the configuration file, rather than think about it on commands?

[theofidry]

I think it would be great to have it in the config file, but I'd argue that having it as an option is a must have too.

[vinise]

@florentdestremau @theofidry totally agree with you
I'm going to add these options to the configuration as well.
I might also make a new feature --one-block to join all queries in a single sql nowdoc (with corresponding option in config file).

$this->addSql('
  CREATE TABLE "user" (
    id SERIAL PRIMARY KEY,
    firstname VARCHAR(100) NOT NULL,
    lastname VARCHAR(100) NOT NULL
  );
  ALTER TABLE platform ADD test_number INT NOT NULL;
  ALTER TABLE registration ADD test_number INT NOT NULL;
');

[florentdestremau]

If all the queries are joined in a single statement the heredoc syntax would make much more sense to be the default, yes !

[florentdestremau]

ultimately this should be a project-specific configuration, when I run make:migration I don't think I should have to think about it

[theofidry]

For the one block you need to mind the fact that if you have multiple prepare statements it won't work

[vinise]

For the one block you need to mind the fact that if you have multiple prepare statements it won't work

@theofidry diff command is not responsible for that. Like always, it is up to the user to modify it.
Having all options in the configuration files and being able to override them if needed via cli seems to cover any cases.