Merge pull request php-annotations#102 from benesch/trait-docblocks

Trait docblocks

Author: Alexander Obuhovich

src/annotations/AnnotationFile.php

@@ -59,6 +59,11 @@ class AnnotationFile
      */
     public $uses;
 
+    /**
+     * @var string[] $traitMethodOverrides hash mapping FQCN to a hash mapping aliased method names to (trait, original method name)
+     */
+    public $traitMethodOverrides;
+
     /**
      * @param string $path absolute path to php source-file
      * @param array $data annotation data (as provided by AnnotationParser)
@@ -69,6 +74,25 @@ public function __construct($path, array $data)
         $this->data = $data;
         $this->namespace = $data['#namespace'];
         $this->uses = $data['#uses'];
+
+        if (isset($data['#traitMethodOverrides'])) {
+            foreach ($data['#traitMethodOverrides'] as $class => $methods) {
+                $this->traitMethodOverrides[$class] = array_map(array($this, 'resolveMethod'), $methods);
+            }
+        }
+    }
+
+    /**
+     * Qualify the class name in a method reference like 'Class::method'.
+     *
+     * @param string $raw_method Raw method string.
+     *
+     * @return string[] of fully-qualified class name, method name
+     */
+    public function resolveMethod($raw_method)
+    {
+        list($class, $method) = explode('::', $raw_method, 2);
+        return array(ltrim($this->resolveType($class), '\\'), $method);
     }
 
     /**

src/annotations/AnnotationManager.php

@@ -134,6 +134,11 @@ class AnnotationManager
      */
     private $_cacheSeed = '';
 
+    /**
+     * Whether this version of PHP has support for traits.
+     */
+    private $_traitsSupported;
+
     /**
      * Initialize the Annotation Manager
      *
@@ -145,6 +150,7 @@ public function __construct($cacheSeed = '')
         $this->_usageAnnotation = new UsageAnnotation();
         $this->_usageAnnotation->class = true;
         $this->_usageAnnotation->inherited = true;
+        $this->_traitsSupported = version_compare(PHP_VERSION, '5.4.0', '>=');
     }
 
     /**
@@ -262,34 +268,52 @@ protected function getAnnotations($class_name, $member_type = self::MEMBER_CLASS
 
             $inherit = true; // inherit parent annotations unless directed not to
 
-            if (isset($file) && isset($file->data[$key])) {
-                foreach ($file->data[$key] as $spec) {
-                    $name = $spec['#name']; // currently unused
-                    $type = $spec['#type'];
+            if (isset($file)) {
+                if (isset($file->data[$key])) {
+                    foreach ($file->data[$key] as $spec) {
+                        $name = $spec['#name']; // currently unused
+                        $type = $spec['#type'];
 
-                    unset($spec['#name'], $spec['#type']);
+                        unset($spec['#name'], $spec['#type']);
 
-                    if (!class_exists($type, $this->autoload)) {
-                        throw new AnnotationException("Annotation type '{$type}' does not exist");
-                    }
+                        if (!class_exists($type, $this->autoload)) {
+                            throw new AnnotationException("Annotation type '{$type}' does not exist");
+                        }
 
-                    $annotation = new $type;
+                        $annotation = new $type;
 
-                    if (!($annotation instanceof IAnnotation)) {
-                        throw new AnnotationException("Annotation type '{$type}' does not implement the mandatory IAnnotation interface");
-                    }
+                        if (!($annotation instanceof IAnnotation)) {
+                            throw new AnnotationException("Annotation type '{$type}' does not implement the mandatory IAnnotation interface");
+                        }
 
-                    if ($annotation instanceof IAnnotationFileAware) {
-                        $annotation->setAnnotationFile($file);
-                    }
+                        if ($annotation instanceof IAnnotationFileAware) {
+                            $annotation->setAnnotationFile($file);
+                        }
 
-                    $annotation->initAnnotation($spec);
+                        $annotation->initAnnotation($spec);
 
-                    $annotations[] = $annotation;
-                }
+                        $annotations[] = $annotation;
+                    }
+
+                    if ($member_type === self::MEMBER_CLASS) {
+                        $classAnnotations = $annotations;
+                    }
+                } else if ($this->_traitsSupported && $member_name !== null) {
+                    $traitAnnotations = array();
+
+                    if (isset($file->traitMethodOverrides[$class_name][$member_name])) {
+                        list($traitName, $originalMemberName) = $file->traitMethodOverrides[$class_name][$member_name];
+                        $traitAnnotations = $this->getAnnotations($traitName, $member_type, $originalMemberName);
+                    } else {
+                        foreach ($reflection->getTraitNames() as $traitName) {
+                            if ($this->classHasMember($traitName, $member_type, $member_name)) {
+                                $traitAnnotations = $this->getAnnotations($traitName, $member_type, $member_name);
+                                break;
+                            }
+                        }
+                    }
 
-                if ($member_type === self::MEMBER_CLASS) {
-                    $classAnnotations = $annotations;
+                    $annotations = array_merge($traitAnnotations, $annotations);
                 }
             }
 
@@ -321,6 +345,25 @@ protected function getAnnotations($class_name, $member_type = self::MEMBER_CLASS
         return $this->annotations[$key];
     }
 
+    /**
+     * Determines whether a class or trait has the specified member.
+     *
+     * @param string $className The name of the class or trait to check
+     * @param string $memberType The type of member, e.g. "property" or "method"
+     * @param string $memberName The member name, e.g. "method" or "$property"
+     *
+     * @return bool whether class or trait has the specified member
+     */
+    protected function classHasMember($className, $memberType, $memberName)
+    {
+        if ($memberType === self::MEMBER_METHOD) {
+            return method_exists($className, $memberName);
+        } else if ($memberType === self::MEMBER_PROPERTY) {
+            return property_exists($className, ltrim($memberName, '$'));
+        }
+        return false;
+    }
+
     /**
      * Validates the constraints (as defined by the UsageAnnotation of each annotation) of a
      * list of annotations for a given type of member.
@@ -453,14 +496,14 @@ public function getClassAnnotations($class, $type = null)
             $class = ltrim($class, '\\');
         }
 
-        if (!class_exists($class, $this->autoload)) {
-            $isTrait = function_exists('trait_exists') ? trait_exists($class, $this->autoload) : false;
-
-            if (interface_exists($class, $this->autoload) || $isTrait) {
-                throw new AnnotationException("Reading annotations from interface/trait '{$class}' is not supported");
+        if (!class_exists($class, $this->autoload) &&
+            !(function_exists('trait_exists') && trait_exists($class, $this->autoload))
+        ) {
+            if (interface_exists($class, $this->autoload)) {
+                throw new AnnotationException("Reading annotations from interface '{$class}' is not supported");
             }
 
-            throw new AnnotationException("Unable to read annotations from an undefined class '{$class}'");
+            throw new AnnotationException("Unable to read annotations from an undefined class/trait '{$class}'");
         }
 
         if ($type === null) {

src/annotations/AnnotationParser.php

@@ -13,6 +13,10 @@
 
 namespace mindplay\annotations;
 
+if (!defined('T_TRAIT')) {
+    define(__NAMESPACE__ . '\\T_TRAIT', -2);
+}
+
 /**
  * This class implements a parser for source code annotations
  */
@@ -27,6 +31,10 @@ class AnnotationParser
     const NAMESPACE_NAME = 6;
     const USE_CLAUSE = 11;
     const USE_CLAUSE_AS = 12;
+    const TRAIT_USE_CLAUSE = 13;
+    const TRAIT_USE_BLOCK = 14;
+    const TRAIT_USE_AS = 15;
+    const TRAIT_USE_INSTEADOF = 16;
 
     const SKIP = 7;
     const NAME = 8;
@@ -68,6 +76,7 @@ public function __construct(AnnotationManager $manager)
     public function parse($source, $path)
     {
         $index = array();
+        $traitMethodOverrides = array();
 
         $docblocks = array();
         $state = self::SCAN;
@@ -91,7 +100,7 @@ public function parse($source, $path)
 
             switch ($state) {
                 case self::SCAN:
-                    if ($type == T_CLASS) {
+                    if ($type == T_CLASS || $type == T_TRAIT) {
                         $state = self::CLASS_NAME;
                     }
                     if ($type == T_NAMESPACE) {
@@ -159,6 +168,7 @@ public function parse($source, $path)
                 case self::CLASS_NAME:
                     if ($type == T_STRING) {
                         $class = ($namespace ? $namespace . '\\' : '') . $str;
+                        $traitMethodOverrides[$class] = array();
                         $index[$class] = $docblocks;
                         $docblocks = array();
                         $state = self::SCAN_CLASS;
@@ -172,6 +182,59 @@ public function parse($source, $path)
                     if ($type == T_FUNCTION) {
                         $state = self::METHOD_NAME;
                     }
+                    if ($type == T_USE) {
+                        $state = self::TRAIT_USE_CLAUSE;
+                        $use = '';
+                    }
+                    break;
+
+                case self::TRAIT_USE_CLAUSE:
+                    if ($type === self::CHAR) {
+                        if ($str === '{') {
+                            $state = self::TRAIT_USE_BLOCK;
+                            $use = '';
+                        } elseif ($str === ';') {
+                            $state = self::SCAN_CLASS;
+                        }
+                    }
+                    break;
+
+                case self::TRAIT_USE_BLOCK:
+                    if ($type == T_STRING || $type == T_NS_SEPARATOR || $type == T_DOUBLE_COLON) {
+                        $use .= $str;
+                    } elseif ($type === T_INSTEADOF) {
+                        $state = self::TRAIT_USE_INSTEADOF;
+                    } elseif ($type === T_AS) {
+                        $state = self::TRAIT_USE_AS;
+                        $use_as = '';
+                    } elseif ($type === self::CHAR) {
+                        if ($str === ';') {
+                            $use = '';
+                        } elseif ($str === '}') {
+                            $state = self::SCAN_CLASS;
+                        }
+                    }
+                    break;
+
+                case self::TRAIT_USE_INSTEADOF:
+                    if ($type === self::CHAR && $str === ';') {
+                        $traitMethodOverrides[$class][substr($use, strrpos($use, '::') + 2)] = $use;
+                        $state = self::TRAIT_USE_BLOCK;
+                        $use = '';
+                    }
+                    break;
+
+                case self::TRAIT_USE_AS:
+                    if ($type === T_STRING) {
+                        $use_as .= $str;
+                    } elseif ($type === self::CHAR && $str === ';') {
+                        // Ignore use... as statements that only change method visibility.
+                        if ($use_as !== '') {
+                            $traitMethodOverrides[$class][$use_as] = $use;
+                        }
+                        $state = self::TRAIT_USE_BLOCK;
+                        $use = '';
+                    }
                     break;
 
                 case self::MEMBER:
@@ -233,6 +296,8 @@ public function parse($source, $path)
         $code = "return array(\n";
         $code .= "  '#namespace' => " . var_export($namespace, true) . ",\n";
         $code .= "  '#uses' => " . var_export($uses, true) . ",\n";
+        $code .= "  '#traitMethodOverrides' => " . var_export($traitMethodOverrides, true) . ",\n";
+
         foreach ($index as $key => $docblocks) {
             $array = array();
             foreach ($docblocks as $str) {