Kohana v3.3.0

This commit is contained in:
Deon George
2013-04-22 14:09:50 +10:00
commit f96694b18f
1280 changed files with 145034 additions and 0 deletions

View File

@@ -0,0 +1,279 @@
<?php defined('SYSPATH') or die('No direct script access.');
/**
* Class documentation generator.
*
* @package Kohana/Userguide
* @category Base
* @author Kohana Team
* @copyright (c) 2009-2012 Kohana Team
* @license http://kohanaphp.com/license
*/
class Kohana_Kodoc_Class extends Kodoc {
/**
* @var ReflectionClass The ReflectionClass for this class
*/
public $class;
/**
* @var string modifiers like abstract, final
*/
public $modifiers;
/**
* @var string description of the class from the comment
*/
public $description;
/**
* @var array array of tags, retrieved from the comment
*/
public $tags = array();
/**
* @var array array of this classes constants
*/
public $constants = array();
/**
* @var array Parent classes/interfaces of this class/interface
*/
public $parents = array();
/**
* Loads a class and uses [reflection](http://php.net/reflection) to parse
* the class. Reads the class modifiers, constants and comment. Parses the
* comment to find the description and tags.
*
* @param string class name
* @return void
*/
public function __construct($class)
{
$this->class = new ReflectionClass($class);
if ($modifiers = $this->class->getModifiers())
{
$this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
}
$this->constants = $this->class->getConstants();
// If ReflectionClass::getParentClass() won't work if the class in
// question is an interface
if ($this->class->isInterface())
{
$this->parents = $this->class->getInterfaces();
}
else
{
$parent = $this->class;
while ($parent = $parent->getParentClass())
{
$this->parents[] = $parent;
}
}
if ( ! $comment = $this->class->getDocComment())
{
foreach ($this->parents as $parent)
{
if ($comment = $parent->getDocComment())
{
// Found a description for this class
break;
}
}
}
list($this->description, $this->tags) = Kodoc::parse($comment, FALSE);
}
/**
* Gets the constants of this class as HTML.
*
* @return array
*/
public function constants()
{
$result = array();
foreach ($this->constants as $name => $value)
{
$result[$name] = Debug::vars($value);
}
return $result;
}
/**
* Get the description of this class as HTML. Includes a warning when the
* class or one of its parents could not be found.
*
* @return string HTML
*/
public function description()
{
$result = $this->description;
// If this class extends Kodoc_Missing, add a warning about possible
// incomplete documentation
foreach ($this->parents as $parent)
{
if ($parent->name == 'Kodoc_Missing')
{
$result .= "[!!] **This class, or a class parent, could not be
found or loaded. This could be caused by a missing
module or other dependancy. The documentation for
class may not be complete!**";
}
}
return Kodoc_Markdown::markdown($result);
}
/**
* Gets a list of the class properties as [Kodoc_Property] objects.
*
* @return array
*/
public function properties()
{
$props = $this->class->getProperties();
$defaults = $this->class->getDefaultProperties();
usort($props, array($this,'_prop_sort'));
foreach ($props as $key => $property)
{
// Create Kodoc Properties for each property
$props[$key] = new Kodoc_Property($this->class->name, $property->name, Arr::get($defaults, $property->name));
}
return $props;
}
protected function _prop_sort($a, $b)
{
// If one property is public, and the other is not, it goes on top
if ($a->isPublic() AND ( ! $b->isPublic()))
return -1;
if ($b->isPublic() AND ( ! $a->isPublic()))
return 1;
// If one property is protected and the other is private, it goes on top
if ($a->isProtected() AND $b->isPrivate())
return -1;
if ($b->isProtected() AND $a->isPrivate())
return 1;
// Otherwise just do alphabetical
return strcmp($a->name, $b->name);
}
/**
* Gets a list of the class properties as [Kodoc_Method] objects.
*
* @return array
*/
public function methods()
{
$methods = $this->class->getMethods();
usort($methods, array($this,'_method_sort'));
foreach ($methods as $key => $method)
{
$methods[$key] = new Kodoc_Method($this->class->name, $method->name);
}
return $methods;
}
/**
* Sort methods based on their visibility and declaring class based on:
* - methods will be sorted public, protected, then private.
* - methods that are declared by an ancestor will be after classes
* declared by the current class
* - lastly, they will be sorted alphabetically
*
*/
protected function _method_sort($a, $b)
{
// If one method is public, and the other is not, it goes on top
if ($a->isPublic() AND ( ! $b->isPublic()))
return -1;
if ($b->isPublic() AND ( ! $a->isPublic()))
return 1;
// If one method is protected and the other is private, it goes on top
if ($a->isProtected() AND $b->isPrivate())
return -1;
if ($b->isProtected() AND $a->isPrivate())
return 1;
// The methods have the same visibility, so check the declaring class depth:
/*
echo Debug::vars('a is '.$a->class.'::'.$a->name,'b is '.$b->class.'::'.$b->name,
'are the classes the same?', $a->class == $b->class,'if they are, the result is:',strcmp($a->name, $b->name),
'is a this class?', $a->name == $this->class->name,-1,
'is b this class?', $b->name == $this->class->name,1,
'otherwise, the result is:',strcmp($a->class, $b->class)
);
*/
// If both methods are defined in the same class, just compare the method names
if ($a->class == $b->class)
return strcmp($a->name, $b->name);
// If one of them was declared by this class, it needs to be on top
if ($a->name == $this->class->name)
return -1;
if ($b->name == $this->class->name)
return 1;
// Otherwise, get the parents of each methods declaring class, then compare which function has more "ancestors"
$adepth = 0;
$bdepth = 0;
$parent = $a->getDeclaringClass();
do
{
$adepth++;
}
while ($parent = $parent->getParentClass());
$parent = $b->getDeclaringClass();
do
{
$bdepth++;
}
while ($parent = $parent->getParentClass());
return $bdepth - $adepth;
}
/**
* Get the tags of this class as HTML.
*
* @return array
*/
public function tags()
{
$result = array();
foreach ($this->tags as $name => $set)
{
foreach ($set as $text)
{
$result[$name][] = Kodoc::format_tag($name, $text);
}
}
return $result;
}
}

View File

@@ -0,0 +1,289 @@
<?php defined('SYSPATH') or die('No direct script access.');
/**
* Custom Markdown parser for Kohana documentation.
*
* @package Kohana/Userguide
* @category Base
* @author Kohana Team
* @copyright (c) 2009-2012 Kohana Team
* @license http://kohanaphp.com/license
*/
class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser {
/**
* @var string base url for links
*/
public static $base_url = '';
/**
* @var string base url for images
*/
public static $image_url = '';
/**
* Currently defined heading ids.
* Used to prevent creating multiple headings with same id.
* @var array
*/
protected $_heading_ids = array();
/**
* @var string the generated table of contents
*/
protected static $_toc = "";
/**
* Slightly less terrible way to make it so the TOC only shows up when we
* want it to. set this to true to show the toc.
*/
public static $show_toc = false;
/**
* Transform some text using [Kodoc_Markdown]
*
* @see Markdown()
*
* @param string Text to parse
* @return string Transformed text
*/
public static function markdown($text)
{
static $instance;
if ($instance === NULL)
{
$instance = new Kodoc_Markdown;
}
return $instance->transform($text);
}
public function __construct()
{
// doImage is 10, add image url just before
$this->span_gamut['doImageURL'] = 9;
// doLink is 20, add base url just before
$this->span_gamut['doBaseURL'] = 19;
// Add API links
$this->span_gamut['doAPI'] = 90;
// Add note spans last
$this->span_gamut['doNotes'] = 100;
// Parse Kohana view inclusions at the very end
$this->document_gamut['doIncludeViews'] = 99;
// Show table of contents for userguide pages
$this->document_gamut['doTOC'] = 100;
// PHP4 makes me sad.
parent::MarkdownExtra_Parser();
}
/**
* Callback for the heading setext style
*
* Heading 1
* =========
*
* @param array Matches from regex call
* @return string Generated html
*/
function _doHeaders_callback_setext($matches)
{
if ($matches[3] == '-' && preg_match('{^- }', $matches[1]))
return $matches[0];
$level = $matches[3]{0} == '=' ? 1 : 2;
$attr = $this->_doHeaders_attr($id =& $matches[2]);
// Only auto-generate id if one doesn't exist
if(empty($attr))
$attr = ' id="'.$this->make_heading_id($matches[1]).'"';
// Add this header to the page toc
$this->_add_to_toc($level,$matches[1],$this->make_heading_id($matches[1]));
$block = "<h$level$attr>".$this->runSpanGamut($matches[1])."</h$level>";
return "\n" . $this->hashBlock($block) . "\n\n";
}
/**
* Callback for the heading atx style
*
* # Heading 1
*
* @param array Matches from regex call
* @return string Generated html
*/
function _doHeaders_callback_atx($matches)
{
$level = strlen($matches[1]);
$attr = $this->_doHeaders_attr($id =& $matches[3]);
// Only auto-generate id if one doesn't exist
if(empty($attr))
$attr = ' id="'.$this->make_heading_id($matches[2]).'"';
// Add this header to the page toc
$this->_add_to_toc($level, $matches[2], $this->make_heading_id(empty($matches[3]) ? $matches[2] : $matches[3]));
$block = "<h$level$attr>".$this->runSpanGamut($matches[2])."</h$level>";
return "\n" . $this->hashBlock($block) . "\n\n";
}
/**
* Makes a heading id from the heading text
* If any heading share the same name then subsequent headings will have an integer appended
*
* @param string The heading text
* @return string ID for the heading
*/
function make_heading_id($heading)
{
$id = url::title($heading, '-', TRUE);
if(isset($this->_heading_ids[$id]))
{
$id .= '-';
$count = 0;
while (isset($this->_heading_ids[$id]) AND ++$count)
{
$id .= $count;
}
}
return $id;
}
public function doIncludeViews($text)
{
if (preg_match_all('/{{([^\s{}]++)}}/', $text, $matches, PREG_SET_ORDER))
{
$replace = array();
$replace = array();
foreach ($matches as $set)
{
list($search, $view) = $set;
if (Kohana::find_file('views', $view))
{
try
{
$replace[$search] = View::factory($view)->render();
}
catch (Exception $e)
{
/**
* Capture the exception handler output and insert it instead.
*
* NOTE: Is this really the correct way to handle an exception?
*/
$response = Kohana_exception::_handler($e);
$replace[$search] = $response->body();
}
}
}
$text = strtr($text, $replace);
}
return $text;
}
/**
* Add the current base url to all local links.
*
* [filesystem](about.filesystem "Optional title")
*
* @param string span text
* @return string
*/
public function doBaseURL($text)
{
// URLs containing "://" are left untouched
return preg_replace('~(?<!!)(\[.+?\]\()(?!\w++://)(?!#)(\S*(?:\s*+".+?")?\))~', '$1'.Kodoc_Markdown::$base_url.'$2', $text);
}
/**
* Add the current base url to all local images.
*
* ![Install Page](img/install.png "Optional title")
*
* @param string span text
* @return string
*/
public function doImageURL($text)
{
// URLs containing "://" are left untouched
return preg_replace('~(!\[.+?\]\()(?!\w++://)(\S*(?:\s*+".+?")?\))~', '$1'.Kodoc_Markdown::$image_url.'$2', $text);
}
/**
* Parses links to the API browser.
*
* [Class_Name], [Class::method] or [Class::$property]
*
* @param string span text
* @return string
*/
public function doAPI($text)
{
return preg_replace_callback('/\['.Kodoc::$regex_class_member.'\]/i', 'Kodoc::link_class_member', $text);
}
/**
* Wrap notes in the applicable markup. Notes can contain single newlines.
*
* [!!] Remember the milk!
*
* @param string span text
* @return string
*/
public function doNotes($text)
{
if ( ! preg_match('/^\[!!\]\s*+(.+?)(?=\n{2,}|$)/s', $text, $match))
{
return $text;
}
return $this->hashBlock('<p class="note">'.$match[1].'</p>');
}
protected function _add_to_toc($level, $name, $id)
{
self::$_toc[] = array(
'level' => $level,
'name' => $name,
'id' => $id);
}
public function doTOC($text)
{
// Only add the toc do userguide pages, not api since they already have one
if (self::$show_toc AND Route::name(Request::current()->route()) == "docs/guide")
{
$toc = View::factory('userguide/page-toc')
->set('array', self::$_toc)
->render()
;
if (($offset = strpos($text, '<p>')) !== FALSE)
{
// Insert the page TOC just before the first <p>, which every
// Markdown page should (will?) have.
$text = substr_replace($text, $toc, $offset, 0);
}
}
return $text;
}
} // End Kodoc_Markdown

View File

@@ -0,0 +1,141 @@
<?php defined('SYSPATH') or die('No direct script access.');
/**
* Class method documentation generator.
*
* @package Kohana/Userguide
* @category Base
* @author Kohana Team
* @copyright (c) 2009 Kohana Team
* @license http://kohanaphp.com/license
*/
class Kohana_Kodoc_Method extends Kodoc {
/**
* @var ReflectionMethod The ReflectionMethod for this class
*/
public $method;
/**
* @var array array of Kodoc_Method_Param
*/
public $params;
/**
* @var array the things this function can return
*/
public $return = array();
/**
* @var string the source code for this function
*/
public $source;
public function __construct($class, $method)
{
$this->method = new ReflectionMethod($class, $method);
$this->class = $parent = $this->method->getDeclaringClass();
if ($modifiers = $this->method->getModifiers())
{
$this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
}
do
{
if ($parent->hasMethod($method) AND $comment = $parent->getMethod($method)->getDocComment())
{
// Found a description for this method
break;
}
}
while ($parent = $parent->getParentClass());
list($this->description, $tags) = Kodoc::parse($comment);
if ($file = $this->class->getFileName())
{
$this->source = Kodoc::source($file, $this->method->getStartLine(), $this->method->getEndLine());
}
if (isset($tags['param']))
{
$params = array();
foreach ($this->method->getParameters() as $i => $param)
{
$param = new Kodoc_Method_Param(array($this->method->class, $this->method->name),$i);
if (isset($tags['param'][$i]))
{
preg_match('/^(\S+)(?:\s*(?:\$'.$param->name.'\s*)?(.+))?$/s', $tags['param'][$i], $matches);
$param->type = $matches[1];
if (isset($matches[2]))
{
$param->description = ucfirst($matches[2]);
}
}
$params[] = $param;
}
$this->params = $params;
unset($tags['param']);
}
if (isset($tags['return']))
{
foreach ($tags['return'] as $return)
{
if (preg_match('/^(\S*)(?:\s*(.+?))?$/', $return, $matches))
{
$this->return[] = array($matches[1], isset($matches[2]) ? $matches[2] : '');
}
}
unset($tags['return']);
}
$this->tags = $tags;
}
public function params_short()
{
$out = '';
$required = TRUE;
$first = TRUE;
foreach ($this->params as $param)
{
if ($required AND $param->default AND $first)
{
$out .= '[ '.$param;
$required = FALSE;
$first = FALSE;
}
elseif ($required AND $param->default)
{
$out .= '[, '.$param;
$required = FALSE;
}
elseif ($first)
{
$out .= $param;
$first = FALSE;
}
else
{
$out .= ', '.$param;
}
}
if ( ! $required)
{
$out .= '] ';
}
return $out;
}
} // End Kodoc_Method

View File

@@ -0,0 +1,101 @@
<?php defined('SYSPATH') or die('No direct script access.');
/**
* Class method parameter documentation generator.
*
* @package Kohana/Userguide
* @category Base
* @author Kohana Team
* @copyright (c) 2009 Kohana Team
* @license http://kohanaphp.com/license
*/
class Kohana_Kodoc_Method_Param extends Kodoc {
/**
* @var object ReflectionParameter for this property
*/
public $param;
/**
* @var string name of this var
*/
public $name;
/**
* @var string variable type, retrieved from the comment
*/
public $type;
/**
* @var string default value of this param
*/
public $default;
/**
* @var string description of this parameter
*/
public $description;
/**
* @var boolean is the parameter passed by reference?
*/
public $reference = FALSE;
/**
* @var boolean is the parameter optional?
*/
public $optional = FALSE;
public function __construct($method, $param)
{
$this->param = new ReflectionParameter($method, $param);
$this->name = $this->param->name;
if ($this->param->isDefaultValueAvailable())
{
$this->default = Debug::dump($this->param->getDefaultValue());
}
if ($this->param->isPassedByReference())
{
$this->reference = TRUE;
}
if ($this->param->isOptional())
{
$this->optional = TRUE;
}
}
public function __toString()
{
$display = '';
if ($this->type)
{
$display .= '<small>'.$this->type.'</small> ';
}
if ($this->reference)
{
$display .= '<small><abbr title="passed by reference">&</abbr></small> ';
}
if ($this->description)
{
$display .= '<span class="param" title="'.preg_replace('/\s+/', ' ', $this->description).'">$'.$this->name.'</span> ';
}
else
{
$display .= '$'.$this->name.' ';
}
if ($this->default)
{
$display .= '<small>= '.$this->default.'</small> ';
}
return $display;
}
} // End Kodoc_Method_Param

View File

@@ -0,0 +1,36 @@
<?php defined('SYSPATH') or die('No direct script access.');
/**
* Set Kodoc_Missing::create_class as an autoloading to prevent missing classes
* from crashing the api browser. Classes that are missing a parent will
* extend this class, and get a warning in the API browser.
*
* @package Kohana/Userguide
* @category Undocumented
* @author Kohana Team
* @since 3.0.7
*/
abstract class Kohana_Kodoc_Missing {
/**
* Creates classes when they are otherwise not found.
*
* Kodoc::create_class('ThisClassDoesNotExist');
*
* [!!] All classes created will extend [Kodoc_Missing].
*
* @param string class name
* @return boolean
* @since 3.0.7
*/
public static function create_class($class)
{
if ( ! class_exists($class))
{
// Create a new missing class
eval("class {$class} extends Kodoc_Missing {}");
}
return TRUE;
}
} // End Kohana_Kodoc_Missing

View File

@@ -0,0 +1,90 @@
<?php defined('SYSPATH') or die('No direct script access.');
/**
* Class property documentation generator.
*
* @package Kohana/Userguide
* @category Base
* @author Kohana Team
* @copyright (c) 2009-2012 Kohana Team
* @license http://kohanaphp.com/license
*/
class Kohana_Kodoc_Property extends Kodoc {
/**
* @var object ReflectionProperty
*/
public $property;
/**
* @var string modifiers: public, private, static, etc
*/
public $modifiers = 'public';
/**
* @var string variable type, retrieved from the comment
*/
public $type;
/**
* @var string value of the property
*/
public $value;
/**
* @var string default value of the property
*/
public $default;
public function __construct($class, $property, $default = NULL)
{
$property = new ReflectionProperty($class, $property);
list($description, $tags) = Kodoc::parse($property->getDocComment());
$this->description = $description;
if ($modifiers = $property->getModifiers())
{
$this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
}
if (isset($tags['var']))
{
if (preg_match('/^(\S*)(?:\s*(.+?))?$/s', $tags['var'][0], $matches))
{
$this->type = $matches[1];
if (isset($matches[2]))
{
$this->description = Kodoc_Markdown::markdown($matches[2]);
}
}
}
$this->property = $property;
// Show the value of static properties, but only if they are public or we are php 5.3 or higher and can force them to be accessible
if ($property->isStatic() AND ($property->isPublic() OR version_compare(PHP_VERSION, '5.3', '>=')))
{
// Force the property to be accessible
if (version_compare(PHP_VERSION, '5.3', '>='))
{
$property->setAccessible(TRUE);
}
// Don't debug the entire object, just say what kind of object it is
if (is_object($property->getValue($class)))
{
$this->value = '<pre>object '.get_class($property->getValue($class)).'()</pre>';
}
else
{
$this->value = Debug::vars($property->getValue($class));
}
}
// Store the defult property
$this->default = Debug::vars($default);;
}
} // End Kodoc_Property