typo3/sysext/extbase/Classes/Reflection/Service.php

   1 <?php
   2 /***************************************************************
   3 *  Copyright notice
   4 *
   5 *  (c) 2009 Christopher Hlubek <hlubek@networkteam.com>
   6 *  All rights reserved
   7 *
   8 *  This script is part of the TYPO3 project. The TYPO3 project is
   9 *  free software; you can redistribute it and/or modify
  10 *  it under the terms of the GNU General Public License as published by
  11 *  the Free Software Foundation; either version 2 of the License, or
  12 *  (at your option) any later version.
  13 *
  14 *  The GNU General Public License can be found at
  15 *  http://www.gnu.org/copyleft/gpl.html.
  16 *
  17 *  This script is distributed in the hope that it will be useful,
  18 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 *  GNU General Public License for more details.
  21 *
  22 *  This copyright notice MUST APPEAR in all copies of the script!
  23 ***************************************************************/
  24
  25 /**
  26  * A backport of the FLOW3 reflection service for aquiring reflection based information.
  27  * Most of the code is based on the FLOW3 reflection service.
  28  *
  29  * @package Extbase
  30  * @subpackage Reflection
  31  * @version $Id$
  32  */
  33 class Tx_Extbase_Reflection_Service implements t3lib_Singleton {
  34
  35         /**
  36          * Whether this service has been initialized.
  37          *
  38          * @var boolean
  39          */
  40         protected $initialized = FALSE;
  41
  42         /**
  43          * @var t3lib_cache_frontend_VariableFrontend
  44          */
  45         protected $cache;
  46
  47         /**
  48          * Whether class alterations should be detected on each initialization.
  49          *
  50          * @var boolean
  51          */
  52         protected $detectClassChanges = FALSE;
  53
  54         /**
  55          * All available class names to consider. Class name = key, value is the
  56          * UNIX timestamp the class was reflected.
  57          *
  58          * @var array
  59          */
  60         protected $reflectedClassNames = array();
  61
  62         /**
  63          * Array of tags and the names of classes which are tagged with them.
  64          *
  65          * @var array
  66          */
  67         protected $taggedClasses = array();
  68
  69         /**
  70          * Array of class names and their tags and values.
  71          *
  72          * @var array
  73          */
  74         protected $classTagsValues = array();
  75
  76         /**
  77          * Array of class names, method names and their tags and values.
  78          *
  79          * @var array
  80          */
  81         protected $methodTagsValues = array();
  82
  83         /**
  84          * Array of class names, method names, their parameters and additional
  85          * information about the parameters.
  86          *
  87          * @var array
  88          */
  89         protected $methodParameters = array();
  90
  91         /**
  92          * Array of class names and names of their properties.
  93          *
  94          * @var array
  95          */
  96         protected $classPropertyNames = array();
  97
  98         /**
  99          * Array of class names, property names and their tags and values.
 100          *
 101          * @var array
 102          */
 103         protected $propertyTagsValues = array();
 104
 105         /**
 106          * List of tags which are ignored while reflecting class and method annotations.
 107          *
 108          * @var array
 109          */
 110         protected $ignoredTags = array('package', 'subpackage', 'license', 'copyright', 'author', 'version', 'const');
 111
 112         /**
 113          * Indicates whether the Reflection cache needs to be updated.
 114          *
 115          * This flag needs to be set as soon as new Reflection information was
 116          * created.
 117          *
 118          * @see reflectClass()
 119          * @see getMethodReflection()
 120          *
 121          * @var boolean
 122          */
 123         protected $cacheNeedsUpdate = FALSE;
 124
 125         /**
 126          * Sets the cache.
 127          *
 128          * The cache must be set before initializing the Reflection Service.
 129          *
 130          * @param t3lib_cache_frontend_VariableFrontend $cache Cache for the Reflection service
 131          * @return void
 132          */
 133         public function setCache(t3lib_cache_frontend_VariableFrontend $cache) {
 134                 $this->cache = $cache;
 135         }
 136
 137         /**
 138          * Initializes this service
 139          *
 140          * @param array $classNamesToReflect Names of available classes to consider in this reflection service
 141          * @return void
 142          */
 143         public function initialize() {
 144                 if ($this->initialized) throw new Tx_Extbase_Reflection_Exception('The Reflection Service can only be initialized once.', 1232044696);
 145
 146                 $this->loadFromCache();
 147
 148                 $this->initialized = TRUE;
 149         }
 150
 151         /**
 152          * Returns whether the Reflection Service is initialized.
 153          *
 154          * @return boolean true if the Reflection Service is initialized, otherwise false
 155          */
 156         public function isInitialized() {
 157                 return $this->initialized;
 158         }
 159
 160         /**
 161          * Shuts the Reflection Service down.
 162          *
 163          * @return void
 164          */
 165         public function shutdown() {
 166                 if ($this->cacheNeedsUpdate) {
 167                         $this->saveToCache();
 168                 }
 169         }
 170
 171         /**
 172          * Returns the names of all properties of the specified class
 173          *
 174          * @param string $className Name of the class to return the property names of
 175          * @return array An array of property names or an empty array if none exist
 176          */
 177         public function getClassPropertyNames($className) {
 178                 if (!isset($this->reflectedClassNames[$className])) $this->reflectClass($className);
 179                 return (isset($this->classPropertyNames[$className])) ? $this->classPropertyNames[$className] : array();
 180         }
 181
 182         /**
 183          * Returns all tags and their values the specified method is tagged with
 184          *
 185          * @param string $className Name of the class containing the method
 186          * @param string $methodName Name of the method to return the tags and values of
 187          * @return array An array of tags and their values or an empty array of no tags were found
 188          */
 189         public function getMethodTagsValues($className, $methodName) {
 190                 if (!isset($this->methodTagsValues[$className][$methodName])) {
 191                         $this->methodTagsValues[$className][$methodName] = array();
 192                         $method = $this->getMethodReflection($className, $methodName);
 193                         foreach ($method->getTagsValues() as $tag => $values) {
 194                                 if (array_search($tag, $this->ignoredTags) === FALSE) {
 195                                         $this->methodTagsValues[$className][$methodName][$tag] = $values;
 196                                 }
 197                         }
 198                 }
 199                 return $this->methodTagsValues[$className][$methodName];
 200         }
 201
 202
 203         /**
 204          * Returns an array of parameters of the given method. Each entry contains
 205          * additional information about the parameter position, type hint etc.
 206          *
 207          * @param string $className Name of the class containing the method
 208          * @param string $methodName Name of the method to return parameter information of
 209          * @return array An array of parameter names and additional information or an empty array of no parameters were found
 210          */
 211         public function getMethodParameters($className, $methodName) {
 212                 if (!isset($this->methodParameters[$className][$methodName])) {
 213                         $method = $this->getMethodReflection($className, $methodName);
 214                         $this->methodParameters[$className][$methodName] = array();
 215                         foreach($method->getParameters() as $parameterPosition => $parameter) {
 216                                 $this->methodParameters[$className][$methodName][$parameter->getName()] = $this->convertParameterReflectionToArray($parameter, $parameterPosition, $method);
 217                         }
 218                 }
 219                 return $this->methodParameters[$className][$methodName];
 220         }
 221
 222         /**
 223          * Returns all tags and their values the specified class property is tagged with
 224          *
 225          * @param string $className Name of the class containing the property
 226          * @param string $propertyName Name of the property to return the tags and values of
 227          * @return array An array of tags and their values or an empty array of no tags were found
 228          */
 229         public function getPropertyTagsValues($className, $propertyName) {
 230                 if (!isset($this->reflectedClassNames[$className])) $this->reflectClass($className);
 231                 if (!isset($this->propertyTagsValues[$className])) return array();
 232                 return (isset($this->propertyTagsValues[$className][$propertyName])) ? $this->propertyTagsValues[$className][$propertyName] : array();
 233         }
 234
 235         /**
 236          * Reflects the given class and stores the results in this service's properties.
 237          *
 238          * @param string $className Full qualified name of the class to reflect
 239          * @return void
 240          */
 241         protected function reflectClass($className) {
 242                 $class = new Tx_Extbase_Reflection_ClassReflection($className);
 243                 $this->reflectedClassNames[$className] = time();
 244
 245                 foreach ($class->getTagsValues() as $tag => $values) {
 246                         if (array_search($tag, $this->ignoredTags) === FALSE) {
 247                                 $this->taggedClasses[$tag][] = $className;
 248                                 $this->classTagsValues[$className][$tag] = $values;
 249                         }
 250                 }
 251
 252                 foreach ($class->getProperties() as $property) {
 253                         $propertyName = $property->getName();
 254                         $this->classPropertyNames[$className][] = $propertyName;
 255
 256                         foreach ($property->getTagsValues() as $tag => $values) {
 257                                 if (array_search($tag, $this->ignoredTags) === FALSE) {
 258                                         $this->propertyTagsValues[$className][$propertyName][$tag] = $values;
 259                                 }
 260                         }
 261                 }
 262
 263                 foreach ($class->getMethods() as $method) {
 264                         $methodName = $method->getName();
 265                         foreach ($method->getTagsValues() as $tag => $values) {
 266                                 if (array_search($tag, $this->ignoredTags) === FALSE) {
 267                                         $this->methodTagsValues[$className][$methodName][$tag] = $values;
 268                                 }
 269                         }
 270
 271                         foreach ($method->getParameters() as $parameter) {
 272                                 $this->methodParameters[$className][$methodName][$parameter->getName()] = $this->convertParameterReflectionToArray($parameter, $method);
 273                         }
 274                 }
 275                 ksort($this->reflectedClassNames);
 276
 277                 $this->cacheNeedsUpdate = TRUE;
 278         }
 279
 280         /**
 281          * Converts the given parameter reflection into an information array
 282          *
 283          * @param ReflectionParameter $parameter The parameter to reflect
 284          * @return array Parameter information array
 285          */
 286         protected function convertParameterReflectionToArray(ReflectionParameter $parameter, $parameterPosition, ReflectionMethod $method = NULL) {
 287                 $parameterInformation = array(
 288                         'position' => $parameterPosition,
 289                         'byReference' => $parameter->isPassedByReference() ? TRUE : FALSE,
 290                         'array' => $parameter->isArray() ? TRUE : FALSE,
 291                         'optional' => $parameter->isOptional() ? TRUE : FALSE,
 292                         'allowsNull' => $parameter->allowsNull() ? TRUE : FALSE
 293                 );
 294
 295                 $parameterClass = $parameter->getClass();
 296                 $parameterInformation['class'] = ($parameterClass !== NULL) ? $parameterClass->getName() : NULL;
 297                 if ($parameter->isDefaultValueAvailable()) {
 298                         $parameterInformation['defaultValue'] = $parameter->getDefaultValue();
 299                 }
 300                 if ($parameterClass !== NULL) {
 301                         $parameterInformation['type'] = $parameterClass->getName();
 302                 } elseif ($method !== NULL) {
 303                         $methodTagsAndValues = $this->getMethodTagsValues($method->getDeclaringClass()->getName(), $method->getName());
 304                         if (isset($methodTagsAndValues['param']) && isset($methodTagsAndValues['param'][$parameterPosition])) {
 305                                 $explodedParameters = explode(' ', $methodTagsAndValues['param'][$parameterPosition]);
 306                                 if (count($explodedParameters) >= 2) {
 307                                         $parameterInformation['type'] = $explodedParameters[0];
 308                                 }
 309                         }
 310                 }
 311                 if (isset($parameterInformation['type']) && $parameterInformation['type']{0} === '\\') {
 312                         $parameterInformation['type'] = substr($parameterInformation['type'], 1);
 313                 }
 314                 return $parameterInformation;
 315         }
 316
 317         /**
 318          * Returns the Reflection of a method.
 319          *
 320          * @param string $className Name of the class containing the method
 321          * @param string $methodName Name of the method to return the Reflection for
 322          * @return Tx_Extbase_Reflection_MethodReflection the method Reflection object
 323          */
 324         protected function getMethodReflection($className, $methodName) {
 325                 if (!isset($this->methodReflections[$className][$methodName])) {
 326                         $this->methodReflections[$className][$methodName] = new Tx_Extbase_Reflection_MethodReflection($className, $methodName);
 327                         $this->cacheNeedsUpdate = TRUE;
 328                 }
 329                 return $this->methodReflections[$className][$methodName];
 330         }
 331
 332         /**
 333          * Tries to load the reflection data from this service's cache.
 334          *
 335          * @return void
 336
 337          */
 338         protected function loadFromCache() {
 339                 if ($this->cache->has('ReflectionData')) {
 340                         $data = $this->cache->get('ReflectionData');
 341                         foreach ($data as $propertyName => $propertyValue) {
 342                                 $this->$propertyName = $propertyValue;
 343                         }
 344                 }
 345         }
 346
 347         /**
 348          * Exports the internal reflection data into the ReflectionData cache.
 349          *
 350          * @return void
 351
 352          */
 353         protected function saveToCache() {
 354                 if (!is_object($this->cache)) {
 355                         throw new Tx_Extbase_Reflection_Exception(
 356                                 'A cache must be injected before initializing the Reflection Service.',
 357                                 1232044697
 358                         );
 359                 }
 360
 361                 $data = array();
 362                 $propertyNames = array(
 363                         'reflectedClassNames',
 364                         'classPropertyNames',
 365                         'classTagsValues',
 366                         'methodTagsValues',
 367                         'methodParameters',
 368                         'propertyTagsValues',
 369                         'taggedClasses'
 370                 );
 371                 foreach ($propertyNames as $propertyName) {
 372                         $data[$propertyName] = $this->$propertyName;
 373                 }
 374                 $this->cache->set('ReflectionData', $data);
 375         }
 376 }
 377 ?>