From 42e83a2716d19eada4f1cd49ece77d5f5229a239 Mon Sep 17 00:00:00 2001 From: Benjamin Morel Date: Thu, 13 Dec 2012 10:28:55 +0000 Subject: [PATCH] Fixed documentation for ORM\Proxy --- lib/Doctrine/ORM/Proxy/Autoloader.php | 17 +++-- lib/Doctrine/ORM/Proxy/Proxy.php | 4 +- lib/Doctrine/ORM/Proxy/ProxyException.php | 31 +++++++-- lib/Doctrine/ORM/Proxy/ProxyFactory.php | 82 ++++++++++++++++------- 4 files changed, 93 insertions(+), 41 deletions(-) diff --git a/lib/Doctrine/ORM/Proxy/Autoloader.php b/lib/Doctrine/ORM/Proxy/Autoloader.php index 0b4d9a019..b79719388 100644 --- a/lib/Doctrine/ORM/Proxy/Autoloader.php +++ b/lib/Doctrine/ORM/Proxy/Autoloader.php @@ -27,7 +27,7 @@ namespace Doctrine\ORM\Proxy; class Autoloader { /** - * Resolve proxy class name to a filename based on the following pattern. + * Resolves proxy class name to a filename based on the following pattern. * * 1. Remove Proxy namespace from class name * 2. Remove namespace seperators from remaining class name. @@ -36,7 +36,10 @@ class Autoloader * @param string $proxyDir * @param string $proxyNamespace * @param string $className + * * @return string + * + * @throws ProxyException */ static public function resolveFile($proxyDir, $proxyNamespace, $className) { @@ -49,13 +52,14 @@ class Autoloader } /** - * Register and return autoloader callback for the given proxy dir and + * Registers and returns autoloader callback for the given proxy dir and * namespace. * - * @param string $proxyDir - * @param string $proxyNamespace - * @param Closure $notFoundCallback Invoked when the proxy file is not found. - * @return Closure + * @param string $proxyDir + * @param string $proxyNamespace + * @param \Closure $notFoundCallback Invoked when the proxy file is not found. + * + * @return \Closure */ static public function register($proxyDir, $proxyNamespace, \Closure $notFoundCallback = null) { @@ -75,4 +79,3 @@ class Autoloader return $autoloader; } } - diff --git a/lib/Doctrine/ORM/Proxy/Proxy.php b/lib/Doctrine/ORM/Proxy/Proxy.php index 47cda9027..ed588af6d 100644 --- a/lib/Doctrine/ORM/Proxy/Proxy.php +++ b/lib/Doctrine/ORM/Proxy/Proxy.php @@ -27,4 +27,6 @@ use Doctrine\Common\Persistence\Proxy as BaseProxy; * @author Roman Borschel * @since 2.0 */ -interface Proxy extends BaseProxy {} +interface Proxy extends BaseProxy +{ +} diff --git a/lib/Doctrine/ORM/Proxy/ProxyException.php b/lib/Doctrine/ORM/Proxy/ProxyException.php index 4e26d8662..7f28a20e0 100644 --- a/lib/Doctrine/ORM/Proxy/ProxyException.php +++ b/lib/Doctrine/ORM/Proxy/ProxyException.php @@ -20,27 +20,45 @@ namespace Doctrine\ORM\Proxy; /** - * ORM Proxy Exception + * ORM Proxy Exception. * * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @link www.doctrine-project.com * @since 1.0 * @author Benjamin Eberlei */ -class ProxyException extends \Doctrine\ORM\ORMException { - - public static function proxyDirectoryRequired() { +class ProxyException extends \Doctrine\ORM\ORMException +{ + /** + * @return ProxyException + */ + public static function proxyDirectoryRequired() + { return new self("You must configure a proxy directory. See docs for details"); } - public static function proxyDirectoryNotWritable() { + /** + * @return ProxyException + */ + public static function proxyDirectoryNotWritable() + { return new self("Your proxy directory must be writable."); } - public static function proxyNamespaceRequired() { + /** + * @return ProxyException + */ + public static function proxyNamespaceRequired() + { return new self("You must configure a proxy namespace. See docs for details"); } + /** + * @param $className + * @param $proxyNamespace + * + * @return ProxyException + */ public static function notProxyClass($className, $proxyNamespace) { return new self(sprintf( @@ -48,5 +66,4 @@ class ProxyException extends \Doctrine\ORM\ORMException { $className, $proxyNamespace )); } - } diff --git a/lib/Doctrine/ORM/Proxy/ProxyFactory.php b/lib/Doctrine/ORM/Proxy/ProxyFactory.php index 7000dae0b..47dd2c28c 100644 --- a/lib/Doctrine/ORM/Proxy/ProxyFactory.php +++ b/lib/Doctrine/ORM/Proxy/ProxyFactory.php @@ -32,13 +32,32 @@ use Doctrine\Common\Util\ClassUtils; */ class ProxyFactory { - /** The EntityManager this factory is bound to. */ + /** + * The EntityManager this factory is bound to. + * + * @var \Doctrine\ORM\EntityManager + */ private $_em; - /** Whether to automatically (re)generate proxy classes. */ + + /** + * Whether to automatically (re)generate proxy classes. + * + * @var bool + */ private $_autoGenerate; - /** The namespace that contains all proxy classes. */ + + /** + * The namespace that contains all proxy classes. + * + * @var string + */ private $_proxyNamespace; - /** The directory that contains all proxy classes. */ + + /** + * The directory that contains all proxy classes. + * + * @var string + */ private $_proxyDir; /** @@ -53,10 +72,12 @@ class ProxyFactory * Initializes a new instance of the ProxyFactory class that is * connected to the given EntityManager. * - * @param EntityManager $em The EntityManager the new factory works for. - * @param string $proxyDir The directory to use for the proxy classes. It must exist. - * @param string $proxyNs The namespace to use for the proxy classes. - * @param boolean $autoGenerate Whether to automatically generate proxy classes. + * @param EntityManager $em The EntityManager the new factory works for. + * @param string $proxyDir The directory to use for the proxy classes. It must exist. + * @param string $proxyNs The namespace to use for the proxy classes. + * @param boolean $autoGenerate Whether to automatically generate proxy classes. + * + * @throws ProxyException */ public function __construct(EntityManager $em, $proxyDir, $proxyNs, $autoGenerate = false) { @@ -77,7 +98,8 @@ class ProxyFactory * the given identifier. * * @param string $className - * @param mixed $identifier + * @param mixed $identifier + * * @return object */ public function getProxy($className, $identifier) @@ -98,12 +120,12 @@ class ProxyFactory } /** - * Generate the Proxy file name + * Generates the Proxy file name. * - * @param string $className - * @param string $baseDir Optional base directory for proxy file name generation. - * If not specified, the directory configured on the Configuration of the - * EntityManager will be used by this factory. + * @param string $className + * @param string|null $baseDir Optional base directory for proxy file name generation. + * If not specified, the directory configured on the Configuration of the + * EntityManager will be used by this factory. * @return string */ private function getProxyFileName($className, $baseDir = null) @@ -116,10 +138,11 @@ class ProxyFactory /** * Generates proxy classes for all given classes. * - * @param array $classes The classes (ClassMetadata instances) for which to generate proxies. - * @param string $toDir The target directory of the proxy classes. If not specified, the - * directory configured on the Configuration of the EntityManager used - * by this factory is used. + * @param array $classes The classes (ClassMetadata instances) for which to generate proxies. + * @param string|null $toDir The target directory of the proxy classes. If not specified, the + * directory configured on the Configuration of the EntityManager used + * by this factory is used. + * * @return int Number of generated proxies. */ public function generateProxyClasses(array $classes, $toDir = null) @@ -146,9 +169,13 @@ class ProxyFactory /** * Generates a proxy class file. * - * @param ClassMetadata $class Metadata for the original class - * @param string $fileName Filename (full path) for the generated class - * @param string $file The proxy class template data + * @param ClassMetadata $class Metadata for the original class. + * @param string $fileName Filename (full path) for the generated class. + * @param string $file The proxy class template data. + * + * @return void + * + * @throws ProxyException */ private function _generateProxyClass(ClassMetadata $class, $fileName, $file) { @@ -198,6 +225,7 @@ class ProxyFactory * Generates the methods of a proxy class. * * @param ClassMetadata $class + * * @return string The code of the generated methods. */ private function _generateMethods(ClassMetadata $class) @@ -206,7 +234,7 @@ class ProxyFactory $methodNames = array(); foreach ($class->reflClass->getMethods() as $method) { - /* @var $method ReflectionMethod */ + /* @var $method \ReflectionMethod */ if ($method->isConstructor() || in_array(strtolower($method->getName()), array("__sleep", "__clone")) || isset($methodNames[$method->getName()])) { continue; } @@ -269,7 +297,7 @@ class ProxyFactory } /** - * Check if the method is a short identifier getter. + * Checks if the method is a short identifier getter. * * What does this mean? For proxy objects the identifier is already known, * however accessing the getter for this identifier usually triggers the @@ -277,8 +305,9 @@ class ProxyFactory * ID is interesting for the userland code (for example in views that * generate links to the entity, but do not display anything else). * - * @param ReflectionMethod $method - * @param ClassMetadata $class + * @param \ReflectionMethod $method + * @param ClassMetadata $class + * * @return bool */ private function isShortIdentifierGetter($method, ClassMetadata $class) @@ -309,7 +338,8 @@ class ProxyFactory /** * Generates the code for the __sleep method for a proxy class. * - * @param $class + * @param ClassMetadata $class + * * @return string */ private function _generateSleep(ClassMetadata $class)