From 293e75261111ab89bebb619301055179cec43883 Mon Sep 17 00:00:00 2001
From: "Jonathan.Wage" <Jonathan.Wage@625475ce-881a-0410-a577-b389adb331d8>
Date: Fri, 5 Oct 2007 20:19:54 +0000
Subject: [PATCH] Added documentation for schema files.

---
 manual/new/docs/en.txt              |   5 +-
 manual/new/docs/en/schema-files.txt | 184 ++++++++++++++++++++++++++++
 2 files changed, 187 insertions(+), 2 deletions(-)

diff --git a/manual/new/docs/en.txt b/manual/new/docs/en.txt
index ef206f44c..65e422129 100644
--- a/manual/new/docs/en.txt
+++ b/manual/new/docs/en.txt
@@ -12,9 +12,10 @@
 + Event listeners
 + Class templates
 + Plugins
-+ File Parser
++ File parser
 + Migration
-+ Data Fixtures
++ Data fixtures
++ Schema Files
 + Searching
 + Database abstraction
 + Improving Performance
diff --git a/manual/new/docs/en/schema-files.txt b/manual/new/docs/en/schema-files.txt
index e69de29bb..9f96b73ae 100644
--- a/manual/new/docs/en/schema-files.txt
+++ b/manual/new/docs/en/schema-files.txt
@@ -0,0 +1,184 @@
+++ 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.
+
+++ Example Schema File
+
+'tableName' and 'className' are optional. If not specified they will be set by the key of the yaml block
+
+schema.yml
+<code type="yml">
+---
+User: 
+  columns: 
+    id: 
+      notnull: true
+      primary: true
+      autoincrement: true
+      type: integer
+      length: 4
+      name: id
+    username: 
+      type: string
+      length: 255
+  relations:
+    Groups:
+      class: Group
+      refClass: UserGroup
+      local: user_id
+      foreign: group_id
+      type: many
+UserGroup:
+  columns:
+    user_id:
+      type: integer
+      length: 4
+      primary: true
+    group_id:
+      type: integer
+      length: 4
+      primary: true
+  relations:
+    User:
+      local: user_id
+      foreign: id
+    Group:
+      local: group_id
+      foreign: id
+Group: 
+  columns: 
+    id: 
+      notnull: true
+      primary: true
+      autoincrement: true
+      type: integer
+      length: 4
+      name: id
+    name: 
+      type: string
+      length: 255
+  relations:
+    Users:
+      class: User
+      refClass: UserGroup
+      local: group_id
+      foreign: user_id
+      type: many
+</code>
+
+And now we want to use some Doctrine code to parse that schema yml file and generate our models from it
+
+<code type="php">
+// This code will generate the models for schema.yml at /path/to/generate/models
+$import = new Doctrine_Import_Schema();
+$import->importSchema('schema.yml', 'yml', '/path/to/generate/models');
+</code>
+
+This is the directory structure that would be generated at /path/to/generate/models
+
+<code>
+- Group.class.php
+- User.class.php
+- UserGroup.class.php
+- generated
+  - BaseGroup.class.php
+  - BaseUser.class.php
+  - BaseUserGroup.class.php
+</code>
+
+And finally here is the code for each of the generated models
+
+<code type="php">
+
+// Group.class.php
+
+/**
+ * This class has been auto-generated by the Doctrine ORM Framework
+ */
+class Group extends BaseGroup
+{
+}
+
+// User.class.php
+
+/**
+ * This class has been auto-generated by the Doctrine ORM Framework
+ */
+class User extends BaseUser
+{
+}
+
+// BaseGroup.class.php
+
+/**
+ * This class has been auto-generated by the Doctrine ORM Framework
+ */
+abstract class BaseGroup extends sfDoctrineRecord
+{
+
+		public function setTableDefinition()
+		{
+        $this->setTableName('group');
+        $this->hasColumn('id', 'integer', 4, array('notnull' => true,
+                                                   'primary' => true,
+                                                   'autoincrement' => true));
+        $this->hasColumn('name', 'string', 255);
+		}
+
+		public function setUp()
+		{
+        $this->hasMany('User as Users', array('refClass' => 'UserGroup',
+                                              'local' => 'group_id',
+                                              'foreign' => 'user_id'));
+		}
+}
+
+// BaseUser.class.php
+
+/**
+ * This class has been auto-generated by the Doctrine ORM Framework
+ */
+abstract class BaseUser extends sfDoctrineRecord
+{
+
+		public function setTableDefinition()
+		{
+        $this->setTableName('user_table');
+        $this->hasColumn('id', 'integer', 4, array('notnull' => true,
+                                                   'primary' => true,
+                                                   'autoincrement' => true));
+        $this->hasColumn('username', 'string', 255);
+		}
+
+		public function setUp()
+		{
+        $this->hasMany('Group as Groups', array('refClass' => 'UserGroup',
+                                                'local' => 'user_id',
+                                                'foreign' => 'group_id'));
+		}
+}
+
+// BaseUserGroup.class.php
+
+/**
+ * This class has been auto-generated by the Doctrine ORM Framework
+ */
+abstract class BaseUserGroup extends sfDoctrineRecord
+{
+
+		public function setTableDefinition()
+		{
+        $this->setTableName('user_group');
+        $this->hasColumn('user_id', 'integer', 4, array('primary' => true));
+        $this->hasColumn('group_id', 'integer', 4, array('primary' => true));
+		}
+
+		public function setUp()
+		{
+        $this->hasOne('User', array('local' => 'user_id',
+                                    'foreign' => 'id'));
+        $this->hasOne('Group', array('local' => 'group_id',
+                                     'foreign' => 'id'));
+		}
+}
+</code>
\ No newline at end of file