Changeset 3922

Show
Ignore:
Timestamp:
03/02/08 05:47:59 (16 months ago)
Author:
jwage
Message:

Expaned schema files chapter with more examples. Documented all the new features.

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • branches/0.10/manual/docs/en/schema-files.txt

    r3921 r3922  
    88connection binding, relationships, attributes, templates/behaviors, indexes, etc. 
    99 
     10++ Short Hand Syntax 
     11 
     12Doctrine offers the ability to specify schema in a short hand syntax. A lot of the schema parameters  
     13have values they default to, this allows us to abbreviate the syntax and let Doctrine just use its  
     14defaults. Below is an example of schema taking advantage of all the shorthand features. 
     15 
     16<code type="php"> 
     17--- 
     18detect_relations: true 
     19 
     20User: 
     21  columns: 
     22    username: string 
     23    password: string 
     24    contact_id: integer 
     25 
     26Contact: 
     27  columns: 
     28    first_name: string 
     29    last_name: string 
     30    phone: string 
     31    email: string 
     32    address: string 
     33</code> 
     34 
     35++ Expanded Syntax 
     36 
     37Here is the none short hand form of the above schema. 
     38 
     39<code type="php"> 
     40--- 
     41detect_relations: true 
     42 
     43User: 
     44  columns: 
     45    username: 
     46      type: string(255) 
     47    password: 
     48      type: string(255) 
     49    contact_id: 
     50      type: integer 
     51  relations: 
     52    Contact: 
     53      class: Contact 
     54      local: contact_id 
     55      foreign: id 
     56      foreignAlias: User 
     57      foreignType: one 
     58      type: one 
     59 
     60Contact: 
     61  columns: 
     62    first_name: 
     63      type: string(255) 
     64    last_name: 
     65      type: string(255) 
     66    phone: 
     67      type: string(255) 
     68    email: 
     69      type: string(255) 
     70    address: 
     71      type: string(255) 
     72  relations: 
     73    User: 
     74      class: User 
     75      local: id 
     76      foreign: contact_id 
     77      foreignAlias: Contact 
     78      foreignType: one 
     79      type: one 
     80</code> 
     81 
    1082++ Relationships 
    1183 
    1284When specifying relationships it is only necessary to specify the relationship on the end where  
    13 the foreign key exists, although both ways are supported. 
     85the foreign key exists. When the schema file is parsed, it inflects the relationship and builds the  
     86opposite end automatically. If you specify the other end of the relationship manually, the auto  
     87generation will have no effect. 
     88 
     89Doctrine will also attempt to guess the local and foreign key names based on the class involved in the  
     90relationship. You will notice that all of our example schemas do not include the specific local and  
     91foreign keys because it is able to guess them. 
     92 
     93+++ Detect Relations 
     94 
     95Doctrine offers the ability to specify a detect_relations options. This feature provides automatic  
     96relationship building based on column names. If you have a User model with a contact_id and a class  
     97with the name Contact exists, it will automatically create the relationships between the two. 
     98 
     99+++ Customizing Relationships 
     100 
     101Doctrine only requires that you specify the relationship on the end where the foreign key exists. The  
     102opposite end of the relationship will be inflected and built on the opposite end. The schema syntax  
     103offers the ability to customize the relationship alias and type of the opposite end. This is good news  
     104because it means you can maintain all the relevant relationship information in one place. Below is an  
     105example of how to customize the alias and type of the opposite end of the relationship. It demonstrates  
     106the relationships User hasOne Contact and Contact hasOne User as UserModel. Normally it would have  
     107automatically generated User hasOne Contact and Contact hasMany User. The foreignType and foreignAlias  
     108keywords allow you to customize the foreign relationship. 
     109 
     110<code type="yaml"> 
     111--- 
     112User: 
     113  columns: 
     114    id: 
     115      type: integer(4) 
     116      primary: true 
     117      autoincrement: true 
     118    contact_id: 
     119      type: integer(4) 
     120    username: 
     121      type: string(255) 
     122    password: 
     123      type: string(255) 
     124  relations: 
     125    Contact: 
     126      foreignType: one 
     127      foreignAlias: UserModel 
     128 
     129Contact: 
     130  columns: 
     131    id: 
     132      type: integer(4) 
     133      primary: true 
     134      autoincrement: true 
     135    name: 
     136      type: string(255) 
     137</code> 
     138 
     139Here is an example schema: 
     140 
     141<code type="yaml"> 
     142--- 
     143detect_relations: true 
     144 
     145User: 
     146  columns: 
     147    id: 
     148      type: integer(4) 
     149      primary: true 
     150      autoincrement: true 
     151    contact_id: 
     152      type: integer(4) 
     153    username: 
     154      type: string(255) 
     155    password: 
     156      type: string(255) 
     157 
     158Contact: 
     159  columns: 
     160    id: 
     161      type: integer(4) 
     162      primary: true 
     163      autoincrement: true 
     164    name: 
     165      type: string(255) 
     166</code> 
     167 
     168The resulting relationships will be User hasOne Contact and Contact hasMany User. 
    14169 
    15170+++ One to One 
    … …  
    113268</code> 
    114269 
    115 ++ Connection Binding 
     270++ Features & Examples 
     271 
     272+++ Connection Binding 
    116273 
    117274<code type="php"> 
    … …  
    136293</code> 
    137294 
    138 ++ Attributes 
     295+++ Attributes 
    139296 
    140297<code type="yaml"> 
    … …  
    158315</code> 
    159316 
    160 ++ Enums 
     317+++ Enums 
    161318 
    162319<code type="yaml"> 
    … …  
    178335</code> 
    179336 
    180 ++ Templates 
     337+++ Templates 
    181338 
    182339<code type="yaml"> 
    … …  
    201358</code> 
    202359 
    203 ++ ActAs 
     360+++ ActAs 
    204361 
    205362<code type="yaml"> 
    … …  
    223380</code> 
    224381 
    225 ++ Options 
     382+++ Options 
    226383 
    227384<code type="yaml"> 
    … …  
    246403</code> 
    247404 
    248 ++ Indexes 
     405+++ Indexes 
    249406 
    250407Please see chapter [doc basic-schema-mapping :index :name] for more information about indexes and  
    … …  
    285442</code> 
    286443 
    287 ++ Inheritance 
     444+++ Inheritance 
    288445 
    289446<code type="yaml"> 
    … …  
    308465</code> 
    309466 
    310 ++ Generating Models 
     467+++ Generate Accessors 
     468 
     469When the generate_accessors: true option is present in a schema file, it will generate propel orm style  
     470get and set accessors in the Base model definition. For example setFieldName() and getFieldName() would  
     471then be possible in your models. 
     472 
     473Example: 
     474<code type="yaml"> 
     475--- 
     476generate_accessors: true 
     477 
     478User: 
     479  columns: 
     480    username: 
     481      type: string(255) 
     482</code> 
     483 
     484+++ Column Aliases 
     485 
     486If you want the ability alias a column name as something other than the column name in the database  
     487this is possible with the " as alias_name" string after the column name. 
     488 
     489Example: 
     490<code type="yaml"> 
     491--- 
     492User: 
     493  columns: 
     494    login: 
     495      name: login as username 
     496      type: string(255) 
     497    password: 
     498      type: string(255) 
     499</code> 
     500 
     501The above example would allow you to access the login column name from the alias "username". 
     502 
     503+++ Packages 
     504 
     505Doctrine offers the "package" parameter which will generate the models in to sub folders. With large  
     506schema files this will allow you to better organize your schemas in to folders. 
     507 
     508<code type="yaml"> 
     509--- 
     510User: 
     511  package: User 
     512  columns: 
     513    username: string(255) 
     514</code> 
     515 
     516The model files from this schema file would be put in a folder named User. You can specify more sub  
     517folders by doing "package: User.Models" and the models would be in User/Models 
     518 
     519+++ Global Schema Information 
     520 
     521Doctrine schemas allow you to specify certain parameters that will apply to all of the models defined  
     522in the schema file. Below you can find an example on what global parameters you can set for schema files. 
     523 
     524List of global parameters: 
     525 
     526connection 
     527attributes 
     528templates 
     529actAs 
     530options 
     531package 
     532inheritance 
     533detect_relations 
     534generate_accessors 
     535 
     536<code type="yaml"> 
     537--- 
     538connection: conn_name1 
     539actAs: [Timestampable] 
     540options: 
     541  type: INNODB 
     542package: User 
     543detect_relations: true 
     544generate_accessors: true 
     545 
     546User: 
     547  columns: 
     548    id: 
     549      type: integer(4) 
     550      primary: true 
     551      autoincrement: true 
     552    contact_id: 
     553      type: integer(4) 
     554    username: 
     555      type: string(255) 
     556    password: 
     557      type: string(255) 
     558 
     559Contact: 
     560  columns: 
     561    id: 
     562      type: integer(4) 
     563      primary: true 
     564      autoincrement: true 
     565    name: 
     566      type: string(255) 
     567</code> 
     568 
     569All of the settings at the top will be applied to every model which is defined in that yaml file. 
     570 
     571++ Using Schema Files 
    311572 
    312573Once you have defined your schema files you need some code to  
    … …  
    322583 
    323584// This code will generate the models for schema.yml at /path/to/generate/models 
    324 Doctrine::generateModelsFromYaml('schema.yml', '/path/to/generate/models', $options); 
    325 </code> 
     585Doctrine::generateModelsFromYaml('/path/to/directory/with/yaml/schema/files', '/path/to/generate/models', $options); 
     586</code>