From 26e1ac6afd6f0d3ac9c2ade644a015d04afd94bf Mon Sep 17 00:00:00 2001 From: Matthieu Napoli Date: Mon, 9 Sep 2013 11:20:12 +0200 Subject: [PATCH] #DDC-2664 Improving and fixing documentation for new Proxy factory flags usage as of DCOM-210 --- docs/en/reference/advanced-configuration.rst | 109 ++++++++++--------- 1 file changed, 59 insertions(+), 50 deletions(-) diff --git a/docs/en/reference/advanced-configuration.rst b/docs/en/reference/advanced-configuration.rst index c1b96294b..be127ce0a 100644 --- a/docs/en/reference/advanced-configuration.rst +++ b/docs/en/reference/advanced-configuration.rst @@ -210,17 +210,56 @@ implementation that logs to the standard output using ``echo`` and Auto-generating Proxy Classes (***OPTIONAL***) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Proxy classes can either be generated manually through the Doctrine +Console or automatically at runtime by Doctrine. The configuration +option that controls this behavior is: + .. code-block:: php setAutoGenerateProxyClasses($bool); - $config->getAutoGenerateProxyClasses(); + $config->setAutoGenerateProxyClasses($mode); -Gets or sets whether proxy classes should be generated -automatically at runtime by Doctrine. If set to ``FALSE``, proxy -classes must be generated manually through the doctrine command -line task ``generate-proxies``. The strongly recommended value for -a production environment is ``FALSE``. +Possible values for ``$mode`` are: + +- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_NEVER`` + +Never autogenerate a proxy. You will need to generate the proxies +manually, for this use the Doctrine Console like so: + +.. code-block:: php + + $ ./doctrine orm:generate-proxies + +When you do this in a development environment, +be aware that you may get class/file not found errors if certain proxies +are not yet generated. You may also get failing lazy-loads if new +methods were added to the entity class that are not yet in the proxy class. +In such a case, simply use the Doctrine Console to (re)generate the +proxy classes. + +- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_ALWAYS`` + +Always generates a new proxy in every request and writes it to disk. + +- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_FILE_NOT_EXISTS`` + +Generate the proxy class when the proxy file does not exist. +This strategy causes a file exists call whenever any proxy is +used the first time in a request. + +- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_EVAL`` + +Generate the proxy classes and evaluate them on the fly via eval(), +avoiding writing the proxies to disk. +This strategy is only sane for development. + +In a production environment, it is highly recommended to use +AUTOGENERATE_NEVER to allow for optimal performances. The other +options are interesting in development environment. + +Before v2.4, ``setAutoGenerateProxyClasses`` would accept a boolean +value. This is still possible, ``FALSE`` being equivalent to +AUTOGENERATE_NEVER and ``TRUE`` to AUTOGENERATE_ALWAYS. Development vs Production Configuration --------------------------------------- @@ -322,57 +361,27 @@ transparently initialize itself on first access. Generating Proxy classes ~~~~~~~~~~~~~~~~~~~~~~~~ -Proxy classes can either be generated manually through the Doctrine -Console or automatically by Doctrine. The configuration option that -controls this behavior is: +In a production environment, it is highly recommended to use +``AUTOGENERATE_NEVER`` to allow for optimal performances. +However you will be required to generate the proxies manually +using the Doctrine Console: .. code-block:: php - setAutoGenerateProxyClasses($mode); - -Possible values are: - -- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_NEVER`` - -Never autogenerate a proxy and rely that it was generated by some -process before deployment. - -To generate the proxies, use: - -.. code-block:: php - -When you do this in a development environment, -note that you may get class/file not found errors if certain proxy -classes are not available or failing lazy-loads if new methods were -added to the entity class that are not yet in the proxy class. -In such a case, simply use the Doctrine Console to (re)generate the -proxy classes. - $ ./doctrine orm:generate-proxies -- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_ALWAYS`` +The other options are interesting in development environment: -Always generates a new proxy in every request. +- ``AUTOGENERATE_ALWAYS`` will require you to create and configure +a proxy directory. Proxies will be generated and written to file +on each request, so any modification to your code will be acknowledged. -- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_FILE_NOT_EXISTS`` +- ``AUTOGENERATE_FILE_NOT_EXISTS`` will not overwrite an existing +proxy file. If your code changes, you will need to regenerate the +proxies manually. -Autogenerate the proxy class when the proxy file does not exist. -This strategy causes a file exists call whenever any proxy is -used the first time in a request. - -- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_EVAL`` - -Generate the proxy classes using eval(), which avoids writing the -proxies to disk. This strategy is only sane for development. - -In a production environment, it is highly recommended to use -AUTOGENERATE_NEVER to allow for optimal performances. The other -options are interesting in development environment. - -Before v2.4, ``setAutoGenerateProxyClasses`` would accept a boolean -value. This is still possible, ``FALSE`` being equivalent to -AUTOGENERATE_NEVER and ``TRUE`` to AUTOGENERATE_ALWAYS. +- ``AUTOGENERATE_EVAL`` will regenerate each proxy on each request, +but without writing them to disk. Autoloading Proxies -------------------