# Upgrade from 1.1 to 1.2

This document details the changes made to Doctrine 1.2 to make it easier for you
to upgrade your projects to use this version.

## Removed Attribute String Support

The string support of `Doctrine_Configurable::getAttribute()` and 
`Doctrine_Configurable::setAttribute()` have been removed.

The reason is that the performance of this simple convenience feature is 
significant and it is totally unneeded.

The following code is no longer supported.

    [php]
    $connection->setAttribute('use_native_enum', true);

You must now always use the following code.

    [php]
    $connection->setAttribute(Doctrine::ATTR_USE_NATIVE_ENUM, true);

## Removed all Deprecated Functions

Removed all functions labeled `@deprecated` in the doc blocks.

Affected Classes

* Doctrine_Query
* Doctrine_Query_Abstract

## Renamed Methods

* Doctrine_Query_Abstract::getSql() to getSqlQuery()
* Doctrine_Search_Query::getSql() to getSqlQuery()
* Doctrine_Query_Abstract::getCountQuery() to getCountSqlQuery()
* Doctrine_RawSql::getCountQuery() to getCountSqlQuery()

## Added ability to configure base table class for class builder

Introduced option named `baseTableClassName` to configure the class child 
`Doctrine_Table` instances use which defaults to `Doctrine_Table`.

    [php]
    $builder = new Doctrine_Import_Builder();
    $builder->setOption('baseTableClassName', 'MyBaseTable');

## Added ability to configure query class

Before Doctrine 1.2 it was hard coded internally to always use the 
`Doctrine_Query` class whenever you instantiate a new query. Now you can 
configure which class this is to use by setting the `Doctrine::ATTR_QUERY_CLASS` 
attribute.

    [php]
    class MyQuery extends Doctrine_Query
    {
      
    }

    $manager->setAttribute(Doctrine::ATTR_QUERY_CLASS, 'MyQuery');

    $q = Doctrine_Query::create();

    echo get_class($q); // MyQuery

## Changed Doctrine_Parser_Xml::arrayToXml() to be static

Now the `arrayToXml()` method can be called directly because it is static.

    [php]
    $array = array(
      'key1' => 'value',
      'key2' => 'value'
    );
    $xml = Doctrine_Parser_Xml::arrayToXml($array);

## Refactored Migrations to better handle multiple connections

Now when working with `Doctrine_Migration` instance you can specify as the 
second argument to the constructor the connection instance to use for the 
migrations.

Migrations for different databases should be handled with a different set of 
migration classes.

Previous method of finding connection based on the table name is flawed since 
databases could have the same table name multiple times.

    [php]
    $conn = Doctrine_Manager::connection();
    $migration = new Doctrine_Migration('/path/to/migrations', $conn);

## Added option for save cascading

Added a new attribute to control whether cascading save operations are done by 
default. Previous to Doctrine 1.2 they were always cascaded.

As of 1.2 you have the option to disable cascading saves and will only cascade 
if the record is dirty. The cost of this is that you can't cascade and save 
records who are dirty that are more then one level deep in the hierarchy.

See: http://trac.doctrine-project.org/ticket/1623

You can disable cascading saves with the following code.

    [php]
    $manager->setAttribute(Doctrine::ATTR_CASCADE_SAVES, false);

Disabling this will increase performance significantly when saving objects.

## Added Doctrine::setPath()

Now you can specify the path to your Doctrine libraries if Doctrine.php is 
outside of the location of your libraries.

So if `Doctrine.php` is located at `/path/to/Doctrine.php` and the actual 
libraries are at `/path/to/the/doctrine/libs` you would need to do the 
following.

    [php]
    Doctrine::setPath('/path/to/the/doctrine/libs');

## Ability to clear an individual reference

Previously the `Doctrine_Record::clearRelated()` would only allow the clearing 
of ALL references. It will now accept a relationship name and you can clear an 
individual reference.

    [php]
    $user->clearRelated('Phonenumber');

## Check related exists

Often you want to check if a relationship exists in the database, but if it 
doesn't exist you get a newly created blank relationship that will try to be 
saved when you call save on the parent record. Use the new `relatedExists()` 
method to check to avoid this behavior.

    [php]
    if ($user->relatedExists('Profile')) {
      // do something if the user has a profile
    }

## Reverse Engineered Columns

If Doctrine does not recognize a column from a database when reverse engineering 
a schema, instead of throwing an exception, it will default to a string.

This allows custom column types or proprietary column types to be reverse 
engineered without stopping the schema from being built completely.

## Oracle Adapter Persistent Connections

The `Doctrine_Adapter_Oracle` now will use persistent connections if specified.

    [php]
    $info = array(
      'oracle:dbname=SID;charset=NLS_CHARACTERSET;persistent=true',
      'usr',
      'pass'
    );

    Doctrine_Manager::connection($info, 'conn_name');

## New Class/File Prefix Option for Model Builder

You can now set a prefix for your generated models and choose to not have the 
generated filename include that prefix as well.

    [php]
    $builder = new Doctrine_Import_Builder();
    $builder->setOption('classPrefixFiles', false);
    $builder->setOption('classPrefix', 'MyClassPrefix_');

Without the first option you'd get a file like `MyClassPrefix_ModelName.php` but 
now you will get `ModelName.php` with a class named `MyClassPrefix_ModelName` 
inside.

## Expanded Magic Finders to Multiple Fields

You can now `findBy` multiple fields and specify conditions between the fields.

    [php]
    $user = $userTable->findOneByUsernameAndPassword('jwage', md5('changeme'));

Or you could do something like the following and find admin users and moderator 
users.

    [php]
    $users = $userTable->findByIsAdminOrIsModerator(true, true);

You can mix the conditions.

    [php]
    $users = $userTable->findByIsAdminAndIsModeratorOrIsSuperAdmin(true, true, true);

> **CAUTION**
> These are very limited magic finders and it is always recommended to expand 
> your queries to be manually written DQL queries. These methods are meant for 
> only quickly accessing single records, no relationships, and are good for 
> prototyping code quickly.

## Custom Collection Class

You can now specify a custom child class to use for all collections inside 
Doctrine.

    [php]
    $manager->setAttribute(Doctrine::ATTR_COLLECTION_CLASS, 'MyCollection');
    
    $phonenumbers = $user->Phonenumbers;
    echo get_class($phonenumbers); // MyCollection

Now define the simple child class.

    [php]
    class MyCollection extends Doctrine_Collection
    {
      
    }

This option can be set at the manager, connection and table levels.

## Custom Hydrators

As of Doctrine 1.2 it is now possible to register your own custom data 
hydrators. The core hydration process has been decoupled to proper drivers and 
now you can register your own to handle the hydration process.

First lets register our custom hydrator class.

    [php]
    $manager->registerHydrator('MyHydrator', 'Doctrine_Hydrator_MyHydrator');

So now we need to define a hydrator class named `MyHydrator` and it must 
implement a method named `hydrateResultSet($stmt)` method which accepts a 
query statement object.

    [php]
    class Doctrine_Hydrator_MyHydrator extends Doctrine_Hydrator_Abstract
    {
        public function hydrateResultSet($stmt)
        {
            return $stmt->fetchAll(PDO::FETCH_ASSOC);
        }
    }

Now you can run a query like the following which would use the new `MyHydrator`.

    [php]
    $q->execute(array(), 'MyHydrator');

# Custom Connections

You can now write and register your own custom Doctrine connection drivers and 
adapters.

    [php]
    class Doctrine_Connection_Test extends Doctrine_Connection_Common
    {
    }

    class Doctrine_Adapter_Test implements Doctrine_Adapter_Interface
    {
      // ... all the methods defined in the interface
    }

Now we can register this with Doctrine so we can utilize it as our connection.

    [php]
    $manager->registerConnectionDriver('test', 'Doctrine_Connection_Test');

Now you can utilize that type of connection in your DSN when connecting.

    [php]
    $conn = $manager->openConnection('test://username:password@localhost/dbname');

Now if we were to check what classes are used for the connection you will notice
that they are the classes we defined above.

    [php]
    echo get_class($conn); // Doctrine_Connection_Test
    echo get_class($conn->getDbh()); // Doctrine_Adapter_Test

# Doctrine Extensions

Doctrine now has support for creating, loading and testing extensions in to your 
projects.

First we need to simply tell `Doctrine` where the extensions are being loaded 
from.

    [php]
    Doctrine::setExtensionsPath('/path/to/extensions');

Now we can check out one of the first available extensions in to our extensions 
directory and then register it.

    $ svn co http://svn.doctrine-project.org/extensions/Sortable/branches/1.2-1.0/ /path/to/extensions/Sortable

The directory structure of this extension looks like the following.

    Sortable/
    	lib/
    		Doctrine/
    			Template/
    				Listener/
    					Sortable.php
    				Sortable.php
    	tests/
    		run.php
    		Template/
    			SortableTestCase.php

You can even run the tests that come bundled with it. We just need to tell your 
CLI where your Doctrine code is.

    $ export DOCTRINE_DIR=/path/to/doctrine

> **NOTE**
> The above path to Doctrine must be the path to the main folder, not just the 
> lib folder. In order to run the tests it must have access to the `tests` 
> directory included with Doctrine.

Now you can run the tests included.

    $ cd /path/to/extensions/Sortable/tests
    $ php run.php

It should output something like the following.

    Doctrine Unit Tests
    ===================
    Doctrine_Template_Sortable_TestCase.............................................passed

    Tested: 1 test cases.
    Successes: 26 passes.
    Failures: 0 fails.
    Number of new Failures: 0 
    Number of fixed Failures: 0 

    Tests ran in 1 seconds and used 13024.9414062 KB of memory

Now if you want to use the extension in your project you will need register the 
extension with Doctrine and setup the extension autoloading mechanism.

First lets setup the extension autoloading.

    [php]
    spl_autoload_register(array('Doctrine', 'extensionsAutoload'));

Now you can register the extension and the classes inside that extension will be 
autoloaded.

    [php]
    $manager->registerExtension('Sortable');

> **NOTE**
> If you need to register an extension from a different location you can specify 
> the full path to the extension directory as the second argument to the 
> `registerExtension()` method.