[DOCUMENTATION] Explain how to inject or custom MigrationFinder through DI or Factory

[shakaran]

I full read the old issue #127

Where the author only have the way to custom the file names for finder like:

Prod
| - Version001InitialSchema
| - Version002FirstNewFeature
Version001InitialSchemaDev
VersionFeatureInDev

As doc specifies for Version number
https://www.doctrine-project.org/projects/doctrine-migrations/en/4.0/reference/version-numbers.html#version-numbers it follows the patttern or convention with "Version" in the name, as we can see also in code of generator right here (which is not customizable)
https://github.com/doctrine/migrations/blob/3.9.x/src/Generator/ClassNameGenerator.php#L16

And all that files are later "found" throught the finder which is not customizable:
https://github.com/doctrine/migrations/blob/3.9.x/src/Finder/GlobFinder.php#L22

The resolution or close of that issue #278 via @goetas in commit doctrine/migrations@1dab078#diff-a6ea6f812989661f14fb8ebabe503958f932fe9f75ba3c3852d779d1810f36bd suggest that it could be used or implemented via Dependency Injection (DI) or via factory, but it not documented or a clear example of how to it.

I have something similar in a project with:

VersionM0001_CreatePolicyTables_20250606183915.php
VersionM0002_CreateSupplementTables_20250607161000.php
VersionM0003_InsertSupplementDefaultData_20250607161800.php
VersionM0004_CreateCommissionTables_20250607162000.php
VersionM0005_InsertCommissionCategoryDefaultData_20250607162100.php
VersionM0006_AddActiveColumnToCommissionCategory_20250610120316.php
VersionM0007_CreateReceiptPolicyTypeTables_20250607205815.php
VersionM0008_CreateCommissionPerPolicyTable_20250610150420.php
VersionM0009_InsertPolicytTypeDefaultData_20250612013600.php

That is, I am forced to use the "Version" in the filename, but I would like to read and follow only the pattern M[0-9]{4}_*.php for the finder (that is, no "Version" in the name, also improve the generator following this pattern)

For example:

<?php

declare(strict_types=1);

 namespace App\Migrations;

 use Doctrine\Migrations\Finder\Finder;
 use function glob;
 use function rtrim;

 class CustomMigrationFinder extends Finder
 {
	 public function findMigrations(string $directory, string|null $namespace = null): array
	 {
		 $dir = $this->getRealPath($directory);

		 $files = glob(rtrim($dir, '/') . '/M[0-9]{4}_*.php');
		 if ($files === false) {
			 $files = [];
		 }

		 return $this->loadMigrations($files, $namespace);
	 }
 }

# config/pacakages/doctrine_migrations.yaml
doctrine_migrations:
  migrations_paths:
    'DoctrineMigrations': '%kernel.project_dir%/migrations'
  services:
    # Method 1) this could be used via Service?
    'Doctrine\Migrations\Finder\MigrationFinder': '@App\Finder\CustomMigrationFinder'
  factories:
    # Method 2) this could be used via factory?
    Doctrine\Migrations\Finder\MigrationFinder: ['@App\Finder\CustomMigrationFinder']

  # Method 3) Implement this new config option "custom_finder" to use a custom migration finder
  custom_finder:
    class: App\Finder\CustomMigrationFinder

  enable_profiler: false
  storage:
    table_storage:
      table_name: doctrine_migration_versions 
      version_column_name: 'version'
      version_column_length: 192
      executed_at_column_name: 'executed_at'

Using symfony in yaml file, I would like to custom via a service or factory or even custon config "migration_finder"

Maybe is need to implement a setMigrationFinder() method in configuration for doctrine migrations which seems not documented at
https://www.doctrine-project.org/projects/doctrine-migrations/en/4.0/reference/custom-configuration.html#custom-configuration

And for example the custom_finder or custom_generator option, could be implemented as option configuration here