--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/vendor/bundles/Symfony/Bundle/DoctrineMigrationsBundle/Resources/doc/index.rst Fri Nov 25 18:55:43 2011 +0100
@@ -0,0 +1,286 @@
+DoctrineMigrationsBundle
+========================
+
+The database migrations feature is an extension of the database abstraction
+layer and offers you the ability to programmatically deploy new versions of
+your database schema in a safe, easy and standardized way.
+
+.. tip::
+
+ You can read more about the Doctrine Database Migrations on the project's
+ `documentation`_.
+
+Installation
+------------
+
+Doctrine migrations for Symfony are maintained in the `DoctrineMigrationsBundle`_.
+Make sure you have both the ``doctrine-migrations`` and ``DoctrineMigrationsBundle``
+libraries configured in your project. Follow these steps to install the
+libraries in the Symfony Standard distribution.
+
+Add the following to ``deps``. This will register the Migrations Bundle
+and the doctrine-migrations library as dependencies in your application:
+
+.. code-block:: text
+
+ [doctrine-migrations]
+ git=http://github.com/doctrine/migrations.git
+
+ [DoctrineMigrationsBundle]
+ git=http://github.com/symfony/DoctrineMigrationsBundle.git
+ target=/bundles/Symfony/Bundle/DoctrineMigrationsBundle
+
+Update the vendor libraries:
+
+.. code-block:: bash
+
+ $ php bin/vendors install
+
+Next, ensure the new ``Doctrine\DBAL\Migrations`` namespace will be autoloaded
+via ``autoload.php``. The new ``Migrations`` namespace *must* be placed above
+the ``Doctrine\\DBAL`` entry so that the autoloader looks inside the migrations
+directory for those classes:
+
+.. code-block:: php
+
+ // app/autoload.php
+ $loader->registerNamespaces(array(
+ //...
+ 'Doctrine\\DBAL\\Migrations' => __DIR__.'/../vendor/doctrine-migrations/lib',
+ 'Doctrine\\DBAL' => __DIR__.'/../vendor/doctrine-dbal/lib',
+ ));
+
+Finally, be sure to enable the bundle in ``AppKernel.php`` by including the
+following:
+
+.. code-block:: php
+
+ // app/AppKernel.php
+ public function registerBundles()
+ {
+ $bundles = array(
+ //...
+ new Symfony\Bundle\DoctrineMigrationsBundle\DoctrineMigrationsBundle(),
+ );
+ }
+
+Usage
+-----
+
+All of the migrations functionality is contained in a few console commands:
+
+.. code-block:: bash
+
+ doctrine:migrations
+ :diff Generate a migration by comparing your current database to your mapping information.
+ :execute Execute a single migration version up or down manually.
+ :generate Generate a blank migration class.
+ :migrate Execute a migration to a specified version or the latest available version.
+ :status View the status of a set of migrations.
+ :version Manually add and delete migration versions from the version table.
+
+Start by getting the status of migrations in your application by running
+the ``status`` command:
+
+.. code-block:: bash
+
+ php app/console doctrine:migrations:status
+
+ == Configuration
+
+ >> Name: Application Migrations
+ >> Configuration Source: manually configured
+ >> Version Table Name: migration_versions
+ >> Migrations Namespace: Application\Migrations
+ >> Migrations Directory: /path/to/project/app/DoctrineMigrations
+ >> Current Version: 0
+ >> Latest Version: 0
+ >> Executed Migrations: 0
+ >> Available Migrations: 0
+ >> New Migrations: 0
+
+Now, you can start working with migrations by generating a new blank migration
+class. Later, you'll learn how Doctrine can generate migrations automatically
+for you.
+
+.. code-block:: bash
+
+ php app/console doctrine:migrations:generate
+ Generated new migration class to "/path/to/project/app/DoctrineMigrations/Version20100621140655.php"
+
+Have a look at the newly generated migration class and you will see something
+like the following::
+
+ namespace Application\Migrations;
+
+ use Doctrine\DBAL\Migrations\AbstractMigration,
+ Doctrine\DBAL\Schema\Schema;
+
+ class Version20100621140655 extends AbstractMigration
+ {
+ public function up(Schema $schema)
+ {
+
+ }
+
+ public function down(Schema $schema)
+ {
+
+ }
+ }
+
+If you run the ``status`` command it will now show that you have one new
+migration to execute:
+
+.. code-block:: bash
+
+ php app/console doctrine:migrations:status
+
+ == Configuration
+
+ >> Name: Application Migrations
+ >> Configuration Source: manually configured
+ >> Version Table Name: migration_versions
+ >> Migrations Namespace: Application\Migrations
+ >> Migrations Directory: /path/to/project/app/DoctrineMigrations
+ >> Current Version: 0
+ >> Latest Version: 2010-06-21 14:06:55 (20100621140655)
+ >> Executed Migrations: 0
+ >> Available Migrations: 1
+ >> New Migrations: 1
+
+ == Migration Versions
+
+ >> 2010-06-21 14:06:55 (20100621140655) not migrated
+
+Now you can add some migration code to the ``up()`` and ``down()`` methods and
+finally migrate when you're ready:
+
+.. code-block:: bash
+
+ php app/console doctrine:migrations:migrate
+
+For more information on how to write the migrations themselves (i.e. how to
+fill in the ``up()`` and ``down()`` methods), see the official Doctrine Migrations
+`documentation`_.
+
+Running Migrations during Deployment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Of course, the end goal of writing migrations is to be able to use them to
+reliably update your database structure when you deploy your application.
+By running the migrations locally (or on a beta server), you can ensure that
+the migrations work as you expect.
+
+When you do finally deploy your application, you just need to remember to run
+the ``doctrine:migrations:migrate`` command. Internally, Doctrine creates
+a ``migration_versions`` table inside your database and tracks which migrations
+have been executed there. So, no matter how many migrations you've created
+and executed locally, when you run the command during deployment, Doctrine
+will know exactly which migrations it hasn't run yet by looking at the ``migration_versions``
+table of your production database. Regardless of what server you're on, you
+can always safely run this command to execute only the migrations that haven't
+been run yet on *that* particular database.
+
+Generating Migrations Automatically
+-----------------------------------
+
+In reality, you should rarely need to write migrations manually, as the migrations
+library can generate migration classes automatically by comparing your Doctrine
+mapping information (i.e. what your database *should* look like) with your
+actual current database structure.
+
+For example, suppose you create a new ``User`` entity and add mapping information
+for Doctrine's ORM:
+
+.. configuration-block::
+
+ .. code-block:: php-annotations
+
+ // src/Acme/HelloBundle/Entity/User.php
+ namespace Acme\HelloBundle\Entity;
+
+ use Doctrine\ORM\Mapping as ORM;
+
+ /**
+ * @ORM\Entity
+ * @ORM\Table(name="hello_user")
+ */
+ class User
+ {
+ /**
+ * @ORM\Id
+ * @ORM\Column(type="integer")
+ * @ORM\GeneratedValue(strategy="AUTO")
+ */
+ protected $id;
+
+ /**
+ * @ORM\Column(type="string", length="255")
+ */
+ protected $name;
+ }
+
+ .. code-block:: yaml
+
+ # src/Acme/HelloBundle/Resources/config/doctrine/User.orm.yml
+ Acme\HelloBundle\Entity\User:
+ type: entity
+ table: hello_user
+ id:
+ id:
+ type: integer
+ generator:
+ strategy: AUTO
+ fields:
+ name:
+ type: string
+ length: 255
+
+ .. code-block:: xml
+
+ <!-- src/Acme/HelloBundle/Resources/config/doctrine/User.orm.xml -->
+ <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+ http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+
+ <entity name="Acme\HelloBundle\Entity\User" table="hello_user">
+ <id name="id" type="integer" column="id">
+ <generator strategy="AUTO"/>
+ </id>
+ <field name="name" column="name" type="string" length="255" />
+ </entity>
+
+ </doctrine-mapping>
+
+With this information, Doctrine is now ready to help you persist your new
+``User`` object to and from the ``hello_user`` table. Of course, this table
+doesn't exist yet! Generate a new migration for this table automatically by
+running the following command:
+
+.. code-block:: bash
+
+ php app/console doctrine:migrations:diff
+
+You should see a message that a new migration class was generated based on
+the schema differences. If you open this file, you'll find that it has the
+SQL code needed to create the ``hello_user`` table. Next, run the migration
+to add the table to your database:
+
+.. code-block:: bash
+
+ php app/console doctrine:migrations:migrate
+
+The moral of the story is this: after each change you make to your Doctrine
+mapping information, run the ``doctrine:migrations:diff`` command to automatically
+generate your migration classes.
+
+If you do this from the very beginning of your project (i.e. so that even
+the first tables were loaded via a migration class), you'll always be able
+to create a fresh database and run your migrations in order to get your database
+schema fully up to date. In fact, this is an easy and dependable workflow
+for your project.
+
+.. _documentation: http://www.doctrine-project.org/projects/migrations/2.0/docs/reference/introduction/en
+.. _DoctrineMigrationsBundle: https://github.com/symfony/DoctrineMigrationsBundle