annotations.php

<?php
/*
 * Addendum PHP Reflection Annotations
 * http://code.google.com/p/addendum/
 *
 * Copyright (C) 2006-2009 Jan "johno Suchal <johno@jsmf.net>

 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.

 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.

 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

/**
 * FORK Addendum PHP Reflection Annotations
 *
 * @filesource    annotations.php
 * @link          https://github.com/eriknyk/addendum
 * @version       $Revision$
 * @modifiedby    $LastChangedBy$
 * @lastmodified  $Date$
 * @license       http://www.gnu.org/licenses/lgpl-2.1.html
 * @author        Erik Amaru Ortiz <aortiz.erik@gmail.com>
 */

require_once(dirname(__FILE__).'/annotations/annotation_parser.php');

class Annotation
{
    public $value;

    private static $creationStack = array();

    /**
     * @var array contains a string array that store any log message like warnings or errors.
     * @author Erik Amaru ortiz <aortiz.erik@gmail.com>
     */
    public static $log = array();

    public final function __construct($data = array(), $target = false)
    {
        $reflection = new ReflectionClass($this);
        $class = $reflection->getName();
        if(isset(self::$creationStack[$class])) {
            trigger_error("Circular annotation reference on '$class'", E_USER_ERROR);
            return;
        }
        self::$creationStack[$class] = true;
        foreach($data as $key => $value) {
            if($reflection->hasProperty($key)) {
                $this->$key = $value;
            } else {
                trigger_error("Property '$key' not defined for annotation '$class'");
            }
        }
        $this->checkTargetConstraints($target);
        $this->checkConstraints($target);
        unset(self::$creationStack[$class]);
    }

    private function checkTargetConstraints($target)
    {
        $reflection = new ReflectionAnnotatedClass($this);
        if($reflection->hasAnnotation('Target')) {
            $value = $reflection->getAnnotation('Target')->value;
            $values = is_array($value) ? $value : array($value);
            foreach($values as $value) {
                if($value == 'class' && $target instanceof ReflectionClass) return;
                if($value == 'method' && $target instanceof ReflectionMethod) return;
                if($value == 'property' && $target instanceof ReflectionProperty) return;
                if($value == 'nested' && $target === false) return;
            }
            if($target === false) {
                trigger_error("Annotation '".get_class($this)."' nesting not allowed", E_USER_ERROR);
            } else {
                trigger_error("Annotation '".get_class($this)."' not allowed on ".$this->createName($target), E_USER_ERROR);
            }
        }
    }

    private function createName($target)
    {
        if($target instanceof ReflectionMethod) {
            return $target->getDeclaringClass()->getName().'::'.$target->getName();
        } elseif($target instanceof ReflectionProperty) {
            return $target->getDeclaringClass()->getName().'::$'.$target->getName();
        } else {
            return $target->getName();
        }
    }

    protected function checkConstraints($target) {}

    public function log($str)
    {
        self::$log[] = $str;
    }

    public function getLog()
    {
        return self::$log;
    }
}

class AnnotationsCollection
{
    private $annotations;

    public function __construct($annotations)
    {
        $this->annotations = $annotations;
    }

    public function hasAnnotation($class)
    {
        $class = Addendum::resolveClassName($class);
        return isset($this->annotations[$class]);
    }

    public function getAnnotation($class)
    {
        $class = Addendum::resolveClassName($class);
        return isset($this->annotations[$class]) ? end($this->annotations[$class]) : false;
    }

    public function getAnnotations()
    {
        $result = array();
        foreach($this->annotations as $instances) {
            $result[] = end($instances);
        }
        return $result;
    }

    public function getAllAnnotations($restriction = false)
    {
        $restriction = Addendum::resolveClassName($restriction);
        $result = array();
        foreach($this->annotations as $class => $instances) {
            if(!$restriction || $restriction == $class) {
                $result = array_merge($result, $instances);
            }
        }
        return $result;
    }
}

class Annotation_Target extends Annotation {}

class AnnotationsBuilder
{
    private static $cache = array();

    public function build($targetReflection)
    {
        $data = $this->parse($targetReflection);
        $annotations = array();
        foreach($data as $class => $parameters) {
            foreach($parameters as $params) {
                $annotation = $this->instantiateAnnotation($class, $params, $targetReflection);
                if($annotation !== false) {
                    $annotations[get_class($annotation)][] = $annotation;
                }
            }
        }
        return new AnnotationsCollection($annotations);
    }

    public function instantiateAnnotation($class, $parameters, $targetReflection = false)
    {
        //erik 7/8/2011: first at all verify if the class exists
        if (class_exists($class)) {
            $class = Addendum::resolveClassName($class);
            if(is_subclass_of($class, 'Annotation') && !Addendum::ignores($class) || $class == 'Annotation') {
                $annotationReflection = new ReflectionClass($class);
                return $annotationReflection->newInstance($parameters, $targetReflection);
            }
        } else {
            Annotation::log("Skipped - Annotated class defined $class but doesn't exist");
        }
        return false;
    }

    private function parse($reflection)
    {
        $key = $this->createName($reflection);
        if(!isset(self::$cache[$key])) {
            $parser = new AnnotationsMatcher;
            $parser->matches($this->getDocComment($reflection), $data);
            self::$cache[$key] = $data;
        }
        return self::$cache[$key];
    }

    private function createName($target)
    {
        if($target instanceof ReflectionMethod) {
            return $target->getDeclaringClass()->getName().'::'.$target->getName();
        } elseif($target instanceof ReflectionProperty) {
            return $target->getDeclaringClass()->getName().'::$'.$target->getName();
        } else {
            return $target->getName();
        }
    }

    protected function getDocComment($reflection)
    {
        return Addendum::getDocComment($reflection);
    }

    public static function clearCache()
    {
        self::$cache = array();
    }
}

class ReflectionAnnotatedClass extends ReflectionClass
{
    private $annotations;

    public function __construct($class)
    {
        parent::__construct($class);
        $this->annotations = $this->createAnnotationBuilder()->build($this);
    }

    public function hasAnnotation($class)
    {
        return $this->annotations->hasAnnotation($class);
    }

    public function getAnnotation($annotation)
    {
        return $this->annotations->getAnnotation($annotation);
    }

    public function getAnnotations()
    {
        return $this->annotations->getAnnotations();
    }

    public function getAllAnnotations($restriction = false)
    {
        return $this->annotations->getAllAnnotations($restriction);
    }

    public function getConstructor()
    {
        return $this->createReflectionAnnotatedMethod(parent::getConstructor());
    }

    public function getMethod($name)
    {
        return $this->createReflectionAnnotatedMethod(parent::getMethod($name));
    }

    public function getMethods($filter = -1)
    {
        $result = array();
        foreach(parent::getMethods($filter) as $method) {
            $result[] = $this->createReflectionAnnotatedMethod($method);
        }
        return $result;
    }

    public function getProperty($name)
    {
        return $this->createReflectionAnnotatedProperty(parent::getProperty($name));
    }

    public function getProperties($filter = -1)
    {
        $result = array();
        foreach(parent::getProperties($filter) as $property) {
            $result[] = $this->createReflectionAnnotatedProperty($property);
        }
        return $result;
    }

    public function getInterfaces()
    {
        $result = array();
        foreach(parent::getInterfaces() as $interface) {
            $result[] = $this->createReflectionAnnotatedClass($interface);
        }
        return $result;
    }

    public function getParentClass()
    {
        $class = parent::getParentClass();
        return $this->createReflectionAnnotatedClass($class);
    }

    protected function createAnnotationBuilder()
    {
        return new AnnotationsBuilder();
    }

    private function createReflectionAnnotatedClass($class)
    {
        return ($class !== false) ? new ReflectionAnnotatedClass($class->getName()) : false;
    }

    private function createReflectionAnnotatedMethod($method)
    {
        return ($method !== null) ? new ReflectionAnnotatedMethod($this->getName(), $method->getName()) : null;
    }

    private function createReflectionAnnotatedProperty($property)
    {
        return ($property !== null) ? new ReflectionAnnotatedProperty($this->getName(), $property->getName()) : null;
    }
}

class ReflectionAnnotatedMethod extends ReflectionMethod
{
    private $annotations;

    public function __construct($class, $name)
    {
        parent::__construct($class, $name);
        $this->annotations = $this->createAnnotationBuilder()->build($this);
    }

    public function hasAnnotation($class)
    {
        return $this->annotations->hasAnnotation($class);
    }

    public function getAnnotation($annotation)
    {
        return $this->annotations->getAnnotation($annotation);
    }

    public function getAnnotations()
    {
        return $this->annotations->getAnnotations();
    }

    public function getAllAnnotations($restriction = false)
    {
        return $this->annotations->getAllAnnotations($restriction);
    }

    public function getDeclaringClass()
    {
        $class = parent::getDeclaringClass();
        return new ReflectionAnnotatedClass($class->getName());
    }

    protected function createAnnotationBuilder()
    {
        return new AnnotationsBuilder();
    }
}

class ReflectionAnnotatedProperty extends ReflectionProperty
{
    private $annotations;

    public function __construct($class, $name)
    {
        parent::__construct($class, $name);
        $this->annotations = $this->createAnnotationBuilder()->build($this);
    }

    public function hasAnnotation($class)
    {
        return $this->annotations->hasAnnotation($class);
    }

    public function getAnnotation($annotation)
    {
        return $this->annotations->getAnnotation($annotation);
    }

    public function getAnnotations()
    {
        return $this->annotations->getAnnotations();
    }

    public function getAllAnnotations($restriction = false)
    {
        return $this->annotations->getAllAnnotations($restriction);
    }

    public function getDeclaringClass()
    {
        $class = parent::getDeclaringClass();
        return new ReflectionAnnotatedClass($class->getName());
    }

    protected function createAnnotationBuilder()
    {
        return new AnnotationsBuilder();
    }
}

class Addendum
{
    private static $rawMode;
    private static $ignore;
    private static $classnames = array();
    private static $annotations = false;

    public static function getDocComment($reflection)
    {
        if(self::checkRawDocCommentParsingNeeded()) {
            $docComment = new DocComment();
            return $docComment->get($reflection);
        } else {
            return $reflection->getDocComment();
        }
    }

    /** Raw mode test */
    private static function checkRawDocCommentParsingNeeded()
    {
        if(self::$rawMode === null) {
            $reflection = new ReflectionClass('Addendum');
            $method = $reflection->getMethod('checkRawDocCommentParsingNeeded');
            self::setRawMode($method->getDocComment() === false);
        }
        return self::$rawMode;
    }

    public static function setRawMode($enabled = true)
    {
        if($enabled) {
            require_once(dirname(__FILE__).'/annotations/doc_comment.php');
        }
        self::$rawMode = $enabled;
    }

    public static function resetIgnoredAnnotations()
    {
        self::$ignore = array();
    }

    public static function ignores($class)
    {
        return isset(self::$ignore[$class]);
    }

    public static function ignore()
    {
        foreach(func_get_args() as $class) {
            self::$ignore[$class] = true;
        }
    }

    public static function resolveClassName($class)
    {
        if(isset(self::$classnames[$class])) return self::$classnames[$class];
        $matching = array();
        foreach(self::getDeclaredAnnotations() as $declared) {
            if($declared == $class) {
                $matching[] = $declared;
            } else {
                $pos = strrpos($declared, "_$class");
                if($pos !== false && ($pos + strlen($class) == strlen($declared) - 1)) {
                    $matching[] = $declared;
                }
            }
        }
        $result = null;
        switch(count($matching)) {
            case 0: $result = $class; break;
            case 1: $result = $matching[0]; break;
            default: trigger_error("Cannot resolve class name for '$class'. Possible matches: " . join(', ', $matching), E_USER_ERROR);
        }
        self::$classnames[$class] = $result;
        return $result;
    }

    private static function getDeclaredAnnotations()
    {
        if(!self::$annotations) {
            self::$annotations = array();
            foreach(get_declared_classes() as $class) {
                if(is_subclass_of($class, 'Annotation') || $class == 'Annotation') self::$annotations[] = $class;
            }
        }
        return self::$annotations;
    }
}