DoctrineBundle配置信息("doctrine"根键)

3.4 版本
维护中的版本


完整的默认配置 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
doctrine:
    dbal:
        default_connection:   default
        types:
            # A collection of custom types / 一个自定义类型的集合
            # Example / 样例
            some_custom_type:
                class:                Acme\HelloBundle\MyCustomType
                commented:            true
        # If enabled all tables not prefixed with sf2_ will be ignored by the schema
        # tool. This is for custom tables which should not be altered automatically.
        # 如果开启的话,所有“前缀不是sf2_”的表将被schema工具所忽略。
        # 这是为自定义的表“不应被自动修改”而设。
        #schema_filter:        ^sf2_

        connections:
            # A collection of different named connections (e.g. default, conn2, etc)
            # 不同的“命名连接”集合(如,default, conn2,等等)
            default:
                dbname:               ~
                host:                 localhost
                port:                 ~
                user:                 root
                password:             ~
                charset:              ~
                path:                 ~
                memory:               ~
 
                # The unix socket to use for MySQL / 用于MySQL的unix socket
                unix_socket:          ~
 
                # True to use as persistent connection for the ibm_db2 driver
                # 设为ture即作为ibm_db2驱动的持久化连接
                persistent:           ~
 
                # The protocol to use for the ibm_db2 driver (default to TCPIP if omitted)
                # 用于ibm_db2驱动的protocol(若忽略此选项,默认是TCPIP)
                protocol:             ~
 
                # True to use dbname as service name instead of SID for Oracle
                # 设为true即可把Oracle的数据库名称作为服务名称,而不是用SID
                service:              ~
 
                # The session mode to use for the oci8 driver
                # 用于oci8驱动的session模式
                sessionMode:          ~
 
                # True to use a pooled server with the oci8 driver
                # 设为true即可和oci8驱动一起使用pooled server
                pooled:               ~
 
                # Configuring MultipleActiveResultSets for the pdo_sqlsrv driver
                # 为pdo_sqlsrv driver配置MultipleActiveResultSets 
                MultipleActiveResultSets:  ~
                driver:               pdo_mysql
                platform_service:     ~
 
                # the version of your database engine / 数据库引擎版本
                server_version:       ~
 
                # when true, queries are logged to a 'doctrine' monolog channel
                # 若设为true,查询日志将使用'doctrine' monolog channel
                logging:              "%kernel.debug%"
                profiling:            "%kernel.debug%"
                driver_class:         ~
                wrapper_class:        ~
                options:
                    # an array of options / 选项数组
                    key:                  []
                mapping_types:
                    # an array of mapping types / 映射类型的数组
                    name:                 []
                slaves:

                    # a collection of named slave connections (e.g. slave1, slave2)
                    # “命名从连接”的一个集合(如,slave1, slave2)
                    slave1:
                        dbname:               ~
                        host:                 localhost
                        port:                 ~
                        user:                 root
                        password:             ~
                        charset:              ~
                        path:                 ~
                        memory:               ~
 
                        # The unix socket to use for MySQL / 用于MySQL的unix socket
                        unix_socket:          ~
 
                        # True to use as persistent connection for the ibm_db2 driver
                        # 设为ture即作为ibm_db2驱动的持久化连接
                        persistent:           ~
 
                        # The protocol to use for the ibm_db2 driver (default to TCPIP if omitted)
                        # 设为ture即作为ibm_db2驱动的持久化连接
                        protocol:             ~
 
                        # True to use dbname as service name instead of SID for Oracle
                        # 设为true即可把Oracle的数据库名称作为服务名称,而不是用SID
                        service:              ~
 
                        # The session mode to use for the oci8 driver
                        # 用于oci8驱动的session模式
                        sessionMode:          ~
 
                        # True to use a pooled server with the oci8 driver
                        # 设为true即可和oci8驱动一起使用pooled server
                        pooled:               ~
 
                        # the version of your database engine / 数据库引擎版本
                        server_version:       ~
 
                        # Configuring MultipleActiveResultSets for the pdo_sqlsrv driver
                        # 为pdo_sqlsrv driver配置MultipleActiveResultSets 
                        MultipleActiveResultSets:  ~

    orm:
        default_entity_manager:  ~
        auto_generate_proxy_classes:  false
        proxy_dir:            "%kernel.cache_dir%/doctrine/orm/Proxies"
        proxy_namespace:      Proxies
        # search for the "ResolveTargetEntityListener" class for an article about this
        # 搜索一篇名为"ResolveTargetEntityListener"的文章以了解此项
        resolve_target_entities: []
        entity_managers:
            # A collection of different named entity managers (e.g. some_em, another_em)
            # 被命名的不同entity managers(实体管理器,如,some_em, another_em)之集合
            some_em:
                query_cache_driver:
                    type:                 array # Required / 必填项
                    host:                 ~
                    port:                 ~
                    instance_class:       ~
                    class:                ~
                metadata_cache_driver:
                    type:                 array # Required / 必填项
                    host:                 ~
                    port:                 ~
                    instance_class:       ~
                    class:                ~
                result_cache_driver:
                    type:                 array # Required / 必填项
                    host:                 ~
                    port:                 ~
                    instance_class:       ~
                    class:                ~
                connection:           ~
                class_metadata_factory_name:  Doctrine\ORM\Mapping\ClassMetadataFactory
                default_repository_class:  Doctrine\ORM\EntityRepository
                auto_mapping:         false
                hydrators:

                    # An array of hydrator names / 水合器(译注:doctrine专业术语)名称的数组
                    hydrator_name:                 []
                mappings:
                    # An array of mappings, which may be a bundle name or something else
                    # 一个映射数组,可以是bundle名称或是其他什么
                    mapping_name:
                        mapping:              true
                        type:                 ~
                        dir:                  ~
                        alias:                ~
                        prefix:               ~
                        is_bundle:            ~
                dql:
                    # a collection of string functions / 一个字符串函数的集合
                    string_functions:
                        # example / 样例
                        # test_string: Acme\HelloBundle\DQL\StringFunction
 
                    # a collection of numeric functions / 一个数字函数的集合
                    numeric_functions:
                        # example / 样例
                        # test_numeric: Acme\HelloBundle\DQL\NumericFunction
 
                    # a collection of datetime functions / 一个日期函数的集合
                    datetime_functions:
                        # example / 样例
                        # test_datetime: Acme\HelloBundle\DQL\DatetimeFunction
 
                # Register SQL Filters in the entity manager
                # 在entity manager中注册SQL过滤器
                filters:
                    # An array of filters / 一个filters的数组
                    some_filter:
                        class:                ~ # Required / 必填项
                        enabled:              false
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/doctrine
        http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
    <doctrine:config>
        <doctrine:dbal default-connection="default">
            <doctrine:connection
                name="default"
                dbname="database"
                host="localhost"
                port="1234"
                user="user"
                password="secret"
                driver="pdo_mysql"
                driver-class="MyNamespace\MyDriverImpl"
                path="%kernel.data_dir%/data.sqlite"
                memory="true"
                unix-socket="/tmp/mysql.sock"
                wrapper-class="MyDoctrineDbalConnectionWrapper"
                charset="UTF8"
                logging="%kernel.debug%"
                platform-service="MyOwnDatabasePlatformService"
                server-version="5.6"
            >
                <doctrine:option key="foo">bar</doctrine:option>
                <doctrine:mapping-type name="enum">string</doctrine:mapping-type>
            </doctrine:connection>
            <doctrine:connection name="conn1" />
            <doctrine:type name="custom">Acme\HelloBundle\MyCustomType</doctrine:type>
        </doctrine:dbal>
 
        <doctrine:orm
            default-entity-manager="default"
            auto-generate-proxy-classes="false"
            proxy-namespace="Proxies"
            proxy-dir="%kernel.cache_dir%/doctrine/orm/Proxies"
        >
            <doctrine:entity-manager
                name="default"
                query-cache-driver="array"
                result-cache-driver="array"
                connection="conn1"
                class-metadata-factory-name="Doctrine\ORM\Mapping\ClassMetadataFactory"
            >
                <doctrine:metadata-cache-driver
                    type="memcache"
                    host="localhost"
                    port="11211"
                    instance-class="Memcache"
                    class="Doctrine\Common\Cache\MemcacheCache"
                />
 
                <doctrine:mapping name="AcmeHelloBundle" />
 
                <doctrine:dql>
                    <doctrine:string-function name="test_string">
                        Acme\HelloBundle\DQL\StringFunction
                    </doctrine:string-function>
 
                    <doctrine:numeric-function name="test_numeric">
                        Acme\HelloBundle\DQL\NumericFunction
                    </doctrine:numeric-function>
 
                    <doctrine:datetime-function name="test_datetime">
                        Acme\HelloBundle\DQL\DatetimeFunction
                    </doctrine:datetime-function>
                </doctrine:dql>
            </doctrine:entity-manager>
 
            <doctrine:entity-manager name="em2" connection="conn2" metadata-cache-driver="apc">
                <doctrine:mapping
                    name="DoctrineExtensions"
                    type="xml"
                    dir="%kernel.root_dir%/../vendor/gedmo/doctrine-extensions/lib/DoctrineExtensions/Entity"
                    prefix="DoctrineExtensions\Entity"
                    alias="DExt"
                />
            </doctrine:entity-manager>
        </doctrine:orm>
    </doctrine:config>
</container>

配置概要 

下列配置样例展示了ORM所需要解析的全部默认配置:

1
2
3
4
5
6
7
8
9
10
11
12
doctrine:
    orm:
        auto_mapping: true
        # the standard distribution overrides this to be true in debug, false otherwise
        # Symfony标准分发包在debug开启时覆写了此项为true,否则是false
        auto_generate_proxy_classes: false
        proxy_namespace: Proxies
        proxy_dir: "%kernel.cache_dir%/doctrine/orm/Proxies"
        default_entity_manager: default
        metadata_cache_driver: array
        query_cache_driver: array
        result_cache_driver: array

在覆写特定的类时,你还可以使用很多其他配置选项,但那此都是为了“非常高端”的使用场合而准备的。

缓存驱动 

对于缓存驱动,你可以指定其选项值:array, apc, memcache, memcached, redis, wincache, zenddata, xcache 或是 service

下例展示了缓存配置的概况:

1
2
3
4
5
6
7
8
9
10
11
12
doctrine:
    orm:
        auto_mapping: true
        metadata_cache_driver: apc
        query_cache_driver:
            type: service
            id: my_doctrine_common_cache_service
        result_cache_driver:
            type: memcache
            host: localhost
            port: 11211
            instance_class: Memcache

与映射相关的配置 

所有被映射entity的“显示定义”,是ORM的唯一必要配置,对于它们的若干些选项你可以进行控制。下列配置选项因mapping(映射)而存在:

type 

annotation, xml, yml, phpstaticphp中的一种。本选项指定的是,你的映射关系所使用的是何种metadata类型。

dir 

映射或entity文件的路径(根据驱动的不同)。如果路径是相对的,它被假设为相对于bundle根目录。此时仅在你的映射名称是一个bundle名称时才能运行。如果你需要使用此选项来指定绝对路径,你应该对路径加上DIC中的kernel参数来作为前缀(如%kernel.root_dir%)。

prefix 

一个普通的命名空间可以作为这个映射(mapping)下面全部entity的前缀。前缀不可以与其他已定义的映射发生冲突,否则你的entity就不能被Doctrine找到。本选项的默认值是bundle的命名空间 + Entity,例如,对于程序中的一名为AcmeHelloBundle的bundle来说,前缀应该是:Acme\HelloBundle\Entity

alias 

Doctrine提供种对entity命名空间施以假名(alias)的方式,以求简化并缩短“使用在DQL查询中”或是“访问Repository时”的(entity)名称。当使用bundle时,默认的假名就是bundle名字。

is_bundle 

本选项是dir的衍生值,默认被设为true,如果用file_exists()检查dir时返回的是false的话。如果“存在性”的检查返回true,那么它的值是false。本例中,指定了一个绝对路径,metadata文件所在的目录是在bundle之外。

Doctrine DBAL配置 

DoctrineBundle支持默认的Doctrine驱动所支持的全部参数,并将其转换为Symofny强制要求的XML或YAML命名标准。参考DBAL文档以了解更多。下面码段展示了所有可能的配置选项:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
doctrine:
    dbal:
        dbname:               database
        host:                 localhost
        port:                 1234
        user:                 user
        password:             secret
        driver:               pdo_mysql
        # the DBAL driverClass option / DBAL driverClass的选项
        driver_class:         MyNamespace\MyDriverImpl
        # the DBAL driverOptions option / DBAL driverOptions的选项
        options:
            foo: bar
        path:                 "%kernel.data_dir%/data.sqlite"
        memory:               true
        unix_socket:          /tmp/mysql.sock
        # the DBAL wrapperClass option / DBAL wrapperClass的选项
        wrapper_class:        MyDoctrineDbalConnectionWrapper
        charset:              UTF8
        logging:              "%kernel.debug%"
        platform_service:     MyOwnDatabasePlatformService
        server_version:       5.6
        mapping_types:
            enum: string
        types:
            custom: Acme\HelloBundle\MyCustomType
        # the DBAL keepSlave option / DBAL keepSlave的选项
        keep_slave:           false
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/doctrine
        http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd"
>
 
    <doctrine:config>
        <doctrine:dbal
            name="default"
            dbname="database"
            host="localhost"
            port="1234"
            user="user"
            password="secret"
            driver="pdo_mysql"
            driver-class="MyNamespace\MyDriverImpl"
            path="%kernel.data_dir%/data.sqlite"
            memory="true"
            unix-socket="/tmp/mysql.sock"
            wrapper-class="MyDoctrineDbalConnectionWrapper"
            charset="UTF8"
            logging="%kernel.debug%"
            platform-service="MyOwnDatabasePlatformService"
            server-version="5.6">
 
            <doctrine:option key="foo">bar</doctrine:option>
            <doctrine:mapping-type name="enum">string</doctrine:mapping-type>
            <doctrine:type name="custom">Acme\HelloBundle\MyCustomType</doctrine:type>
        </doctrine:dbal>
    </doctrine:config>
</container>

server_version选项自Doctrine 2.5开始被添加进来,在DoctrineBundle 1.3中开始使用。该选项的值应该匹配你的数据库的server版本(使用postgres -Vpsql -V来查看你的PostgresSQL版本,使用mysql -V可以得到MySQL版本)。

如果你还没有创建数据库并且没有定义此选项,你可能会得到一个PDOException错误,因为Doctrine将自动地尝试猜出你的数据库server版本,却没有可用的。

如果你要在YAML中配置多个数据库连接(multiple connections),把它们放到connections键下面,并给予其唯一的名称(unique name):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
doctrine:
    dbal:
        default_connection:       default
        connections:
            default:
                dbname:           Symfony
                user:             root
                password:         null
                host:             localhost
                server_version:   5.6
            customer:
                dbname:           customer
                user:             root
                password:         null
                host:             localhost
                server_version:   5.7

database_connection服务始终引用默认 的连接,也就是第一个被定义的,或者是通过default_connection键定义的。

每个连接都可以通过doctrine.dbal.[name]_connection服务来访问,其中的[name]就是连接的名称(the name of connection)。

简化配置的语法 

当你只使用一个entity manager时,所有可用的配置选项可以直接置于配置文件中的doctrine.orm层级之下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
doctrine:
    orm:
        # ...
        query_cache_driver:
           # ...
        metadata_cache_driver:
            # ...
        result_cache_driver:
            # ...
        connection: ~
        class_metadata_factory_name:  Doctrine\ORM\Mapping\ClassMetadataFactory
        default_repository_class:  Doctrine\ORM\EntityRepository
        auto_mapping: false
        hydrators:
            # ...
        mappings:
            # ...
        dql:
            # ...

这个简化版本通常被使用在别的文档片断中。要注意的是,你不能同时使用两种语法(在一个配置文件中)。

在Bundle中自定义entity映射 

Doctrine的auto_mapping功能从每一个bundle的Entity/目录中加载annotation配置信息 并且Resources/config/doctrine目录中寻找其他格式(的配置信息,比如,YAML, XML)。

如果你把metadata存放在bundle中的其他某处,你可以定义自己的mappings(映射),告诉Doctrine到底去哪里 找到它们连同其他一些配置信息。

如果你使用了auto_mapping配置选项,即可随需覆写配置。在本例中,与“映射”相关的配置的键(key)必须对应bundle的名称,这很重要。

例如,假设,你决定把你的AppBundle中的XML格式的entity配置信息放到@AppBundle/SomeResources/config/doctrine目录:

1
2
3
4
5
6
7
8
9
10
doctrine:
    # ...
    orm:
        # ...
        auto_mapping: true
        mappings:
            # ...
            AppBundle:
                type: xml
                dir: SomeResources/config/doctrine
1
2
3
4
5
6
7
8
9
10
<?xml version="1.0" charset="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
 
    <doctrine:config>
        <doctrine:orm auto-mapping="true">
            <mapping name="AppBundle" dir="SomeResources/config/doctrine" type="xml" />
        </doctrine:orm>
    </doctrine:config>
</container>
1
2
3
4
5
6
7
8
$container->loadFromExtension('doctrine', array(
    'orm' => array(
        'auto_mapping' => true,
        'mappings' => array(
            'AppBundle' => array('dir' => 'SomeResources/config/doctrine', 'type' => 'xml'),
        ),
    ),
));

在Bundle之外映射entity 

你也可以创建新的映射,例如,在Symfony文件夹之外。

例如,下面的配置会在src/Entity目录中的App\Entity命名空间下来寻找entity类,并且给它们一个App假名(以便你能够使用App:Post这种写法):

1
2
3
4
5
6
7
8
9
10
11
12
doctrine:
        # ...
        orm:
            # ...
            mappings:
                # ...
                SomeEntityNamespace:
                    type: annotation
                    dir: "%kernel.root_dir%/../src/Entity"
                    is_bundle: false
                    prefix: App\Entity
                    alias: App
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<?xml version="1.0" charset="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
 
    <doctrine:config>
        <doctrine:orm>
            <mapping name="SomeEntityNamespace"
                type="annotation"
                dir="%kernel.root_dir%/../src/Entity"
                is-bundle="false"
                prefix="App\Entity"
                alias="App"
            />
        </doctrine:orm>
    </doctrine:config>
</container>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
$container->loadFromExtension('doctrine', array(
    'orm' => array(
        'auto_mapping' => true,
        'mappings' => array(
            'SomeEntityNamespace' => array(
                'type'      => 'annotation',
                'dir'       => '%kernel.root_dir%/../src/Entity',
                'is_bundle' => false,
                'prefix'    => 'App\Entity',
                'alias'     => 'App',
            ),
        ),
    ),
));

探测出映射的配置格式 

如果bundle配置中的type选项没有被配置,DoctrineBundle将尝试为bundle探测出正确的映射配置格式信息(mapping configuration format)。

DoctrineBundle将在你的映射中已配置好的dir中,寻找匹配*.orm.[FORMAT]的文件(如Post.orm.yml)(如果你映射了一个bundle,则dir是相对于该bundle的目录的)。

该bundle(按此顺序)寻找XML、YAML和PHP文件。使用auto_mapping功能时,每个bundle只能有唯一的一个配置格式。该bundle只要锁定文件即停止找寻。

如果没有可能决定一个bundle的配置文件格式,DoctrineBundle将检查是否有一个Entity文件夹存在于该bundle的根目录下。如果有,Doctrine就将回滚,使用一个annotaion驱动(来读取里面的entity的metadata)。

Dir的默认值 

如果dir选项未被指定,默认值将取决于使用的是何种配置驱动。对于那些依赖于PHP文件的驱动(annotation, staticphp),其取值为[Bundle]/Entity。对于使用了配置文件的驱动(XML, YAML,...),取值为[Bundle]/Resources/config/doctrine

如果dir选项有被设置,并且is_bundle选项被设为true,DoctrineBundle将对dir的取值施以“bundle路径”的前缀。

本文,包括例程代码在内,采用的是 Creative Commons BY-SA 3.0 创作共用授权。

登录symfonychina 发表评论或留下问题(我们会尽量回复)