[DoctrineBundle] Improvements for building entities and getting started

Author: jwage

src/Symfony/Framework/DoctrineBundle/Command/BuildDoctrineCommand.php

@@ -55,6 +55,27 @@ protected function configure()
       ->addOption('and-append', null, InputOption::PARAMETER_OPTIONAL | InputOption::PARAMETER_IS_ARRAY, 'Load data fixtures and append to existing data')
       ->addOption('and-update-schema', null, null, 'Update schema after rebuilding all classes')
       ->addOption('connection', null, null, 'The connection to use.')
+      ->setHelp('
+The <info>doctrine:build</info> task builds your Doctrine development environment.
+
+  <info>php console doctrine:build --all</info>
+
+The above command will re-build your entities and re-create your database schema.
+
+If you wanted to only update your schema instead of re-creating it you can run
+the following:
+
+  <info>php console doctrine:build --entities --and-update-schema</info>
+
+Now your entities are re-built and your database schema is up to date!
+
+You can also use the <info>--and-load</info> and <info>--and-append</info> to
+load data fixtures after running another build option.
+
+  <info>php console doctrine:build --all --and-load</info>
+
+The above will re-build everything and load all bundle data fixtures.
+')
     ;
   }
 

src/Symfony/Framework/DoctrineBundle/Command/BuildEntitiesDoctrineCommand.php

@@ -56,10 +56,12 @@ protected function execute(InputInterface $input, OutputInterface $output)
 
       if (isset($bundleDirs[$namespace]))
       {
-        if (is_dir($dir = $bundleDirs[$namespace].'/'.$class.'/Entities'))
+        if (is_dir($dir = $bundleDirs[$namespace].'/'.$class.'/Resources/config/doctrine/metadata'))
         {
           $this->convertMapping($dir, $bundleDirs[$namespace].'/..');
-        } else if (is_dir($dir = $bundleDirs[$namespace].'/'.$class.'/Resources/config/doctrine/metadata')) {
+        }
+        else if (is_dir($dir = $bundleDirs[$namespace].'/'.$class.'/Entities'))
+        {
           $this->convertMapping($dir, $bundleDirs[$namespace].'/..');
         }
       }

src/Symfony/Framework/DoctrineBundle/Command/InitEntityDoctrineCommand.php

@@ -0,0 +1,116 @@
+<?php
+
+namespace Symfony\Framework\DoctrineBundle\Command;
+
+use Symfony\Components\Console\Input\InputArgument;
+use Symfony\Components\Console\Input\InputOption;
+use Symfony\Components\Console\Input\InputInterface;
+use Symfony\Components\Console\Output\OutputInterface;
+use Symfony\Components\Console\Output\Output;
+use Symfony\Framework\WebBundle\Util\Filesystem;
+use Doctrine\Common\Cli\Configuration;
+use Doctrine\Common\Cli\CliController as DoctrineCliController;
+
+/*
+ * This file is part of the symfony framework.
+ *
+ * (c) Fabien Potencier <fabien.potencier@symfony-project.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+/**
+ * Initialize a new Doctrine entity inside a bundle.
+ *
+ * @package    symfony
+ * @subpackage console
+ * @author     Fabien Potencier <fabien.potencier@symfony-project.com>
+ * @author     Jonathan H. Wage <jonwage@gmail.com>
+ */
+class InitEntityDoctrineCommand extends DoctrineCommand
+{
+  /**
+   * @see Command
+   */
+  protected function configure()
+  {
+    $this
+      ->setName('doctrine:init-entity')
+      ->setDescription('Initialize a new Doctrine entity inside a bundle.')
+      ->addOption('bundle', null, InputOption::PARAMETER_REQUIRED, 'The bundle to initialize the entity in.')
+      ->addOption('entity', null, InputOption::PARAMETER_REQUIRED, 'The entity class to initialize.')
+      ->setHelp('
+The <info>doctrine:init-entity</info> task initializes a new Doctrine entity inside a bundle:
+
+    <comment>php console doctrine:init-entity --bundle="Bundle\MyCustomBundle" --entity="User\Group"</comment>
+
+The above would initialize a new entity in the following entity namespace <info>Bundle\MyCustomBundle\Entities\User\Group</info>.
+
+You can now build your entities and update your database schema:
+
+    <comment>php console doctrine:build --entities --and-update-schema</comment>
+
+Now you have a new entity and your database has been updated.
+      ')
+    ;
+  }
+
+  /**
+   * @see Command
+   */
+  protected function execute(InputInterface $input, OutputInterface $output)
+  {
+    if (!preg_match('/Bundle$/', $bundle = $input->getOption('bundle')))
+    {
+      throw new \InvalidArgumentException('The bundle name must end with Bundle. Example: "Bundle\MySampleBundle".');
+    }
+
+    $dirs = $this->container->getKernelService()->getBundleDirs();
+
+    $tmp = str_replace('\\', '/', $bundle);
+    $namespace = str_replace('/', '\\', dirname($tmp));
+    $bundle = basename($tmp);
+
+    if (!isset($dirs[$namespace]))
+    {
+      throw new \InvalidArgumentException(sprintf('Unable to initialize the bundle entity (%s not defined).', $namespace));
+    }
+
+    $entity = $input->getOption('entity');
+    $entityNamespace = $namespace.'\\'.$bundle.'\\Entities';
+    $fullEntityClassName = $entityNamespace.'\\'.$entity;
+    $tmp = str_replace('\\', '/', $fullEntityClassName);
+    $tmp = str_replace('/', '\\', dirname($tmp));
+    $className = basename($tmp);
+
+    $extends = null;
+    $path = $dirs[$namespace].'/'.$bundle.'/Resources/config/doctrine/metadata/'.str_replace('\\', '.', $fullEntityClassName).'.dcm.xml';
+
+    $xml = sprintf('<?xml version="1.0" encoding="UTF-8"?>
+
+<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://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+
+    <entity name="%s" table="%s">
+        <id name="id" type="integer" column="id">
+            <generator strategy="AUTO"/>
+        </id>
+    </entity>
+
+</doctrine-mapping>',
+    $fullEntityClassName,
+    str_replace('\\', '_', strtolower($entity))
+  );
+
+    if (!is_dir($dir = dirname($path)))
+    {
+      mkdir($dir, 0777, true);
+    }
+
+    file_put_contents($path, $xml);
+    $this->runCommand('doctrine:build-entities');
+  }
+}

src/Symfony/Framework/DoctrineBundle/README

@@ -59,7 +59,6 @@ If you want to enable the Doctrine 2 ORM you can do so with the following:
 
     doctrine.orm:
       default_entity_manager:   default
-      metadata_driver:          xml           # xml, yml, annotation
       cache_driver:             apc           # array, apc, memcache, xcache
       entity_managers:
         default:
@@ -157,6 +156,8 @@ file named **Entry.php** with some code like the following:
 The Doctrine 2 CLI is integrated with the Symfony 2 CLI so we have all the common
 commands we need to make working with Doctrine 2 just as easy and fast as before!
 
+### Listing Available Doctrine Commands
+
     $ php console list doctrine
 
     Available commands for the "doctrine" namespace:
@@ -167,12 +168,45 @@ commands we need to make working with Doctrine 2 just as easy and fast as before
       :database-tool               Create and drop the configured databases.
       :ensure-production-settings  Verify that Doctrine is properly configured for a production environment.
       :generate-proxies            Generates proxy classes for entity classes.
+      :import-mapping              Import the initial mapping information for entities from an existing database.
+      :init-entity                 Initialize a new Doctrine entity inside a bundle.
       :load-data-fixtures          Load data fixtures to your database.
       :run-dql                     Executes arbitrary DQL directly from the command line.
       :run-sql                     Executes arbitrary SQL from a file or directly from the command line.
       :schema-tool                 Processes the schema and either apply it directly on EntityManager or generate the SQL output.
       :version                     Displays the current installed Doctrine version.
 
+### Schema Tool
+
+The schema tool in Doctrine 2 allows you to easily drop and your create your 
+database schemas for your mapping information.
+
+You can easily create your initial schema from mapping information:
+
+    php console doctrine:schema-tool --create
+
+Or if you want to then drop your schema you can do:
+
+    php console doctrine:schema-tool --drop
+
+If you want to re-create it (drop and create) you can use:
+
+    php console doctrine:schema-tool --re-create
+
+Now the scenario arrises where you want to change your mapping information and
+update your database without blowing away everything and losing your existing data.
+You can do the following for that:
+
+    php console doctrine:schema-tool --update
+
+> **TIP**
+> The above will not drop anything from your database schema. To drop the remaining
+> things from your schema you need to use the **--complete-update** option.
+>
+>     php console doctrine:schema-tool --complete-update
+
+### Doctrine Build Command
+
 The development workflow is very similar to how it is in Symfony 1.4. You can modify 
 your mapping information and use **doctrine:build --all** to re-build your 
 environment:
@@ -187,6 +221,11 @@ schema:
 Now any changes you made in your mapping information will be reflected in the 
 according databases! Here are all the available options for the **build** task:
 
+> **NOTE**
+> Not the key difference here is that you can modify your schema during development
+> and just update your database schema without having to blow everything away and 
+> re-build it all.
+
     $ php console help doctrine:build
     Usage:
      Symfony doctrine:build [--all] [--all-classes] [--entities] [--db] [--and-load[="..."]] [--and-append[="..."]] [--and-update-schema] [--dump-sql] [--connection]
@@ -198,4 +237,20 @@ according databases! Here are all the available options for the **build** task:
      --and-load Load data fixtures (multiple values allowed)
      --and-append Load data fixtures and append to existing data (multiple values allowed)
      --and-update-schema Update schema after rebuilding all classes
-     --connection The connection to use.
+     --connection The connection to use.
+
+### Doctrine Init Entity Command
+
+You can easily initialize a new Doctrine entity for a bundle by using the 
+**doctrine:init-bundle** command:
+
+    $ php console doctrine:init-entity --bundle="Bundle\MySampleBundle" --entity="User\Group"
+
+Now if you have a look inside the bundle you will see that you have a **Group** class
+located here **Bundle/MySampleBundle/Entities/User/Group.php**.
+
+Now you can customize the mapping information for the entity by editing the metadata
+information inside **Bundle/MySampleBundle/Resources/config/doctrine/metadata** and
+just update your database schema:
+
+    $ php console doctrine:schema-tool --update