/**
* Initialize the logger.
*
* @param string $file May also be the FILE_STDOUT constant to output to STDOUT.
*/
public function __construct($file)
{
// only do the file checks if it is an actual file.
if ($file !== self::FILE_STDOUT) {
// replace APP_ROOT and DATE variables
$file = str_replace(array('{APP_ROOT}', '{DATE}'), array(DocBlox_Core_Abstract::config()->paths->application, date('YmdHis')), $file);
// check if the given file location is writable; if not: output an error
if (!is_writeable(dirname($file))) {
$this->logger = new Zend_Log(new Zend_Log_Writer_Null());
$this->log('The log directory does not appear to be writable; tried to log to: ' . $file . ', disabled logging to file', self::ERR);
$this->filename = null;
return;
}
}
$this->filename = $file;
$this->logger = new Zend_Log(new Zend_Log_Writer_Stream(fopen($file, 'w')));
}
/**
* Merge the config files before population.
*
* @return void
*/
protected function prePopulate()
{
// prevent the loading of configuration files by specifying 'none'.
if (strtolower($this->getConfig()) == 'none') {
return;
}
if ($this->getConfig()) {
// when the configuration parameter is provided; merge that with the basic config
DocBlox_Core_Abstract::config()->merge(new Zend_Config_Xml($this->getConfig()));
} elseif (is_readable('docblox.xml')) {
// when the configuration is not provided; check for the presence of a configuration file in the current directory
// and merge that
DocBlox_Core_Abstract::config()->merge(new Zend_Config_Xml('docblox.xml'));
} elseif (is_readable('docblox.dist.xml')) {
// when no docblox.xml is provided; check for a dist.xml file. Yes, compared to, for example, PHPUnit the xml
// and dist is reversed; this is done on purpose so IDEs have an easier time on it.
DocBlox_Core_Abstract::config()->merge(new Zend_Config_Xml('docblox.dist.xml'));
}
}
/**
* Configuration override for setting the parser visibility
*
* By default it will use the command line options first, and then
* look at the config file if no options have been supplied
*
* @return string
*/
protected function getVisibility()
{
$visibility = $this->__call('getVisibility', array());
if ('' == $visibility) {
$visibility = DocBlox_Core_Abstract::config()->parser->visibility;
}
return $visibility;
}
/**
* Execute the task
*
* @return Docblox
* @throw BuildException
*/
public function execute()
{
if (!class_exists('Parser')) {
if (!$this->getLibraryPath()) {
throw new BuildException('No Docblox library path set');
}
$libraryPath = $this->filterProperties($this->getLibraryPath());
set_include_path(get_include_path() . PATH_SEPARATOR . $libraryPath);
require_once 'markdown.php';
$autoloader = new StandardAutoloader();
$autoloader->registerPrefix('Zend', "{$libraryPath}/Zend")->registerPrefix('DocBlox', "{$libraryPath}/DocBlox")->setFallbackAutoloader(true)->register();
}
$parser = new Parser();
ParserAbstract::$event_dispatcher = new sfEventDispatcher();
if ($this->getForce()) {
$parser->setForced($this->getForce());
}
if ($this->getMarkers()) {
$parser->setMarkers($this->getMarkers());
}
if ($this->getTitle()) {
$parser->setTitle($this->filterProperties($this->getTitle()));
}
if ($this->getValidate()) {
$parser->setValidate($this->getValidate());
}
$files = new Files();
foreach ($this->getFiles() as $file) {
$files->addFile($this->filterProperties($file));
}
$xml = $parser->parseFiles($files);
$transformer = new Transformer();
$transformer->setSource($xml);
if ($this->getParsePrivate()) {
$transformer->setParseprivate($this->getParsePrivate());
}
if ($this->getTarget()) {
$transformer->setTarget($this->filterProperties($this->getTarget()));
}
if ($this->getThemesPath()) {
$transformer->setThemesPath($this->filterProperties($this->getThemesPath()));
} else {
$transformer->setThemesPath(CoreAbstract::config()->paths->themes);
}
if ($this->getTemplates()) {
$transformer->setTemplates($this->getTemplates());
} else {
$transformer->setTemplates(CoreAbstract::config()->transformations->template->name);
}
$transformer->execute();
return $this;
}
/**
* Returns the configuration for DocBlox.
*
* @return DocBlox_Core_Config
*/
public static function config()
{
if (self::$config === null) {
self::$config = new DocBlox_Core_Config(dirname(__FILE__) . '/../../../data/docblox.tpl.xml');
}
return self::$config;
}
/**
* Task entry point
* @see Task::main()
*/
public function main()
{
if (empty($this->destDir)) {
throw new BuildException("You must supply the 'destdir' attribute", $this->getLocation());
}
if (empty($this->filesets)) {
throw new BuildException("You have not specified any files to include (<fileset>)", $this->getLocation());
}
$this->initializeDocBlox();
$xml = $this->parseFiles();
$this->log("Transforming...", Project::MSG_VERBOSE);
$transformer = new DocBlox_Transformer();
$transformer->setTemplatesPath(DocBlox_Core_Abstract::config()->paths->templates);
$transformer->setTemplates(DocBlox_Core_Abstract::config()->transformations->template->name);
$transformer->setSource($xml);
$transformer->setTarget($this->destDir->getAbsolutePath());
$transformer->execute();
}
public function tearDown()
{
DocBlox_Core_Abstract::resetConfig();
}
/**
* Returns the list of markers to scan for and summize in their separate page.
*
* @return string[]
*/
public function getMarkers()
{
if (parent::getMarkers()) {
return explode(',', parent::getMarkers());
}
return DocBlox_Core_Abstract::config()->getArrayFromPath('parser/markers/item');
}
public function testConfig()
{
$this->assertInstanceOf('DocBlox_Core_Config', DocBlox_Core_Abstract::config());
}
/**
* Tests whether an execute call will yield the desired results.
*
* @return void
*/
public function testExecute()
{
DocBlox_Core_Abstract::config()->transformations = array();
$this->fixture = new DocBlox_Transformer();
// when nothing is added; this mock should not be invoked
$transformation = $this->getMock('DocBlox_Transformer_Transformation', array('execute'), array($this->fixture, '', 'Xsl', '', ''));
$transformation->expects($this->never())->method('execute');
$this->fixture->execute();
// when we add this mock; we expect it to be invoked
$transformation = $this->getMock('DocBlox_Transformer_Transformation', array('execute'), array($this->fixture, '', 'Xsl', '', ''));
$transformation->expects($this->once())->method('execute');
$this->fixture->addTransformation($transformation);
$this->fixture->execute();
}
/**
* Returns the name of the current template, or the default.
*
* @return string
*/
public function getTemplate()
{
return parent::getTemplate() ? parent::getTemplate() : DocBlox_Core_Abstract::config()->transformations->template->name;
}
/**
* Executes the transformation process.
*
* @throws Zend_Console_Getopt_Exception
*
* @return void
*/
public function execute()
{
// initialize timer
$timer = microtime(true);
// initialize transformer
$transformer = new DocBlox_Transformer();
$transformer->setThemesPath(DocBlox_Core_Abstract::config()->paths->themes);
$transformer->setTarget($this->getTarget());
$transformer->setSource($this->getSource());
$transformer->setTemplates($this->getTemplate());
$transformer->setParseprivate($this->getParseprivate());
// add links to external docs
$external_class_documentation = DocBlox_Core_Abstract::config()->getArrayFromPath('transformer/external-class-documentation');
$external_class_documentation = !is_numeric(current(array_keys($external_class_documentation))) ? $external_class_documentation = array($external_class_documentation) : $external_class_documentation;
/** @var DocBlox_Core_Config $doc */
foreach ($external_class_documentation as $doc) {
if (empty($doc)) {
continue;
}
$transformer->setExternalClassDoc((string) $doc['prefix'], (string) $doc['uri']);
}
// start the transformation process
if (!$this->getQuiet()) {
echo 'Starting transformation of files (this could take a while depending upon the size of your project)' . PHP_EOL;
}
$transformer->execute();
if (!$this->getQuiet()) {
echo 'Finished transformation in ' . round(microtime(true) - $timer, 2) . ' seconds' . PHP_EOL;
}
}
/**
* Execute the parsing process.
*
* @throws Zend_Console_Getopt_Exception
*
* @return void
*/
public function execute()
{
$files = new DocBlox_Parser_Files();
$files->setAllowedExtensions($this->getExtensions());
$files->setIgnorePatterns($this->getIgnore());
$paths = array_unique($this->getFilename() ? explode(',', $this->getFilename()) : DocBlox_Core_Abstract::config()->getArrayFromPath('files/file'));
$files->addFiles($paths);
$paths = array_unique($this->getDirectory() || !empty($paths) ? explode(',', $this->getDirectory()) : DocBlox_Core_Abstract::config()->getArrayFromPath('files/directory'));
$files->addDirectories($paths);
$parser = new DocBlox_Parser();
$parser->setTitle(htmlentities($this->getTitle()));
$parser->setExistingXml($this->getTarget() . '/structure.xml');
$parser->setForced($this->getForce());
$parser->setMarkers($this->getMarkers());
$parser->setValidate($this->getValidate());
$parser->setVisibility($this->getVisibility());
$parser->setDefaultPackageName($this->getDefaultpackagename());
$parser->setPath($files->getProjectRoot());
try {
// save the generate file to the path given as the 'target' option
file_put_contents($this->getTarget() . '/structure.xml', $parser->parseFiles($files));
} catch (Exception $e) {
if ($e->getCode() === DocBlox_Parser_Exception::NO_FILES_FOUND) {
throw new Zend_Console_Getopt_Exception('No parsable files were found, did you specify any using the -f or -d parameter?');
}
throw new Zend_Console_Getopt_Exception($e->getMessage());
}
}
