++ Introduction
++ Levels of configuration
++ General attributes
+++ Portability

Each database management system (DBMS) has it's own behaviors. For example, some databases capitalize field names in their output, some lowercase them, while others leave them alone. These quirks make it difficult to port your scripts over to another server type. Doctrine strives to overcome these differences so your program can switch between DBMS's without any changes.

You control which portability modes are enabled by using the portability configuration option. Configuration options are set via {{factory()}} and {{setOption()}}.

The portability modes are bitwised, so they can be combined using {{|}} and removed using {{^}}. See the examples section below on how to do this.


++++ Portability Mode Constants


: {{Doctrine::PORTABILITY_ALL}} (default) : turn on all portability features. this is the default setting. 

: {{Doctrine::PORTABILITY_DELETE_COUNT}} : Force reporting the number of rows deleted. Some DBMS's don't count the number of rows deleted when performing simple {{DELETE FROM}} tablename queries. This mode tricks such DBMS's into telling the count by adding {{WHERE 1=1}} to the end of {{DELETE}} queries. 

: {{Doctrine::PORTABILITY_EMPTY_TO_NULL}} : Convert empty strings values to null in data in and output. Needed because Oracle considers empty strings to be null, while most other DBMS's know the difference between empty and null. 

: {{Doctrine::PORTABILITY_ERRORS}} : Makes certain error messages in certain drivers compatible with those from other DBMS's 

: {{Doctrine::PORTABILITY_FIX_ASSOC_FIELD_NAMES}} : This removes any qualifiers from keys in associative fetches. some RDBMS , like for example SQLite, will be default use the fully qualified name for a column in assoc fetches if it is qualified in a query.

: {{Doctrine::PORTABILITY_FIX_CASE}} : Convert names of tables and fields to lower or upper case in all methods. The case depends on the {{field_case}} option that may be set to either {{CASE_LOWER}} (default) or {{CASE_UPPER}} 

: {{Doctrine::PORTABILITY_NONE}} : Turn off all portability features 

: {{Doctrine::PORTABILITY_NUMROWS}} : Enable hack that makes {{numRows()}} work in Oracle 

: {{Doctrine::PORTABILITY_EXPR}} : Makes DQL API throw exceptions when non-portable expressions are being used.

: {{Doctrine::PORTABILITY_RTRIM}} : Right trim the data output for all data fetches. This does not applied in drivers for RDBMS that automatically right trim values of fixed length character values, even if they do not right trim value of variable length character values.


++++ Examples
 
Using {{setAttribute()}} to enable portability for lowercasing and trimming

<code type="php">
$conn->setAttribute('portability',
        Doctrine::PORTABILITY_FIX_CASE | Doctrine::PORTABILITY_RTRIM);
</code>

Using {{setAttribute()}} to enable all portability options except trimming

<code type="php">
$conn->setAttribute('portability',
        Doctrine::PORTABILITY_ALL ^ Doctrine::PORTABILITY_RTRIM);
</code>


+++ Identifier quoting

You can quote the db identifiers (table and field names) with {{quoteIdentifier()}}. The delimiting style depends on which database driver is being used.

NOTE: just because you CAN use delimited identifiers, it doesn't mean you SHOULD use them. In general, they end up causing way more problems than they solve. Anyway, it may be necessary when you have a reserved word as a field name (in this case, we suggest you to change it, if you can).

Some of the internal Doctrine methods generate queries. Enabling the {{quote_identifier}} attribute of Doctrine you can tell Doctrine to quote the identifiers in these generated queries. For all user supplied queries this option is irrelevant.

Portability is broken by using the following characters inside delimited identifiers: 

* backtick (`) -- due to MySQL
* double quote (") -- due to Oracle
* brackets ([ or ]) -- due to Access

Delimited identifiers are known to generally work correctly under the following drivers: 

* Mssql
* Mysql
* Oracle
* Pgsql
* Sqlite
* Firebird

When using the {{ATTR_QUOTE_IDENTIFIER}} option, all of the field identifiers will be automatically quoted in the resulting SQL statements:

<code type="php">
$conn->setAttribute(Doctrine::ATTR_QUOTE_IDENTIFIER, true);
</code>

will result in a SQL statement that all the field names are quoted with the backtick '`' operator (in MySQL). 

<code type="sql">
SELECT * FROM `sometable` WHERE `id` = '123'
</code>

as opposed to:

<code type="sql">
SELECT * FROM sometable WHERE id='123'
</code>


+++ Exporting

The export attribute is used for telling Doctrine what it should export when exporting classes.

If you don't want to export anything when calling export() you can use:

<code type="php">
$manager->setAttribute(Doctrine::ATTR_EXPORT, Doctrine::EXPORT_NONE);
</code>

For exporting tables only (but not constraints) you can use on of the following:

<code type="php">
$manager->setAttribute(Doctrine::ATTR_EXPORT, Doctrine::EXPORT_TABLES);
// or you can use
$manager->setAttribute(Doctrine::ATTR_EXPORT, Doctrine::EXPORT_ALL ^ Doctrine::EXPORT_CONSTRAINTS);
</code>

For exporting everything (tables and constraints) you can use:

<code type="php">
$manager->setAttribute(Doctrine::ATTR_EXPORT, Doctrine::EXPORT_ALL);
</code>

+++ Event listener

<code type="php">
// setting default event listener
$manager->setAttribute(Doctrine::ATTR_LISTENER, new MyListener());
</code>
++ Naming convention attributes

Naming convention attributes affect on the naming of different database related elements such as tables, indexes and sequences. Basically every naming convention attribute has affect in both ways. When importing schemas from the database to classes and when exporting classes into database.

So for example by default Doctrine naming convention for indexes is %s_idx. Not only do the indexes you set get a special suffix, also the imported classes get their indexes mapped to their non-suffixed equivalents. This applies to all naming convention attributes.

+++ Index name format

Doctrine::ATTR_IDXNAME_FORMAT can be used for changing the naming convention of indexes. By default Doctrine uses the format [name]_idx. So defining an index called 'ageindex' will actually be converted into 'ageindex_idx'.

<code type="php">
// changing the index naming convention
$manager->setAttribute(Doctrine::ATTR_IDXNAME_FORMAT, '%s_index');
</code>

+++ Sequence name format

Similar to Doctrine::ATTR_IDXNAME_FORMAT, Doctrine::ATTR_SEQNAME_FORMAT can be used for changing the naming convention of sequences. By default Doctrine uses the format [name]_seq, hence creating a new sequence with the name of 'mysequence' will lead into creation of sequence called 'mysequence_seq'.

<code type="php">
// changing the sequence naming convention
$manager->setAttribute(Doctrine::ATTR_IDXNAME_FORMAT, '%s_sequence');
</code>

+++ Table name format

+++ Database name format

<code type="php">
// changing the database naming convention
$manager->setAttribute(Doctrine::ATTR_DBNAME_FORMAT, 'myframework_%s');
</code>

++ Validation attributes

Doctrine provides complete control over what it validates. The validation procedure can be controlled with Doctrine::ATTR_VALIDATE.

The validation modes are bitwised, so they can be combined using {{|}} and removed using {{^}}. See the examples section below on how to do this.

+++ Validation mode constants

: {Doctrine::VALIDATE_NONE} : Turns off the whole validation procedure. This is the default value.

: {Doctrine::VALIDATE_LENGTHS} : Makes Doctrine validate all field lengths.

: {Doctrine::VALIDATE_TYPES} : Makes Doctrine validate all field types. Doctrine does loose type validation. This means that for example string with value '13.3' will not pass as an integer but '13' will.

: {Doctrine::VALIDATE_CONSTRANTS} : Makes Doctrine validate all field constraints such as notnull, email etc.

: {Doctrine::VALIDATE_ALL} : Turns on all validations.

+++ Examples

Turning on all validations:

<code type="php">
$manager->setAttribute(Doctrine::ATTR_VALIDATE, Doctrine::VALIDATE_ALL);
</code>

Validating lengths and types, but not constraints:

<code type="php">
$manager->setAttribute(Doctrine::ATTR_VALIDATE, Doctrine::VALIDATE_LENGTHS | Doctrine::VALIDATE_TYPES);
</code>