数据库和Doctrine

注解

Defining the configuration via parameters.yml is just a convention. The parameters defined in that file are referenced by the main configuration file when setting up Doctrine:

By separating the database information into a separate file, you can easily keep different versions of the file on each server. You can also easily store database configuration (or any sensitive information) outside of your project, like inside your Apache configuration, for example. For more information, see 如何将Service Container的参数暴露到外部.

Setting up the Database to be UTF8

One mistake even seasoned developers make when starting a Symfony project is forgetting to set up default charset and collation on their database, ending up with latin type collations, which are default for most databases. They might even remember to do it the very first time, but forget that it’s all gone after running a relatively common command during development:

$ php app/console doctrine:database:drop --force
$ php app/console doctrine:database:create

There’s no way to configure these defaults inside Doctrine, as it tries to be as agnostic as possible in terms of environment configuration. One way to solve this problem is to configure server-level defaults.

Setting UTF8 defaults for MySQL is as simple as adding a few lines to your configuration file (typically my.cnf):

[mysqld]
collation-server = utf8_general_ci
character-set-server = utf8

注解

If you want to use SQLite as your database, you need to set the path where your database file should be stored:

小技巧

Once you learn the concepts behind Doctrine, you can have Doctrine create simple entity classes for you. This will ask you interactive questions to help you build any entity:

$ php app/console doctrine:generate:entity

• Annotations

  // src/AppBundle/Entity/Product.php
  namespace AppBundleEntity;
  
  use DoctrineORMMapping as ORM;
  
  /**
   * @ORMEntity
   * @ORMTable(name="product")
   */
  class Product
  {
      /**
       * @ORMColumn(type="integer")
       * @ORMId
       * @ORMGeneratedValue(strategy="AUTO")
       */
      protected $id;
  
      /**
       * @ORMColumn(type="string", length=100)
       */
      protected $name;
  
      /**
       * @ORMColumn(type="decimal", scale=2)
       */
      protected $price;
  
      /**
       * @ORMColumn(type="text")
       */
      protected $description;
  }
  

• YAML

  # src/AppBundle/Resources/config/doctrine/Product.orm.yml
  AppBundleEntityProduct:
      type: entity
      table: product
      id:
          id:
              type: integer
              generator: { strategy: AUTO }
      fields:
          name:
              type: string
              length: 100
          price:
              type: decimal
              scale: 2
          description:
              type: text
  

• XML

  <!-- src/AppBundle/Resources/config/doctrine/Product.orm.xml -->
  <?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://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
  
      <entity name="AppBundleEntityProduct" table="product">
          <id name="id" type="integer">
              <generator strategy="AUTO" />
          </id>
          <field name="name" type="string" length="100" />
          <field name="price" type="decimal" scale="2" />
          <field name="description" type="text" />
      </entity>
  </doctrine-mapping>
  

注解

A bundle can accept only one metadata definition format. For example, it’s not possible to mix YAML metadata definitions with annotated PHP entity class definitions.

小技巧

The table name is optional and if omitted, will be determined automatically based on the name of the entity class.

参见

You can also check out Doctrine’s Basic Mapping Documentation for all details about mapping information. If you use annotations, you’ll need to prepend all annotations with ORM (e.g. ORMColumn(...)), which is not shown in Doctrine’s documentation. You’ll also need to include the use DoctrineORMMapping as ORM; statement, which imports the ORM annotations prefix.

警告

Be careful that your class name and properties aren’t mapped to a protected SQL keyword (such as group or user). For example, if your entity class name is Group, then, by default, your table name will be group, which will cause an SQL error in some engines. See Doctrine’s Reserved SQL keywords documentation on how to properly escape these names. Alternatively, if you’re free to choose your database schema, simply map to a different table name or column name. See Doctrine’s Persistent classes and Property Mapping documentation.

注解

When using another library or program (e.g. Doxygen) that uses annotations, you should place the @IgnoreAnnotation annotation on the class to indicate which annotations Symfony should ignore.

For example, to prevent the @fn annotation from throwing an exception, add the following:

/**
 * @IgnoreAnnotation("fn")
 */
class Product
// ...

警告

Keep in mind that Doctrine’s entity generator produces simple getters/setters. You should check generated entities and adjust getter/setter logic to your own needs.

More about doctrine:generate:entities

With the doctrine:generate:entities command you can:

• 生成Getters和Setters;

• generate repository classes configured with the @ORMEntity(repositoryClass="...") annotation;
• generate the appropriate constructor for 1:n and n:m relations.

The doctrine:generate:entities command saves a backup of the original Product.php named Product.php~. In some cases, the presence of this file can cause a “Cannot redeclare class” error. It can be safely removed. You can also use the --no-backup option to prevent generating these backup files.

Note that you don’t need to use this command. Doctrine doesn’t rely on code generation. Like with normal PHP classes, you just need to make sure that your protected/private properties have getter and setter methods. Since this is a common thing to do when using Doctrine, this command was created.

注解

Doctrine doesn’t care whether your properties are protected or private, or whether you have a getter or setter function for a property. The getters and setters are generated here only because you’ll need them to interact with your PHP object.

小技巧

Actually, this command is incredibly powerful. It compares what your database should look like (based on the mapping information of your entities) with how it actually looks, and generates the SQL statements needed to update the database to where it should be. In other words, if you add a new property with mapping metadata to Product and run this task again, it will generate the “alter table” statement needed to add that new column to the existing product table.

An even better way to take advantage of this functionality is via migrations, which allow you to generate these SQL statements and store them in migration classes that can be run systematically on your production server in order to track and migrate your database schema safely and reliably.

注解

If you’re following along with this example, you’ll need to create a route that points to this action to see it work.

小技巧

This article shows working with Doctrine from within a controller by using the getDoctrine() method of the controller. This method is a shortcut to get the doctrine service. You can work with Doctrine anywhere else by injecting that service in the service. See 服务容器（Service Container） for more on creating your own services.

注解

In fact, since Doctrine is aware of all your managed entities, when you call the flush() method, it calculates an overall changeset and executes the queries in the correct order. It utilizes cached prepared statement to slightly improve the performance. For example, if you persist a total of 100 Product objects and then subsequently call flush(), Doctrine will execute 100 INSERT queries using a single prepared statement object.

小技巧

Doctrine provides a library that allows you to programmatically load testing data into your project (i.e. “fixture data”). For information, see the “DoctrineFixturesBundle” documentation.

小技巧

You can achieve the equivalent of this without writing any code by using the @ParamConverter shortcut. See the FrameworkExtraBundle documentation for more details.

注解

The AppBundle:Product string is a shortcut you can use anywhere in Doctrine instead of the full class name of the entity (i.e. AppBundleEntityProduct). As long as your entity lives under the Entity namespace of your bundle, this will work.

注解

Of course, you can also issue complex queries, which you’ll learn more about in the 查找对象 section.

小技巧

When you render any page, you can see how many queries were made in the bottom right corner of the web debug toolbar.

If you click the icon, the profiler will open, showing you the exact queries that were made.

The icon will turn yellow if there were more than 50 queries on the page. This could indicate that something is not correct.

$repository->find($id);

$repository->findOneByName('Foo');

小技巧

Take note of the setParameter() method. When working with Doctrine, it’s always a good idea to set any external values as “placeholders” (:price in the example above) as it prevents SQL injection attacks.

• Annotations

  // src/AppBundle/Entity/Product.php
  namespace AppBundleEntity;
  
  use DoctrineORMMapping as ORM;
  
  /**
   * @ORMEntity(repositoryClass="AppBundleEntityProductRepository")
   */
  class Product
  {
      //...
  }
  

• YAML

  # src/AppBundle/Resources/config/doctrine/Product.orm.yml
  AppBundleEntityProduct:
      type: entity
      repositoryClass: AppBundleEntityProductRepository
      # ...
  

• XML

  <!-- src/AppBundle/Resources/config/doctrine/Product.orm.xml -->
  <?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://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
  
      <entity
          name="AppBundleEntityProduct"
          repository-class="AppBundleEntityProductRepository">
  
          <!-- ... -->
      </entity>
  </doctrine-mapping>
  

小技巧

The entity manager can be accessed via $this->getEntityManager() from inside the repository.

注解

When using a custom repository class, you still have access to the default finder methods such as find() and findAll().

$ php app/console doctrine:generate:entity 
    --entity="AppBundle:Category" 
    --fields="name:string(255)"

• Annotations

  // src/AppBundle/Entity/Category.php
  
  // ...
  use DoctrineCommonCollectionsArrayCollection;
  
  class Category
  {
      // ...
  
      /**
       * @ORMOneToMany(targetEntity="Product", mappedBy="category")
       */
      protected $products;
  
      public function __construct()
      {
          $this->products = new ArrayCollection();
      }
  }
  

• YAML

  # src/AppBundle/Resources/config/doctrine/Category.orm.yml
  AppBundleEntityCategory:
      type: entity
      # ...
      oneToMany:
          products:
              targetEntity: Product
              mappedBy: category
      # don't forget to init the collection in the __construct() method
      # of the entity
  

• XML

  <!-- src/AppBundle/Resources/config/doctrine/Category.orm.xml -->
  <?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://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
  
      <entity name="AppBundleEntityCategory">
          <!-- ... -->
          <one-to-many
              field="products"
              target-entity="Product"
              mapped-by="category" />
  
          <!--
              don't forget to init the collection in
              the __construct() method of the entity
          -->
      </entity>
  </doctrine-mapping>
  

注解

The code in the __construct() method is important because Doctrine requires the $products property to be an ArrayCollection object. This object looks and acts almost exactly like an array, but has some added flexibility. If this makes you uncomfortable, don’t worry. Just imagine that it’s an array and you’ll be in good shape.

小技巧

The targetEntity value in the decorator used above can reference any entity with a valid namespace, not just entities defined in the same namespace. To relate to an entity defined in a different class or bundle, enter a full namespace as the targetEntity.

• Annotations

  // src/AppBundle/Entity/Product.php
  
  // ...
  class Product
  {
      // ...
  
      /**
       * @ORMManyToOne(targetEntity="Category", inversedBy="products")
       * @ORMJoinColumn(name="category_id", referencedColumnName="id")
       */
      protected $category;
  }
  

• YAML

  # src/AppBundle/Resources/config/doctrine/Product.orm.yml
  AppBundleEntityProduct:
      type: entity
      # ...
      manyToOne:
          category:
              targetEntity: Category
              inversedBy: products
              joinColumn:
                  name: category_id
                  referencedColumnName: id
  

• XML

  <!-- src/AppBundle/Resources/config/doctrine/Product.orm.xml -->
  <?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://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
  
      <entity name="AppBundleEntityProduct">
          <!-- ... -->
          <many-to-one
              field="category"
              target-entity="Category"
              inversed-by="products"
              join-column="category">
  
              <join-column name="category_id" referenced-column-name="id" />
          </many-to-one>
      </entity>
  </doctrine-mapping>
  

注解

This task should only be really used during development. For a more robust method of systematically updating your production database, read about migrations.

Relationships and Proxy Classes

This “lazy loading” is possible because, when necessary, Doctrine returns a “proxy” object in place of the true object. Look again at the above example:

$product = $this->getDoctrine()
    ->getRepository('AppBundle:Product')
    ->find($id);

$category = $product->getCategory();

// prints "ProxiesAppBundleEntityCategoryProxy"
echo get_class($category);

This proxy object extends the true Category object, and looks and acts exactly like it. The difference is that, by using a proxy object, Doctrine can delay querying for the real Category data until you actually need that data (e.g. until you call $category->getName()).

The proxy classes are generated by Doctrine and stored in the cache directory. And though you’ll probably never even notice that your $category object is actually a proxy object, it’s important to keep it in mind.

In the next section, when you retrieve the product and category data all at once (via a join), Doctrine will return the true Category object, since nothing needs to be lazily loaded.

小技巧

Remember that you can see all of the queries made during a request via the web debug toolbar.

注解

If you’re using annotations, you’ll need to prepend all annotations with ORM (e.g. ORMOneToMany), which is not reflected in Doctrine’s documentation. You’ll also need to include the use DoctrineORMMapping as ORM; statement, which imports the ORM annotations prefix.

/**
 * @ORMEntity()
 * @ORMHasLifecycleCallbacks()
 */
class Product
{
    // ...
}