Skip to content

#DDC-2664 Document new Proxy factory flags usage as of DCOM-210 #782

Merged
merged 2 commits into from Sep 9, 2013

3 participants

@mnapoli
mnapoli commented Sep 9, 2013

#DDC-2664 - Document new Proxy factory flags usage as of DCOM-210

Please not I'm not an expert in RST so if you spot a syntax mistake let me know.

@doctrinebot

Hello,

thank you for creating this pull request. I have automatically opened an issue
on our Jira Bug Tracker for you. See the issue link:

http://www.doctrine-project.org/jira/browse/DDC-2665

We use Jira to track the state of pull requests and the versions they got
included in.

@Ocramius Ocramius and 1 other commented on an outdated diff Sep 9, 2013
docs/en/reference/advanced-configuration.rst
-recommended for a production environment. To eliminate the overhead
-of proxy class generation during runtime, set this configuration
-option to ``FALSE``. 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 like so:
+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
@Ocramius
Doctrine member
Ocramius added a note Sep 9, 2013

The code block is missing here... maybe it was $ ./doctrine orm:generate-proxies?

@mnapoli
mnapoli added a note Sep 9, 2013

yes the line was below, mixed up

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Ocramius Ocramius commented on an outdated diff Sep 9, 2013
docs/en/reference/advanced-configuration.rst
-The default value is ``TRUE`` for convenient development. However,
-this setting is not optimal for performance and therefore not
-recommended for a production environment. To eliminate the overhead
-of proxy class generation during runtime, set this configuration
-option to ``FALSE``. 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 like so:
+Possible values are:
@Ocramius
Doctrine member
Ocramius added a note Sep 9, 2013

Possible values for $mode are:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Ocramius Ocramius and 1 other commented on an outdated diff Sep 9, 2013
docs/en/reference/advanced-configuration.rst
-The default value is ``TRUE`` for convenient development. However,
-this setting is not optimal for performance and therefore not
-recommended for a production environment. To eliminate the overhead
-of proxy class generation during runtime, set this configuration
-option to ``FALSE``. 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 like so:
+Possible values are:
+
+- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_NEVER``
+
+Never autogenerate a proxy and rely that it was generated by some
@Ocramius
Doctrine member
Ocramius added a note Sep 9, 2013

there's a bit of mess in this sentence

@mnapoli
mnapoli added a note Sep 9, 2013

Yep, I copied the phpdoc but that's not good, will fix

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Ocramius Ocramius commented on an outdated diff Sep 9, 2013
docs/en/reference/advanced-configuration.rst
.. code-block:: php
+When you do this in a development environment,
@Ocramius
Doctrine member
Ocramius added a note Sep 9, 2013

It should probably be pointed out that the setting is mainly for production environments

@Ocramius
Doctrine member
Ocramius added a note Sep 9, 2013

Never mind, you did it in the last part of this document

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Ocramius Ocramius commented on an outdated diff Sep 9, 2013
docs/en/reference/advanced-configuration.rst
.. 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
@Ocramius
Doctrine member
Ocramius added a note Sep 9, 2013

Split the sentence - you're messing it up around or failing lazy-loads

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Ocramius Ocramius commented on an outdated diff Sep 9, 2013
docs/en/reference/advanced-configuration.rst
$ ./doctrine orm:generate-proxies
+- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_ALWAYS``
+
+Always generates a new proxy in every request.
@Ocramius
Doctrine member
Ocramius added a note Sep 9, 2013

(and writes it to disk)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Ocramius Ocramius commented on an outdated diff Sep 9, 2013
docs/en/reference/advanced-configuration.rst
$ ./doctrine orm:generate-proxies
+- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_ALWAYS``
+
+Always generates a new proxy in every request.
+
+- ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_FILE_NOT_EXISTS``
+
+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
@Ocramius
Doctrine member
Ocramius added a note Sep 9, 2013

Generate the proxy classes and evaluate them on the fly via eval(), avoiding ....

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@Ocramius
Doctrine member
Ocramius commented Sep 9, 2013

Except for some english language issues, :+1:!

@mnapoli
mnapoli commented Sep 9, 2013

I'm fixing up with your comments, note also that I mixed up: there are 2 parts talking about setAutoGenerateProxyClasses. I edited the second part that is in the "Development vs Production Configuration" chapter.

I am moving most of this to the first part: "Configuration Options > Auto-generating Proxy Classes (OPTIONAL)".

See http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/advanced-configuration.html

@mnapoli mnapoli commented on the diff Sep 9, 2013
docs/en/reference/advanced-configuration.rst
@@ -322,30 +361,27 @@ transparently initialize itself on first access.
Generating Proxy classes
~~~~~~~~~~~~~~~~~~~~~~~~
@mnapoli
mnapoli added a note Sep 9, 2013

FYI from here and below, it's the chapter about configuring for Production vs Development, I moved up everything that I previously wrote, and completely rewrote this part.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@mnapoli
mnapoli commented Sep 9, 2013

OK I fixed your suggestions, there's still one thing I don't know what to do.

It's the first code block of the page:

if ($applicationMode == "development") {
    $config->setAutoGenerateProxyClasses(true);
} else {
    $config->setAutoGenerateProxyClasses(false);
}

If I start throwing Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_NEVER… in the code I'm afraid it will be messy and confusing since there will be no explanation around about the constants and possible values.

Also, that would recommend a specific value for dev environment whereas there are 3 possible choices: is there an "official" recommended option? AUTOGENERATE_ALWAYS would be equivalent to the default of 2.3, but AUTOGENERATE_EVAL seems way more sensible since it's simpler and works fine as well.

@Ocramius
Doctrine member
Ocramius commented Sep 9, 2013

@mnapoli I think it's fine to have true or false for newcomers. I wouldn't change that part unless we deprecate boolean flags

@mnapoli
mnapoli commented Sep 9, 2013

OK fine by me

@Ocramius Ocramius merged commit 4d51a02 into doctrine:master Sep 9, 2013

1 check failed

Details default The Travis CI build failed
@mnapoli mnapoli deleted the mnapoli:patch-4 branch Sep 9, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.