root/trunk/classes/phing/Phing.php

<?php
/*
 * $Id$
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * This software consists of voluntary contributions made by many individuals
 * and is licensed under the LGPL. For more information please see
 * <http://phing.info>.
 */

namespace phing;
use phing::system::io::OutputStream;
use phing::system::util::Properties;
use phing::util::StringHelper;
use phing::system::io::File;
use phing::system::io::FileReader;

/**
 * Entry point into Phing.  This class handles the full lifecycle of a build -- from
 * parsing & handling commandline arguments to assembling the project to shutting down
 * and cleaning up in the end.
 *
 * If you are invoking Phing from an external application, this is still
 * the class to use.  Your applicaiton can invoke the start() method, passing
 * any commandline arguments or additional properties.
 *
 * @author    Andreas Aderhold <andi@binarycloud.com>
 * @author    Hans Lellelid <hans@xmpl.org>
 * @version   $Revision: 1.51 $
 * @package   phing
 */
class Phing {

    /** The default build file name */
    const DEFAULT_BUILD_FILENAME = "build.xml";

    /** Our current message output status. Follows Project::MSG_XXX */
    private static $msgOutputLevel = Project::MSG_INFO;

    /** File that we are using for configuration */
    private $buildFile = null;

    /** The build targets */
    private $targets = array();

    /**
     * Set of properties that are passed in from commandline or invoking code.
     * @var Properties
     */
    private static $definedProps;

    /** Names of classes to add as listeners to project */
    private $listeners = array();

    private $loggerClassname = null;

    /** The class to handle input (can be only one). */
    private $inputHandlerClassname;

    /** Indicates if this phing should be run */
    private $readyToRun = false;

    /** Indicates we should only parse and display the project help information */
    private $projectHelp = false;

    /** Used by utility function getResourcePath() */
    private static $importPaths;

    /** System-wide static properties (moved from System) */
    private static $properties = array();

    /** Static system timer. */
    private static $timer;

    /** The current Project */
    private static $currentProject;

    /** Whether to capture PHP errors to buffer. */
    private static $phpErrorCapture = false;

    /** Array of captured PHP errors */
    private static $capturedPhpErrors = array();

    /**
     * @var OUtputStream Stream for standard output.
     */
    private static $out;

    /**
     * @var OutputStream Stream for error output.
     */
    private static $err;

    /**
     * @var boolean Whether we are using a logfile.
     */
    private static $isLogFileUsed = false;
    
    /**
     * Enter description here...
     *
     * @param string $clazz Class that was requested.
     */
    public static function autoload($clazz)
    {
        
        
        $file = str_replace('::', DIRECTORY_SEPARATOR, $clazz) . '.php';
        
        foreach(explode(PATH_SEPARATOR, get_include_path()) as $path) {
            if (is_readable($path . DIRECTORY_SEPARATOR . $file)) {
                // print "Autloaded: $file\n";
                require $path . DIRECTORY_SEPARATOR . $file;
                return true;
            }
        }
        
        print "Failed to autoload: " . $clazz . "\n";
        // print new Exception('trace');
        
        return false;
    }
    
    /**
     * Entry point allowing for more options from other front ends.
     *
     * This method encapsulates the complete build lifecycle.
     *
     * @param array &$args The commandline args passed to phing shell script.
     * @param array $additionalUserProperties   Any additional properties to be passed to Phing (alternative front-end might implement this).
     *                                          These additional properties will be available using the getDefinedProperty() method and will
     *                                          be added to the project's "user" properties.
     * @return void
     * @see execute()
     * @see runBuild()
     */
    public static function start(&$args, $additionalUserProperties = null) {

        try {
            $m = new Phing();
            $m->execute($args);
        } catch (Exception $exc) {
            self::handleLogfile(); // clean up log file before attempting to print message
            $m->printMessage($exc);
            self::halt(-1); // Parameter error
        }

        if ($additionalUserProperties !== null) {
            $keys = $m->additionalUserProperties->keys();
            while(count($keys)) {
                $key = array_shift($keys);
                $property = $m->additionalUserProperties->getProperty($key);
                $m->setDefinedProperty($key, $property);
            }
        }

        try {
            $m->runBuild();
        } catch(Exception $exc) {
            if ($exc instanceof ConfigurationException) {
                if (self::$msgOutputLevel >= Project::MSG_VERBOSE) {
                    self::$out->write($exc->__toString() . PHP_EOL);
                } else {
                    self::$out->write($exc->getMessage() . PHP_EOL);
                }
            }
            self::handleLogfile();
            self::halt(1); // Errors occured
        }

        // everything fine, shutdown
        self::handleLogfile();
        self::halt(0);
    }

    /**
     * Prints the message of the Exception if it's not null.
     * @param Exception $t
     */
    public static function printMessage(Exception $t) {
        if (self::getMsgOutputLevel() <= Project::MSG_DEBUG) {
            self::$err->write($t->__toString());
        } else {
            self::$err->write($t->getMessage());
        }
    }

    /**
     * Sets the stdout and stderr streams if they are not already set.
     */
    private static function initializeOutputStreams() {
        if (self::$out === null) {
            self::$out = new OutputStream(fopen("php://stdout", "w"));
        }
        if (self::$err === null) {
            self::$err = new OutputStream(fopen("php://stderr", "w"));
        }
    }

    /**
     * Sets the stream to use for standard (non-error) output.
     * @param OutputStream $stream The stream to use for standard output.
     */
    public static function setOutputStream(OutputStream $stream) {
        self::$out = $stream;
    }

    /**
     * Gets the stream to use for standard (non-error) output.
     * @return OutputStream
     */
    public static function getOutputStream() {
        return self::$out;
    }

    /**
     * Sets the stream to use for error output.
     * @param OutputStream $stream The stream to use for error output.
     */
    public static function setErrorStream(OutputStream $stream) {
        self::$err = $stream;
    }

    /**
     * Gets the stream to use for error output.
     * @return OutputStream
     */
    public static function getErrorStream() {
        return self::$err;
    }

    /**
     * Close logfiles, if we have been writing to them.
     *
     * @since Phing 2.3.0
     */
    private static function handleLogfile() {
        if (self::$isLogFileUsed) {
            self::$err->close();
            self::$out->close();
        }
    }

    /**
     * Making output level a static property so that this property
     * can be accessed by other parts of the system, enabling
     * us to display more information -- e.g. backtraces -- for "debug" level.
     * @return int
     */
    public static function getMsgOutputLevel() {
        return self::$msgOutputLevel;
    }

    /**
     * Command line entry point. This method kicks off the building
     * of a project object and executes a build using either a given
     * target or the default target.
     *
     * @param array $args Command line args.
     * @return void
     */
    public static function fire($args) {
        self::start($args, null);
    }

    /**
     * Setup/initialize Phing environment from commandline args.
     * @param array $args commandline args passed to phing shell.
     * @return void
     */
    public function execute($args) {

        self::$definedProps = new Properties();
        $this->searchForThis = null;

        // cycle through given args
        for ($i = 0, $argcount = count($args); $i < $argcount; ++$i) {
            // ++$i intentional here, as first param is script name
            $arg = $args[$i];

            if ($arg == "-help" || $arg == "-h") {
                $this->printUsage();
                return;
            } elseif ($arg == "-version" || $arg == "-v") {
                $this->printVersion();
                return;
            } elseif ($arg == "-quiet" || $arg == "-q") {
                self::$msgOutputLevel = Project::MSG_WARN;
            } elseif ($arg == "-verbose") {
                $this->printVersion();
                self::$msgOutputLevel = Project::MSG_VERBOSE;
            } elseif ($arg == "-debug") {
                $this->printVersion();
                self::$msgOutputLevel = Project::MSG_DEBUG;
            } elseif ($arg == "-logfile") {
                try {
                    // see: http://phing.info/trac/ticket/65
                    if (!isset($args[$i+1])) {
                        $msg = "You must specify a log file when using the -logfile argument\n";
                        throw new ConfigurationException($msg);
                    } else {
                        $logFile = new File($args[++$i]);
                        $out = new FileOutputStream($logFile); // overwrite
                        self::setOutputStream($out);
                        self::setErrorStream($out);
                        self::$isLogFileUsed = true;
                    }
                } catch (IOException $ioe) {
                    $msg = "Cannot write on the specified log file. Make sure the path exists and you have write permissions.";
                    throw new ConfigurationException($msg, $ioe);
                }
            } elseif ($arg == "-buildfile" || $arg == "-file" || $arg == "-f") {
                if (!isset($args[$i+1])) {
                    $msg = "You must specify a buildfile when using the -buildfile argument.";
                    throw new ConfigurationException($msg);
                } else {
                    $this->buildFile = new File($args[++$i]);
                }
            } elseif ($arg == "-listener") {
                if (!isset($args[$i+1])) {
                    $msg = "You must specify a listener class when using the -listener argument";
                    throw new ConfigurationException($msg);
                } else {
                    $this->listeners[] = $args[++$i];
                }
            } elseif (StringHelper::startsWith("-D", $arg)) {
                $name = substr($arg, 2);
                $value = null;
                $posEq = strpos($name, "=");
                if ($posEq !== false) {
                    $value = substr($name, $posEq+1);
                    $name  = substr($name, 0, $posEq);
                } elseif ($i < count($args)-1) {
                    $value = $args[++$i];
                }
                self::$definedProps->setProperty($name, $value);
            } elseif ($arg == "-logger") {
                if (!isset($args[$i+1])) {
                    $msg = "You must specify a classname when using the -logger argument";
                    throw new ConfigurationException($msg);
                } else {
                    $this->loggerClassname = $args[++$i];
                }
            } elseif ($arg == "-inputhandler") {
                if ($this->inputHandlerClassname !== null) {
                    throw new ConfigurationException("Only one input handler class may be specified.");
                }
                if (!isset($args[$i+1])) {
                    $msg = "You must specify a classname when using the -inputhandler argument";
                    throw new ConfigurationException($msg);
                } else {
                    $this->inputHandlerClassname = $args[++$i];
                }
            } elseif ($arg == "-projecthelp" || $arg == "-targets" || $arg == "-list" || $arg == "-l" || $arg == "-p") {
                // set the flag to display the targets and quit
                $this->projectHelp = true;
            } elseif ($arg == "-find") {
                // eat up next arg if present, default to build.xml
                if ($i < count($args)-1) {
                    $this->searchForThis = $args[++$i];
                } else {
                    $this->searchForThis = self::DEFAULT_BUILD_FILENAME;
                }
            } elseif (substr($arg,0,1) == "-") {
                // we don't have any more args
                self::$err->write("Unknown argument: $arg");
                self::printUsage();
                return;
            } else {
                // if it's no other arg, it may be the target
                array_push($this->targets, $arg);
            }
        }

        // if buildFile was not specified on the command line,
        if ($this->buildFile === null) {
            // but -find then search for it
            if ($this->searchForThis !== null) {
                $this->buildFile = $this->_findBuildFile(self::getProperty("user.dir"), $this->searchForThis);
            } else {
                $this->buildFile = new File(self::DEFAULT_BUILD_FILENAME);
            }
        }
        // make sure buildfile exists
        if (!$this->buildFile->exists()) {
            throw new ConfigurationException("Buildfile: " . $this->buildFile->__toString() . " does not exist!");
        }

        // make sure it's not a directory
        if ($this->buildFile->isDirectory()) {
            throw new ConfigurationException("Buildfile: " . $this->buildFile->__toString() . " is a dir!");
        }

        $this->readyToRun = true;
    }

    /**
     * Helper to get the parent file for a given file.
     *
     * @param File $file
     * @return File Parent file or null if none
     */
    private function _getParentFile(File $file) {
        $filename = $file->getAbsolutePath();
        $file     = new File($filename);
        $filename = $file->getParent();
        return ($filename === null) ? null : new File($filename);
    }

    /**
     * Search parent directories for the build file.
     *
     * Takes the given target as a suffix to append to each
     * parent directory in search of a build file.  Once the
     * root of the file-system has been reached an exception
     * is thrown.
     *
     * @param string $start Start file path.
     * @param string $suffix Suffix filename to look for in parents.
     * @return File A handle to the build file
     *
     * @throws BuildException    Failed to locate a build file
     */
    private function _findBuildFile($start, $suffix) {
        $startf = new File($start);
        $parent = new File($startf->getAbsolutePath());
        $file   = new File($parent, $suffix);

        // check if the target file exists in the current directory
        while (!$file->exists()) {
            // change to parent directory
            $parent = $this->_getParentFile($parent);

            // if parent is null, then we are at the root of the fs,
            // complain that we can't find the build file.
            if ($parent === null) {
                throw new ConfigurationException("Could not locate a build file!");
            }
            // refresh our file handle
            $file = new File($parent, $suffix);
        }
        return $file;
    }

    /**
     * Executes the build.
     * @return void
     */
    function runBuild() {

        if (!$this->readyToRun) {
            return;
        }

        $project = new Project();

        self::setCurrentProject($project);
        //set_error_handler(array('phing::Phing', 'handlePhpError'));

        $error = null;

        $this->addBuildListeners($project);
        $this->addInputHandler($project);

        // set this right away, so that it can be used in logging.
        $project->setUserProperty("phing.file", $this->buildFile->getAbsolutePath());

        try {
            $project->fireBuildStarted();
            $project->init();
        } catch (Exception $exc) {
            $project->fireBuildFinished($exc);
            throw $exc;
        }

        $project->setUserProperty("phing.version", $this->getPhingVersion());

        $e = self::$definedProps->keys();
        while (count($e)) {
            $arg   = (string) array_shift($e);
            $value = (string) self::$definedProps->getProperty($arg);
            $project->setUserProperty($arg, $value);
        }
        unset($e);

        $project->setUserProperty("phing.file", $this->buildFile->getAbsolutePath());

        // first use the Configurator to create the project object
        // from the given build file.

        try {
            phing::parser::ProjectConfigurator::configureProject($project, $this->buildFile);
        } catch (Exception $exc) {
            $project->fireBuildFinished($exc);
            restore_error_handler();
            self::unsetCurrentProject();
            throw $exc;
        }

        // make sure that we have a target to execute
        if (count($this->targets) === 0) {
            $this->targets[] = $project->getDefaultTarget();
        }

        // execute targets if help param was not given
        if (!$this->projectHelp) {

            try {
                $project->executeTargets($this->targets);
            } catch (Exception $exc) {
                $project->fireBuildFinished($exc);
                restore_error_handler();
                self::unsetCurrentProject();
                throw $exc;
            }
        }
        // if help is requested print it
        if ($this->projectHelp) {
            try {
                $this->printDescription($project);
                $this->printTargets($project);