Version Numbers
===============

When :doc:`Generating Migrations <generating_migrations>` the newly created
classes are generated with the name ``Version{date}`` with ``{date}`` having a
``YmdHis`` `format <http://php.net/manual/en/function.date.php>`_. This format
is important as it allows the migrations to be correctly ordered.

Starting with version 1.5 when loading migration classes, Doctrine Migrations
does a ``sort($versions, SORT_STRING)`` on version numbers. This can cause
problems with custom version numbers:

.. code-block:: php

    <?php
    $versions = [
        'Version1',
        'Version2',
        // ...
        'Version10',
    ];
    sort($versions, SORT_STRING);

    var_dump($versions);
    /*
    array(3) {
      [0] =>
      string(8) "Version1"
      [1] =>
      string(9) "Version10"
      [2] =>
      string(8) "Version2"
    }
    */

The custom version numbers above end up out of order which may cause damage
to a database.

It's **strongly recommended** that the ``Version{date}`` migration class name
format is kept to and that the various :doc:`tools for generating migrations <generating_migrations>`
be used.

Should some custom migration numbers be necessary, keeping the version number
the same length as the date format (14 total characters) and padding it to the
left with zeros should work.

.. code-block:: php

    <?php

    $versions = [
        'Version00000000000001',
        'Version00000000000002',
        // ...
        'Version00000000000010',
        'Version20180107070000', // generated version
    ];
    sort($versions, SORT_STRING);

    var_dump($versions);
    /*
    array(4) {
      [0] =>
      string(21) "Version00000000000001"
      [1] =>
      string(21) "Version00000000000002"
      [2] =>
      string(21) "Version00000000000010"
      [3] =>
      string(21) "Version20180107070000"
    }
    */

Please note that migrating to this new, zero-padded format may require
:ref:`manual version table intervention <managing-versions-table>` if the
versions have previously been applied.
