Skip to content

Commit

Permalink
feature #4069 document the namespace alias feature (dbu)
Browse files Browse the repository at this point in the history 
This PR was merged into the master branch.

Discussion
----------

document the namespace alias feature

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | [yes](symfony/symfony#10853)
| Applies to    | 2.6
| Fixed tickets | -

Commits
-------

d753d0e document the namespace alias feature
  • Loading branch information
@weaverryan
weaverryan committed Aug 16, 2014
2 parents c53d9d6 + d753d0e commit 79cb4f1
Showing 1 changed file with 35 additions and 26 deletions.
61 changes: 35 additions & 26 deletions cookbook/doctrine/mapping_model_classes.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,31 +14,31 @@ register the mappings for your model classes.
For non-reusable bundles, the easiest option is to put your model classes
in the default locations: ``Entity`` for the Doctrine ORM or ``Document``
for one of the ODMs. For reusable bundles, rather than duplicate model classes
just to get the auto mapping, use the compiler pass.
just to get the auto-mapping, use the compiler pass.

.. versionadded:: 2.3
The base mapping compiler pass was introduced in Symfony 2.3. The Doctrine bundles
support it from DoctrineBundle >= 1.2.1, MongoDBBundle >= 3.0.0,
PHPCRBundle >= 1.0.0-alpha2 and the (unversioned) CouchDBBundle supports the
PHPCRBundle >= 1.0.0 and the (unversioned) CouchDBBundle supports the
compiler pass since the `CouchDB Mapping Compiler Pass pull request`_
was merged.

If you want your bundle to support older versions of Symfony and
Doctrine, you can provide a copy of the compiler pass in your bundle.
See for example the `FOSUserBundle mapping configuration`_
``addRegisterMappingsPass``.

.. versionadded:: 2.6
Support for defining namespace aliases was introduced in Symfony 2.6.
It is safe to define the aliases with older versions of Symfony as
the aliases are the last argument to ``createXmlMappingDriver`` and
are ignored by PHP if that argument doesn't exist.

In your bundle class, write the following code to register the compiler pass.
This one is written for the FOSUserBundle, so parts of it will need to
This one is written for the CmfRoutingBundle, so parts of it will need to
be adapted for your case::

use Doctrine\Bundle\DoctrineBundle\DependencyInjection\Compiler\DoctrineOrmMappingsPass;
use Doctrine\Bundle\MongoDBBundle\DependencyInjection\Compiler\DoctrineMongoDBMappingsPass;
use Doctrine\Bundle\CouchDBBundle\DependencyInjection\Compiler\DoctrineCouchDBMappingsPass;
use Doctrine\Bundle\PHPCRBundle\DependencyInjection\Compiler\DoctrinePhpcrMappingsPass;

class FOSUserBundle extends Bundle
class CmfRoutingBundle extends Bundle
{
public function build(ContainerBuilder $container)
{
Expand All @@ -47,16 +47,17 @@ be adapted for your case::

$modelDir = realpath(__DIR__.'/Resources/config/doctrine/model');
$mappings = array(
$modelDir => 'FOS\UserBundle\Model',
$modelDir => 'Symfony\Cmf\RoutingBundle\Model',
);

$ormCompilerClass = 'Doctrine\Bundle\DoctrineBundle\DependencyInjection\Compiler\DoctrineOrmMappingsPass';
if (class_exists($ormCompilerClass)) {
$container->addCompilerPass(
DoctrineOrmMappingsPass::createXmlMappingDriver(
$mappings,
array('fos_user.model_manager_name'),
'fos_user.backend_type_orm'
array('cmf_routing.model_manager_name'),
'cmf_routing.backend_type_orm',
array('CmfRoutingBundle' => 'Symfony\Cmf\RoutingBundle\Model')
));
}

Expand All @@ -65,8 +66,9 @@ be adapted for your case::
$container->addCompilerPass(
DoctrineMongoDBMappingsPass::createXmlMappingDriver(
$mappings,
array('fos_user.model_manager_name'),
'fos_user.backend_type_mongodb'
array('cmf_routing.model_manager_name'),
'cmf_routing.backend_type_mongodb',
array('CmfRoutingBundle' => 'Symfony\Cmf\RoutingBundle\Model')
));
}

Expand All @@ -75,8 +77,9 @@ be adapted for your case::
$container->addCompilerPass(
DoctrineCouchDBMappingsPass::createXmlMappingDriver(
$mappings,
array('fos_user.model_manager_name'),
'fos_user.backend_type_couchdb'
array('cmf_routing.model_manager_name'),
'cmf_routing.backend_type_couchdb',
array('CmfRoutingBundle' => 'Symfony\Cmf\RoutingBundle\Model')
));
}

Expand All @@ -85,8 +88,9 @@ be adapted for your case::
$container->addCompilerPass(
DoctrinePhpcrMappingsPass::createXmlMappingDriver(
$mappings,
array('fos_user.model_manager_name'),
'fos_user.backend_type_phpcr'
array('cmf_routing.model_manager_name'),
'cmf_routing.backend_type_phpcr',
array('CmfRoutingBundle' => 'Symfony\Cmf\RoutingBundle\Model')
));
}
}
Expand All @@ -99,17 +103,20 @@ decide which to use.
The compiler pass provides factory methods for all drivers provided by Doctrine:
Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:

* a map/hash of absolute directory path to namespace;
* an array of container parameters that your bundle uses to specify the name of
the Doctrine manager that it is using. In the above example, the FOSUserBundle
stores the manager name that's being used under the ``fos_user.model_manager_name``
* A map/hash of absolute directory path to namespace;
* An array of container parameters that your bundle uses to specify the name of
the Doctrine manager that it is using. In the example above, the CmfRoutingBundle
stores the manager name that's being used under the ``cmf_routing.model_manager_name``
parameter. The compiler pass will append the parameter Doctrine is using
to specify the name of the default manager. The first parameter found is
used and the mappings are registered with that manager;
* an optional container parameter name that will be used by the compiler
* An optional container parameter name that will be used by the compiler
pass to determine if this Doctrine type is used at all. This is relevant if
your user has more than one type of Doctrine bundle installed, but your
bundle is only used with one type of Doctrine.
bundle is only used with one type of Doctrine;
* A map/hash of aliases to namespace. This should be the same convention used
by Doctrine auto-mapping. In the example above, this allows the user to call
``$om->getRepository('CmfRoutingBundle:Route')``.

.. note::

Expand All @@ -120,7 +127,7 @@ Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:
of the class as their filename (e.g. ``BlogPost.orm.xml``)

If you also need to map a base class, you can register a compiler pass
with the ``DefaultFileLocator`` like this. This code is simply taken from the
with the ``DefaultFileLocator`` like this. This code is taken from the
``DoctrineOrmMappingsPass`` and adapted to use the ``DefaultFileLocator``
instead of the ``SymfonyFileLocator``::

Expand All @@ -138,6 +145,9 @@ Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:
);
}

Note that you do not need to provide a namespace alias unless your users are
expected to ask Doctrine for the base classes.

Now place your mapping file into ``/Resources/config/doctrine-base`` with the
fully qualified class name, separated by ``.`` instead of ``\``, for example
``Other.Namespace.Model.Name.orm.xml``. You may not mix the two as otherwise
Expand All @@ -146,4 +156,3 @@ Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:
Adjust accordingly for the other Doctrine implementations.

.. _`CouchDB Mapping Compiler Pass pull request`: https://github.com/doctrine/DoctrineCouchDBBundle/pull/27
.. _`FOSUserBundle mapping configuration`: https://github.com/FriendsOfSymfony/FOSUserBundle/blob/master/FOSUserBundle.php

0 comments on commit 79cb4f1

Please sign in to comment.