classes/Kohana/Kodoc/Class.php

   1 <?php defined('SYSPATH') or die('No direct script access.');
   2 /**
   3  * Class documentation generator.
   4  *
   5  * @package    Kohana/Userguide
   6  * @category   Base
   7  * @author     Kohana Team
   8  * @copyright  (c) 2008-2013 Kohana Team
   9  * @license    http://kohanaframework.org/license
  10  */
  11 class Kohana_Kodoc_Class extends Kodoc {
  12
  13         /**
  14          * @var  ReflectionClass The ReflectionClass for this class
  15          */
  16         public $class;
  17
  18         /**
  19          * @var  string  modifiers like abstract, final
  20          */
  21         public $modifiers;
  22
  23         /**
  24          * @var  string  description of the class from the comment
  25          */
  26         public $description;
  27
  28         /**
  29          * @var  array  array of tags, retrieved from the comment
  30          */
  31         public $tags = array();
  32
  33         /**
  34          * @var  array  array of this classes constants
  35          */
  36         public $constants = array();
  37
  38         /**
  39          * @var array Parent classes/interfaces of this class/interface
  40          */
  41         public $parents = array();
  42
  43         /**
  44          * Loads a class and uses [reflection](http://php.net/reflection) to parse
  45          * the class. Reads the class modifiers, constants and comment. Parses the
  46          * comment to find the description and tags.
  47          *
  48          * @param   string  Class name
  49          * @return  void
  50          */
  51         public function __construct($class)
  52         {
  53                 $this->class = new ReflectionClass($class);
  54
  55                 if ($modifiers = $this->class->getModifiers())
  56                 {
  57                         $this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
  58                 }
  59
  60                 $this->constants = $this->class->getConstants();
  61
  62                 // If ReflectionClass::getParentClass() won't work if the class in
  63                 // question is an interface
  64                 if ($this->class->isInterface())
  65                 {
  66                         $this->parents = $this->class->getInterfaces();
  67                 }
  68                 else
  69                 {
  70                         $parent = $this->class;
  71
  72                         while ($parent = $parent->getParentClass())
  73                         {
  74                                 $this->parents[] = $parent;
  75                         }
  76                 }
  77
  78                 if ( ! $comment = $this->class->getDocComment())
  79                 {
  80                         foreach ($this->parents as $parent)
  81                         {
  82                                 if ($comment = $parent->getDocComment())
  83                                 {
  84                                         // Found a description for this class
  85                                         break;
  86                                 }
  87                         }
  88                 }
  89
  90                 list($this->description, $this->tags) = Kodoc::parse($comment, FALSE);
  91         }
  92
  93         /**
  94          * Gets the constants of this class as HTML.
  95          *
  96          * @return  array
  97          */
  98         public function constants()
  99         {
 100                 $result = array();
 101
 102                 foreach ($this->constants as $name => $value)
 103                 {
 104                         $result[$name] = Debug::vars($value);
 105                 }
 106
 107                 return $result;
 108         }
 109
 110         /**
 111          * Get the description of this class as HTML. Includes a warning when the
 112          * class or one of its parents could not be found.
 113          *
 114          * @return  string  HTML
 115          */
 116         public function description()
 117         {
 118                 $result = $this->description;
 119
 120                 // If this class extends Kodoc_Missing, add a warning about possible
 121                 // incomplete documentation
 122                 foreach ($this->parents as $parent)
 123                 {
 124                         if ($parent->name == 'Kodoc_Missing')
 125                         {
 126                                 $result .= "[!!] **This class, or a class parent, could not be
 127                                            found or loaded. This could be caused by a missing
 128                                            module or other dependancy. The documentation for
 129                                            class may not be complete!**";
 130                         }
 131                 }
 132
 133                 return Kodoc_Markdown::markdown($result);
 134         }
 135
 136         /**
 137          * Gets a list of the class properties as [Kodoc_Property] objects.
 138          *
 139          * @return  array
 140          */
 141         public function properties()
 142         {
 143                 $props = $this->class->getProperties();
 144
 145                 $defaults = $this->class->getDefaultProperties();
 146
 147                 usort($props, array($this,'_prop_sort'));
 148
 149                 foreach ($props as $key => $property)
 150                 {
 151                         // Create Kodoc Properties for each property
 152                         $props[$key] = new Kodoc_Property($this->class->name, $property->name,  Arr::get($defaults, $property->name));
 153                 }
 154
 155                 return $props;
 156         }
 157
 158         protected function _prop_sort($a, $b)
 159         {
 160                 // If one property is public, and the other is not, it goes on top
 161                 if ($a->isPublic() AND ( ! $b->isPublic()))
 162                         return -1;
 163                 if ($b->isPublic() AND ( ! $a->isPublic()))
 164                         return 1;
 165
 166                 // If one property is protected and the other is private, it goes on top
 167                 if ($a->isProtected() AND $b->isPrivate())
 168                         return -1;
 169                 if ($b->isProtected() AND $a->isPrivate())
 170                         return 1;
 171
 172                 // Otherwise just do alphabetical
 173                 return strcmp($a->name, $b->name);
 174         }
 175
 176         /**
 177          * Gets a list of the class properties as [Kodoc_Method] objects.
 178          *
 179          * @return  array
 180          */
 181         public function methods()
 182         {
 183                 $methods = $this->class->getMethods();
 184
 185                 usort($methods, array($this,'_method_sort'));
 186
 187                 foreach ($methods as $key => $method)
 188                 {
 189                         $methods[$key] = new Kodoc_Method($this->class->name, $method->name);
 190                 }
 191
 192                 return $methods;
 193         }
 194
 195         /**
 196          * Sort methods based on their visibility and declaring class based on:
 197          *
 198          *  * methods will be sorted public, protected, then private.
 199          *  * methods that are declared by an ancestor will be after classes
 200          *    declared by the current class
 201          *  * lastly, they will be sorted alphabetically
 202          *
 203          */
 204         protected function _method_sort($a, $b)
 205         {
 206                 // If one method is public, and the other is not, it goes on top
 207                 if ($a->isPublic() AND ( ! $b->isPublic()))
 208                         return -1;
 209                 if ($b->isPublic() AND ( ! $a->isPublic()))
 210                         return 1;
 211
 212                 // If one method is protected and the other is private, it goes on top
 213                 if ($a->isProtected() AND $b->isPrivate())
 214                         return -1;
 215                 if ($b->isProtected() AND $a->isPrivate())
 216                         return 1;
 217
 218                 // The methods have the same visibility, so check the declaring class depth:
 219
 220
 221                 /*
 222                 echo Debug::vars('a is '.$a->class.'::'.$a->name,'b is '.$b->class.'::'.$b->name,
 223                                                    'are the classes the same?', $a->class == $b->class,'if they are, the result is:',strcmp($a->name, $b->name),
 224                                                    'is a this class?', $a->name == $this->class->name,-1,
 225                                                    'is b this class?', $b->name == $this->class->name,1,
 226                                                    'otherwise, the result is:',strcmp($a->class, $b->class)
 227                                                    );
 228                 */
 229
 230                 // If both methods are defined in the same class, just compare the method names
 231                 if ($a->class == $b->class)
 232                         return strcmp($a->name, $b->name);
 233
 234                 // If one of them was declared by this class, it needs to be on top
 235                 if ($a->name == $this->class->name)
 236                         return -1;
 237                 if ($b->name == $this->class->name)
 238                         return 1;
 239
 240                 // Otherwise, get the parents of each methods declaring class, then compare which function has more "ancestors"
 241                 $adepth = 0;
 242                 $bdepth = 0;
 243
 244                 $parent = $a->getDeclaringClass();
 245                 do
 246                 {
 247                         $adepth++;
 248                 }
 249                 while ($parent = $parent->getParentClass());
 250
 251                 $parent = $b->getDeclaringClass();
 252                 do
 253                 {
 254                         $bdepth++;
 255                 }
 256                 while ($parent = $parent->getParentClass());
 257
 258                 return $bdepth - $adepth;
 259         }
 260
 261         /**
 262          * Get the tags of this class as HTML.
 263          *
 264          * @return  array
 265          */
 266         public function tags()
 267         {
 268                 $result = array();
 269
 270                 foreach ($this->tags as $name => $set)
 271                 {
 272                         foreach ($set as $text)
 273                         {
 274                                 $result[$name][] = Kodoc::format_tag($name, $text);
 275                         }
 276                 }
 277
 278                 return $result;
 279         }
 280
 281 } // End Kodoc_Class