doctrine2/manual/docs/en/schema-files.txt

++ Introduction

The purpose of schema files is to allow you to manage your model definitions directly from a yaml file rather then editing php code. The yaml schema file is parsed and used to generate all your model definitions/classes. This makes Doctrine model definitions much more portable.

Schema files support all the normal things you would write with manual php code. Component to connection binding, relationships, attributes, templates/behaviors, indexes, etc.

++ Relationships

When specifying relationships it is only necessary to specify the relationship on the end where the foreign key exists, although both ways are supported.

+++ One to One

<code type="yaml">
---
User:
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    contact_id:
      type: integer(4)
    username:
      type: string(255)
    password:
      type: string(255)
  relations:
    Contact:
      foreignType: one
Contact:
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    name:
      type: string(255)
</code>

+++ One to Many

<code type="yaml">
---
User:
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    contact_id:
      type: integer(4)
    username:
      type: string(255)
    password:
      type: string(255)
Phonenumber:
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    name:
      type: string(255)
    user_id:
      type: integer(4)
  relations:
    User:
      foreignAlias: Phonenumbers
</code>

+++ Many to Many

<code type="yaml">
User:
  columns:
    id:
      type: integer(4)
      autoincrement: true
      primary: true
    username:
      type: string(255)
    password:
      type: string(255)
  attributes:
    export: all
    validate: true
Group:
  tableName: group_table
  columns:
    id:
      type: integer(4)
      autoincrement: true
      primary: true
    name:
      type: string(255)
  relations:
    Users:
      foreignAlias: Groups
      class: User
      refClass: GroupUser
GroupUser:
  columns:
    group_id:
      type: integer(4)
      primary: true
    user_id:
      type: integer(4)
      primary: true
</code>

+++ One to One Aggregate

<code type="yaml">
---
User:
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    contact_id:
      type: integer(4)
    username:
      type: string(255)
    password:
      type: string(255)
  relations:
    Contact:
      foreignType: one
      onDelete: CASCADE
Contact:
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    name:
      type: string(255)
</code>

++ Connection Binding

<code type="php">
Doctrine::connection('mysql://user:pass@localhost/connection1', 'connection1');
</code>

<code type="yaml">
---
User:
  connection: connection1
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    contact_id:
      type: integer(4)
    username:
      type: string(255)
    password:
      type: string(255)
</code>

++ Attributes

<code type="yaml">
---
User:
  connection: connection1
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    contact_id:
      type: integer(4)
    username:
      type: string(255)
    password:
      type: string(255)
  attributes:
    export: none
    validate: false
</code>

++ Enums

<code type="yaml">
---
TvListing:
 tableName: tv_listing
 actAs: [Timestampable]
 columns:
   notes:
     type: string
   taping:
     type: enum
     length: 4
     values: ['live', 'tape']
   region:
     type: enum
     length: 4
     values: ['US', 'CA']
</code>

++ Templates

<code type="yaml">
---
User:
  connection: connection1
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    contact_id:
      type: integer(4)
    username:
      type: string(255)
    password:
      type: string(255)
  templates:
    MyCustomTemplate
      option1: value
      option2: value
</code>

++ ActAs

<code type="yaml">
---
User:
  connection: connection1
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    contact_id:
      type: integer(4)
    username:
      type: string(255)
    password:
      type: string(255)
  actAs:
    Sluggable:
      fields: [username]
</code>

++ Options

<code type="yaml">
---
User:
  connection: connection1
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    contact_id:
      type: integer(4)
    username:
      type: string(255)
    password:
      type: string(255)
  options:
    type: INNODB
    collate: utf8_unicode_ci
    charset: utf8
</code>

++ Indexes

Please see chapter [doc basic-schema-mapping :index :name] for more information about indexes and their options.

schema.yml
<code type="yml">
---
UserProfile:
  columns:
    user_id:
      type: integer
      length: 4
      primary: true
      autoincrement: true
    first_name:
      type: string
      length: 20
    last_name:
      type: string
      length: 20
  indexes:
    name_index:
      fields:
        first_name:
          sorting: ASC
          length: 10
          primary: true
        last_name: []
      type: unique
</code>

This is the PHP line of code that is auto-generated inside setTableDefinition() inside your base model class.

<code type="php">
$this->index('name_index', array('fields' => array('first_name' => array( 'sorting' => 'ASC', 'length' => '10', 'primary' => true ), 'last_name' => array( ) ), 'type' => 'unique'));
</code>

++ Inheritance

<code type="yaml">
---
Entity:
  actAs: [Timestampable]
  columns:
    id:
      type: integer(4)
      primary: true
      autoincrement: true
    username:
      type: string(255)
    password:
      type: string(255)
User:
  inheritance:
    extends: Entity
Group:
  inheritance:
    extends: Entity
</code>

++ Generating Models

Once you have defined your schema files you need some code to 
<code type="php">
// The options are completely optional. Only use this if you need something beyond the default configuration for model generation
$options = array('packagesPrefix'        =>  'Package',             // What to prefix the middle package models with
                 'packagesPath'          =>  '',                    // this defaults to the "#models_path#/packages"
                 'generateBaseClasses'   =>  true,                  // Whether or not to generate abstract base models containing the definition and a top level class which is empty extends the base
                 'generateTableClasses'  =>  true,                  // Whether or not to generate a table class for each model
                 'baseClassesDirectory'  =>  'generated',           // Name of the folder to generate the base class definitions in
                 'baseClassName'         =>  'Doctrine_Record',     // Name of the base Doctrine_Record class
                 'suffix'                =>  '.php');               // Extension for your generated models

// This code will generate the models for schema.yml at /path/to/generate/models
Doctrine::generateModelsFromYaml('schema.yml', '/path/to/generate/models', $options);
</code>