Merging latest master

PHPCI/Application.php

@@ -22,6 +22,9 @@ use PHPCI\Model\Build;
 */
 class Application extends b8\Application
 {
+    /**
+     * Initialise PHPCI - Handles session verification, routing, etc.
+     */
     public function init()
     {
         $request =& $this->request;
@@ -67,6 +70,7 @@ class Application extends b8\Application
         $this->router->clearRoutes();
         $this->router->register($route, $opts, $routeHandler);
     }
+
     /**
     * Handle an incoming web request.
     */
@@ -102,6 +106,11 @@ class Application extends b8\Application
         return $this->response;
     }
 
+    /**
+     * Loads a particular controller, and injects our layout view into it.
+     * @param $class
+     * @return mixed
+     */
     protected function loadController($class)
     {
         $controller = parent::loadController($class);
@@ -112,6 +121,10 @@ class Application extends b8\Application
         return $controller;
     }
 
+    /**
+     * Injects variables into the layout before rendering it.
+     * @param View $layout
+     */
     protected function setLayoutVariables(View &$layout)
     {
         /** @var \PHPCI\Store\ProjectStore $projectStore */

PHPCI/Builder.php

@@ -252,6 +252,10 @@ class Builder implements LoggerAwareInterface
         return $this->commandExecutor->getLastOutput();
     }
 
+    /**
+     * Specify whether exec output should be logged.
+     * @param bool $enableLog
+     */
     public function logExecOutput($enableLog = true)
     {
         $this->commandExecutor->logExecOutput = $enableLog;
@@ -322,6 +326,12 @@ class Builder implements LoggerAwareInterface
         $this->buildLogger->setLogger($logger);
     }
 
+    /**
+     * Write to the build log.
+     * @param $message
+     * @param string $level
+     * @param array $context
+     */
     public function log($message, $level = LogLevel::INFO, $context = array())
     {
         $this->buildLogger->log($message, $level, $context);

PHPCI/Controller.php

@@ -14,6 +14,10 @@ use b8\Http\Request;
 use b8\Http\Response;
 use b8\View;
 
+/**
+ * PHPCI Base Controller
+ * @package PHPCI
+ */
 class Controller extends \b8\Controller
 {
     /**
@@ -26,11 +30,19 @@ class Controller extends \b8\Controller
      */
     protected $view;
 
+    /**
+     * Initialise the controller.
+     */
     public function init()
     {
         // Extended by actual controllers.
     }
 
+    /**
+     * @param Config $config
+     * @param Request $request
+     * @param Response $response
+     */
     public function __construct(Config $config, Request $request, Response $response)
     {
         parent::__construct($config, $request, $response);
@@ -40,6 +52,9 @@ class Controller extends \b8\Controller
         $this->setControllerView();
     }
 
+    /**
+     * Set the view that this controller should use.
+     */
     protected function setControllerView()
     {
         if (View::exists($this->className)) {
@@ -49,6 +64,10 @@ class Controller extends \b8\Controller
         }
     }
 
+    /**
+     * Set the view that this controller action should use.
+     * @param $action
+     */
     protected function setView($action)
     {
         if (View::exists($this->className . '/' . $action)) {
@@ -56,6 +75,12 @@ class Controller extends \b8\Controller
         }
     }
 
+    /**
+     * Handle the incoming request.
+     * @param $action
+     * @param $actionParams
+     * @return \b8\b8\Http\Response|Response
+     */
     public function handleAction($action, $actionParams)
     {
         $this->setView($action);

PHPCI/Controller/BuildController.php

@@ -34,7 +34,10 @@ class BuildController extends \PHPCI\Controller
      * @var \PHPCI\Service\BuildService
      */
     protected $buildService;
-    
+
+    /**
+     * Initialise the controller, set up stores and services.
+     */
     public function init()
     {
         $this->buildStore = b8\Store\Factory::getStore('Build');
@@ -78,6 +81,10 @@ class BuildController extends \PHPCI\Controller
         $this->layout->nav = $nav;
     }
 
+    /**
+     * Returns an array of the JS plugins to include.
+     * @return array
+     */
     protected function getUiPlugins()
     {
         $rtn = array();
@@ -183,6 +190,9 @@ class BuildController extends \PHPCI\Controller
         return $log;
     }
 
+    /**
+     * Allows the UI to poll for the latest running and pending builds.
+     */
     public function latest()
     {
         $rtn = array(
@@ -195,6 +205,11 @@ class BuildController extends \PHPCI\Controller
         }
     }
 
+    /**
+     * Formats a list of builds into rows suitable for the dropdowns in the PHPCI header bar.
+     * @param $builds
+     * @return array
+     */
     protected function formatBuilds($builds)
     {
         Project::$sleepable = array('id', 'title', 'reference', 'type');

PHPCI/Controller/BuildStatusController.php

@@ -30,6 +30,9 @@ class BuildStatusController extends \PHPCI\Controller
     protected $projectStore;
     protected $buildStore;
 
+    /**
+     * Initialise the controller, set up stores and services.
+     */
     public function init()
     {
         $this->response->disableLayout();
@@ -79,6 +82,12 @@ class BuildStatusController extends \PHPCI\Controller
         die(file_get_contents('http://img.shields.io/badge/build-' . $status . '-' . $color . '.svg'));
     }
 
+    /**
+     * View the public status page of a given project, if enabled.
+     * @param $projectId
+     * @return string
+     * @throws \b8\Exception\HttpException\NotFoundException
+     */
     public function view($projectId)
     {
         $project = $this->projectStore->getById($projectId);

PHPCI/Controller/HomeController.php

@@ -32,6 +32,9 @@ class HomeController extends \PHPCI\Controller
      */
     protected $projectStore;
 
+    /**
+     * Initialise the controller, set up stores and services.
+     */
     public function init()
     {
         $this->buildStore      = b8\Store\Factory::getStore('Build');
@@ -68,12 +71,20 @@ class HomeController extends \PHPCI\Controller
         die($this->getLatestBuildsHtml());
     }
 
+    /**
+     * Ajax request for the project overview section of the dashboard.
+     */
     public function summary()
     {
         $projects = $this->projectStore->getWhere(array(), 50, 0, array(), array('title' => 'ASC'));
         die($this->getSummaryHtml($projects));
     }
 
+    /**
+     * Generate the HTML for the project overview section of the dashboard.
+     * @param $projects
+     * @return string
+     */
     protected function getSummaryHtml($projects)
     {
         $summaryBuilds = array();

PHPCI/Controller/PluginController.php

@@ -43,6 +43,10 @@ class PluginController extends \PHPCI\Controller
     protected $canInstall;
     protected $composerPath;
 
+    /**
+     * List all enabled plugins, installed and recommend packages.
+     * @return string
+     */
     public function index()
     {
         $this->requireAdmin();
@@ -69,6 +73,9 @@ class PluginController extends \PHPCI\Controller
         return $this->view->render();
     }
 
+    /**
+     * Remove a given package.
+     */
     public function remove()
     {
         $this->requireAdmin();
@@ -88,6 +95,9 @@ class PluginController extends \PHPCI\Controller
         die;
     }
 
+    /**
+     * Install a given package.
+     */
     public function install()
     {
         $this->requireAdmin();
@@ -103,6 +113,10 @@ class PluginController extends \PHPCI\Controller
         die;
     }
 
+    /**
+     * Get the json-decoded contents of the composer.json file.
+     * @return mixed
+     */
     protected function getComposerJson()
     {
         $json = file_get_contents(APPLICATION_PATH . 'composer.json');
@@ -125,6 +139,11 @@ class PluginController extends \PHPCI\Controller
         file_put_contents(APPLICATION_PATH . 'composer.json', $json);
     }
 
+    /**
+     * Find a system binary.
+     * @param $binary
+     * @return null|string
+     */
     protected function findBinary($binary)
     {
         if (is_string($binary)) {
@@ -153,6 +172,9 @@ class PluginController extends \PHPCI\Controller
         return null;
     }
 
+    /**
+     * Perform a search on packagist.org.
+     */
     public function packagistSearch()
     {
         $searchQuery = $this->getParam('q', '');
@@ -163,6 +185,9 @@ class PluginController extends \PHPCI\Controller
         die(json_encode($res['body']));
     }
 
+    /**
+     * Look up available versions of a given package on packagist.org
+     */
     public function packagistVersions()
     {
         $name = $this->getParam('p', '');

PHPCI/Controller/ProjectController.php

@@ -52,6 +52,9 @@ class ProjectController extends \PHPCI\Controller
      */
     protected $buildService;
 
+    /**
+     * Initialise the controller, set up stores and services.
+     */
     public function init()
     {
         $this->buildStore = Store\Factory::getStore('Build');
@@ -366,6 +369,11 @@ class ProjectController extends \PHPCI\Controller
         die(json_encode($github->getRepositories()));
     }
 
+    /**
+     * Get the validator to use to check project references.
+     * @param $values
+     * @return callable
+     */
     protected function getReferenceValidator($values)
     {
         return function ($val) use ($values) {

PHPCI/Controller/SessionController.php

@@ -26,6 +26,9 @@ class SessionController extends \PHPCI\Controller
      */
     protected $userStore;
 
+    /**
+     * Initialise the controller, set up stores and services.
+     */
     public function init()
     {
         $this->response->disableLayout();
@@ -93,6 +96,10 @@ class SessionController extends \PHPCI\Controller
         die;
     }
 
+    /**
+     * Allows the user to request a password reset email.
+     * @return string
+     */
     public function forgotPassword()
     {
         if ($this->request->getMethod() == 'POST') {
@@ -121,6 +128,12 @@ class SessionController extends \PHPCI\Controller
         return $this->view->render();
     }
 
+    /**
+     * Allows the user to change their password after a password reset email.
+     * @param $userId
+     * @param $key
+     * @return string
+     */
     public function resetPassword($userId, $key)
     {
         $user = $this->userStore->getById($userId);
@@ -148,6 +161,10 @@ class SessionController extends \PHPCI\Controller
         return $this->view->render();
     }
 
+    /**
+     * Get the URL the user was trying to go to prior to being asked to log in.
+     * @return string
+     */
     protected function getLoginRedirect()
     {
         $rtn = PHPCI_URL;

PHPCI/Controller/SettingsController.php

@@ -28,6 +28,9 @@ class SettingsController extends Controller
 {
     protected $settings;
 
+    /**
+     * Initialise the controller, set up stores and services.
+     */
     public function init()
     {
         parent::init();
@@ -37,6 +40,10 @@ class SettingsController extends Controller
         $this->settings = $parser->parse($yaml);
     }
 
+    /**
+     * Display settings forms.
+     * @return string
+     */
     public function index()
     {
         $this->requireAdmin();
@@ -66,6 +73,9 @@ class SettingsController extends Controller
         return $this->view->render();
     }
 
+    /**
+     * Save Github settings.
+     */
     public function github()
     {
         $this->requireAdmin();
@@ -83,6 +93,9 @@ class SettingsController extends Controller
         die;
     }
 
+    /**
+     * Save email settings.
+     */
     public function email()
     {
         $this->requireAdmin();
@@ -101,6 +114,9 @@ class SettingsController extends Controller
         die;
     }
 
+    /**
+     * Save build settings.
+     */
     public function build()
     {
         $this->requireAdmin();
@@ -164,6 +180,10 @@ class SettingsController extends Controller
         }
     }
 
+    /**
+     * Get the Github settings form.
+     * @return Form
+     */
     protected function getGithubForm()
     {
         $form = new Form();
@@ -203,6 +223,11 @@ class SettingsController extends Controller
         return $form;
     }
 
+    /**
+     * Get the email settings form.
+     * @param array $values
+     * @return Form
+     */
     protected function getEmailForm($values = array())
     {
         $form = new Form();
@@ -273,6 +298,11 @@ class SettingsController extends Controller
         return $form;
     }
 
+    /**
+     * Call Github API for our Github user object.
+     * @param $token
+     * @return mixed
+     */
     protected function getGithubUser($token)
     {
         $http = new HttpClient('https://api.github.com');
@@ -281,11 +311,20 @@ class SettingsController extends Controller
         return $user['body'];
     }
 
+    /**
+     * Check if we can write the PHPCI config file.
+     * @return bool
+     */
     protected function canWriteConfig()
     {
         return is_writeable(APPLICATION_PATH . 'PHPCI/config.yml');
     }
 
+    /**
+     * Get the Build settings form.
+     * @param array $values
+     * @return Form
+     */
     protected function getBuildForm($values = array())
     {
         $form = new Form();

PHPCI/Controller/UserController.php

@@ -36,6 +36,9 @@ class UserController extends Controller
      */
     protected $userService;
 
+    /**
+     * Initialise the controller, set up stores and services.
+     */
     public function init()
     {
         $this->userStore = b8\Store\Factory::getStore('User');
@@ -55,6 +58,10 @@ class UserController extends Controller
         return $this->view->render();
     }
 
+    /**
+     * Allows the user to edit their profile.
+     * @return string
+     */
     public function profile()
     {
         $user = $_SESSION['phpci_user'];

PHPCI/Controller/WebhookController.php

@@ -40,6 +40,9 @@ class WebhookController extends \PHPCI\Controller
      */
     protected $buildService;
 
+    /**
+     * Initialise the controller, set up stores and services.
+     */
     public function init()
     {
         $this->buildStore = Store\Factory::getStore('Build');
@@ -143,6 +146,11 @@ class WebhookController extends \PHPCI\Controller
         die('This request type is not supported, this is not an error.');
     }
 
+    /**
+     * Handle the payload when Github sends a commit webhook.
+     * @param $project
+     * @param array $payload
+     */
     protected function githubCommitRequest($project, array $payload)
     {
         // Github sends a payload when you close a pull request with a
@@ -182,6 +190,11 @@ class WebhookController extends \PHPCI\Controller
         die('OK');
     }
 
+    /**
+     * Handle the payload when Github sends a Pull Request webhook.
+     * @param $projectId
+     * @param array $payload
+     */
     protected function githubPullRequest($projectId, array $payload)
     {
         // We only want to know about open pull requests:
@@ -262,6 +275,17 @@ class WebhookController extends \PHPCI\Controller
         die('OK');
     }
 
+    /**
+     * Wrapper for creating a new build.
+     * @param $projectId
+     * @param $commitId
+     * @param $branch
+     * @param $committer
+     * @param $commitMessage
+     * @param null $extra
+     * @return bool
+     * @throws \Exception
+     */
     protected function createBuild($projectId, $commitId, $branch, $committer, $commitMessage, $extra = null)
     {
         // Check if a build already exists for this commit ID:

PHPCI/Helper/BaseCommandExecutor.php

@@ -13,6 +13,10 @@ use \PHPCI\Logging\BuildLogger;
 use Psr\Log\LogLevel;
 use PHPCI\Helper\Lang;
 
+/**
+ * Handles running system commands with variables.
+ * @package PHPCI\Helper
+ */
 abstract class BaseCommandExecutor implements CommandExecutor
 {
     /**

PHPCI/Helper/Build.php

@@ -17,6 +17,11 @@ namespace PHPCI\Helper;
  */
 class Build
 {
+    /**
+     * Returns a more human-friendly version of a plugin name.
+     * @param $name
+     * @return mixed
+     */
     public function formatPluginName($name)
     {
         return str_replace('Php', 'PHP', ucwords(str_replace('_', ' ', $name)));

PHPCI/Helper/BuildInterpolator.php

@@ -11,6 +11,10 @@ namespace PHPCI\Helper;
 
 use PHPCI\Model\Build;
 
+/**
+ * The BuildInterpolator class replaces variables in a string with build-specific information.
+ * @package PHPCI\Helper
+ */
 class BuildInterpolator
 {
     /**

PHPCI/Helper/Email.php

@@ -12,6 +12,10 @@ namespace PHPCI\Helper;
 use b8\Config;
 use PHPCI\Helper\MailerFactory;
 
+/**
+ * Helper class for sending emails using PHPCI's email configuration.
+ * @package PHPCI\Helper
+ */
 class Email
 {
     const DEFAULT_FROM = 'PHPCI <no-reply@phptesting.org>';
@@ -23,11 +27,20 @@ class Email
     protected $isHtml = false;
     protected $config;
 
+    /**
+     * Create a new email object.
+     */
     public function __construct()
     {
         $this->config = Config::getInstance();
     }
 
+    /**
+     * Set the email's To: header.
+     * @param string $email
+     * @param string|null $name
+     * @return $this
+     */
     public function setEmailTo($email, $name = null)
     {
         $this->emailTo[$email] = $name;
@@ -35,6 +48,12 @@ class Email
         return $this;
     }
 
+    /**
+     * Add an address to the email's CC header.
+     * @param string $email
+     * @param string|null $name
+     * @return $this
+     */
     public function addCc($email, $name = null)
     {
         $this->emailCc[$email] = $name;
@@ -42,6 +61,11 @@ class Email
         return $this;
     }
 
+    /**
+     * Set the email subject.
+     * @param string $subject
+     * @return $this
+     */
     public function setSubject($subject)
     {
         $this->subject = $subject;
@@ -49,6 +73,11 @@ class Email
         return $this;
     }
 
+    /**
+     * Set the email body.
+     * @param string $body
+     * @return $this
+     */
     public function setBody($body)
     {
         $this->body = $body;
@@ -56,6 +85,11 @@ class Email
         return $this;
     }
 
+    /**
+     * Set whether or not the email body is HTML.
+     * @param bool $isHtml
+     * @return $this
+     */
     public function setIsHtml($isHtml = false)
     {
         $this->isHtml = $isHtml;
@@ -63,6 +97,10 @@ class Email
         return $this;
     }
 
+    /**
+     * Send the email.
+     * @return bool|int
+     */
     public function send()
     {
         $smtpServer = $this->config->get('phpci.email_settings.smtp_address');
@@ -74,6 +112,10 @@ class Email
         }
     }
 
+    /**
+     * Sends the email via the built in PHP mail() function.
+     * @return bool
+     */
     protected function sendViaMail()
     {
         $headers = '';
@@ -100,6 +142,10 @@ class Email
         return mail($emailTo, $this->subject, $this->body, $headers);
     }
 
+    /**
+     * Sends the email using SwiftMailer.
+     * @return int
+     */
     protected function sendViaSwiftMailer()
     {
         $factory = new MailerFactory($this->config->get('phpci'));
@@ -121,6 +167,10 @@ class Email
         return $mailer->send($message);
     }
 
+    /**
+     * Get the from address to use for the email.
+     * @return mixed|string
+     */
     protected function getFrom()
     {
         $email = $this->config->get('phpci.email_settings.from_address', self::DEFAULT_FROM);

PHPCI/Helper/Github.php

@@ -13,8 +13,18 @@ use b8\Cache;
 use b8\Config;
 use b8\HttpClient;
 
+/**
+ * The Github Helper class provides some Github API call functionality.
+ * @package PHPCI\Helper
+ */
 class Github
 {
+    /**
+     * Make a request to the Github API.
+     * @param $url
+     * @param $params
+     * @return mixed
+     */
     public function makeRequest($url, $params)
     {
         $http = new HttpClient('https://api.github.com');

PHPCI/Helper/MailerFactory.php

@@ -9,7 +9,10 @@
 
 namespace PHPCI\Helper;
 
-
+/**
+ * Class MailerFactory helps to set up and configure a SwiftMailer object.
+ * @package PHPCI\Helper
+ */
 class MailerFactory
 {
     /**
@@ -17,8 +20,16 @@ class MailerFactory
      */
     protected $emailConfig;
 
-    public function __construct($config = null)
+    /**
+     * Set the mailer factory configuration.
+     * @param array $config
+     */
+    public function __construct($config = array())
     {
+        if (!is_array($config)) {
+            $config = array();
+        }
+
         $this->emailConfig  = isset($config['email_settings']) ? $config['email_settings'] : array();
     }
 
@@ -48,6 +59,11 @@ class MailerFactory
         return \Swift_Mailer::newInstance($transport);
     }
 
+    /**
+     * Return a specific configuration value by key.
+     * @param $configName
+     * @return null|string
+     */
     public function getMailConfig($configName)
     {
         if (isset($this->emailConfig[$configName]) && $this->emailConfig[$configName] != "") {

PHPCI/Helper/SshKey.php

@@ -9,8 +9,16 @@
 
 namespace PHPCI\Helper;
 
+/**
+ * Helper class for dealing with SSH keys.
+ * @package PHPCI\Helper
+ */
 class SshKey
 {
+    /**
+     * Uses ssh-keygen to generate a public/private key pair.
+     * @return array
+     */
     public function generate()
     {
         $tempPath = sys_get_temp_dir() . '/';
@@ -49,6 +57,10 @@ class SshKey
         return $return;
     }
 
+    /**
+     * Checks whether or not we can generate keys, by quietly test running ssh-keygen.
+     * @return bool
+     */
     public function canGenerateKeys()
     {
         $keygen = @shell_exec('ssh-keygen -h');

PHPCI/Helper/UnixCommandExecutor.php

@@ -9,8 +9,17 @@
 
 namespace PHPCI\Helper;
 
+/**
+ * Unix/Linux specific extension of the CommandExecutor class.
+ * @package PHPCI\Helper
+ */
 class UnixCommandExecutor extends BaseCommandExecutor
 {
+    /**
+     * Uses 'which' to find a system binary by name.
+     * @param string $binary
+     * @return null|string
+     */
     protected function findGlobalBinary($binary)
     {
         return trim(shell_exec('which ' . $binary));

PHPCI/Helper/User.php

@@ -17,6 +17,12 @@ namespace PHPCI\Helper;
 */
 class User
 {
+    /**
+     * Proxies method calls through to the current active user model.
+     * @param $method
+     * @param array $params
+     * @return mixed|null
+     */
     public function __call($method, $params = array())
     {
         $user = $_SESSION['phpci_user'];

PHPCI/Helper/WindowsCommandExecutor.php

@@ -9,8 +9,17 @@
 
 namespace PHPCI\Helper;
 
+/**
+ * Windows-specific extension of the CommandExecutor class.
+ * @package PHPCI\Helper
+ */
 class WindowsCommandExecutor extends BaseCommandExecutor
 {
+    /**
+     * Use 'where' on Windows to find a binary, rather than 'which'
+     * @param string $binary
+     * @return null|string
+     */
     protected function findGlobalBinary($binary)
     {
         return trim(shell_exec('where ' . $binary));

PHPCI/Logging/BuildDBLogHandler.php

@@ -13,6 +13,10 @@ use b8\Store\Factory;
 use Monolog\Handler\AbstractProcessingHandler;
 use PHPCI\Model\Build;
 
+/**
+ * Class BuildDBLogHandler writes the build log to the database.
+ * @package PHPCI\Logging
+ */
 class BuildDBLogHandler extends AbstractProcessingHandler
 {
     /**
@@ -22,6 +26,11 @@ class BuildDBLogHandler extends AbstractProcessingHandler
 
     protected $logValue;
 
+    /**
+     * @param Build $build
+     * @param bool $level
+     * @param bool $bubble
+     */
     public function __construct(
         Build $build,
         $level = LogLevel::INFO,
@@ -33,6 +42,10 @@ class BuildDBLogHandler extends AbstractProcessingHandler
         $this->logValue = $build->getLog();
     }
 
+    /**
+     * Write a log entry to the build log.
+     * @param array $record
+     */
     protected function write(array $record)
     {
         $message = (string)$record['message'];

PHPCI/Logging/BuildLogger.php

@@ -14,6 +14,10 @@ use Psr\Log\LoggerAwareInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\LogLevel;
 
+/**
+ * Class BuildLogger
+ * @package PHPCI\Logging
+ */
 class BuildLogger implements LoggerAwareInterface
 {
     /**
@@ -26,6 +30,11 @@ class BuildLogger implements LoggerAwareInterface
      */
     protected $build;
 
+    /**
+     * Set up the BuildLogger class.
+     * @param LoggerInterface $logger
+     * @param Build $build
+     */
     public function __construct(LoggerInterface $logger, Build $build)
     {
         $this->logger = $logger;

PHPCI/Logging/Handler.php

@@ -11,6 +11,10 @@ namespace PHPCI\Logging;
 
 use Psr\Log\LoggerInterface;
 
+/**
+ * Base Log Handler
+ * @package PHPCI\Logging
+ */
 class Handler
 {
     /**
@@ -33,11 +37,18 @@ class Handler
      */
     protected $logger;
 
+    /**
+     * @param LoggerInterface $logger
+     */
     public function __construct(LoggerInterface $logger = null)
     {
         $this->logger = $logger;
     }
 
+    /**
+     * Register a new log handler.
+     * @param LoggerInterface $logger
+     */
     public static function register(LoggerInterface $logger = null)
     {
         $handler = new static($logger);
@@ -122,6 +133,10 @@ class Handler
         $this->log($exception);
     }
 
+    /**
+     * Write to the build log.
+     * @param \Exception $exception
+     */
     protected function log(\Exception $exception)
     {
         if (null !== $this->logger) {

PHPCI/Logging/LoggedBuildContextTidier.php

@@ -11,8 +11,15 @@ namespace PHPCI\Logging;
 
 use PHPCI\Model\Build;
 
+/**
+ * Class LoggedBuildContextTidier cleans up build log entries.
+ * @package PHPCI\Logging
+ */
 class LoggedBuildContextTidier
 {
+    /**
+     * @return array
+     */
     public function __invoke()
     {
         return $this->tidyLoggedBuildContext(func_get_arg(0));

PHPCI/Logging/LoggerConfig.php

@@ -11,11 +11,13 @@ namespace PHPCI\Logging;
 
 use Monolog\Logger;
 
+/**
+ * Class LoggerConfig
+ * @package PHPCI\Logging
+ */
 class LoggerConfig
 {
-
     const KEY_ALWAYS_LOADED = "_";
-
     private $config;
 
     /**
@@ -59,6 +61,11 @@ class LoggerConfig
         return new Logger($name, $handlers);
     }
 
+    /**
+     * Return an array of enabled log handlers.
+     * @param $key
+     * @return array|mixed
+     */
     protected function getHandlers($key)
     {
         $handlers = array();

PHPCI/Logging/OutputLogHandler.php

@@ -13,6 +13,10 @@ use Monolog\Handler\AbstractProcessingHandler;
 use Psr\Log\LogLevel;
 use Symfony\Component\Console\Output\OutputInterface;
 
+/**
+ * Class OutputLogHandler outputs the build log to the terminal.
+ * @package PHPCI\Logging
+ */
 class OutputLogHandler extends AbstractProcessingHandler
 {
     /**
@@ -20,6 +24,11 @@ class OutputLogHandler extends AbstractProcessingHandler
      */
     protected $output;
 
+    /**
+     * @param OutputInterface $output
+     * @param bool|string $level
+     * @param bool $bubble
+     */
     public function __construct(
         OutputInterface $output,
         $level = LogLevel::INFO,
@@ -29,6 +38,10 @@ class OutputLogHandler extends AbstractProcessingHandler
         $this->output = $output;
     }
 
+    /**
+     * Write a log entry to the terminal.
+     * @param array $record
+     */
     protected function write(array $record)
     {
         $this->output->writeln((string)$record['formatted']);

PHPCI/Model.php

@@ -9,6 +9,10 @@
 
 namespace PHPCI;
 
+/**
+ * PHPCI Base Model.
+ * @package PHPCI
+ */
 abstract class Model extends \b8\Model
 {
 

PHPCI/Model/Base/ProjectBase.php

@@ -38,11 +38,11 @@ class ProjectBase extends Model
         'reference' => null,
         'branch' => null,
         'ssh_private_key' => null,
+        'ssh_public_key' => null,
         'type' => null,
         'access_information' => null,
         'last_commit' => null,
         'build_config' => null,
-        'ssh_public_key' => null,
         'allow_public_status' => null,
     );
 
@@ -56,11 +56,11 @@ class ProjectBase extends Model
         'reference' => 'getReference',
         'branch' => 'getBranch',
         'ssh_private_key' => 'getSshPrivateKey',
+        'ssh_public_key' => 'getSshPublicKey',
         'type' => 'getType',
         'access_information' => 'getAccessInformation',
         'last_commit' => 'getLastCommit',
         'build_config' => 'getBuildConfig',
-        'ssh_public_key' => 'getSshPublicKey',
         'allow_public_status' => 'getAllowPublicStatus',
 
         // Foreign key getters:
@@ -76,11 +76,11 @@ class ProjectBase extends Model
         'reference' => 'setReference',
         'branch' => 'setBranch',
         'ssh_private_key' => 'setSshPrivateKey',
+        'ssh_public_key' => 'setSshPublicKey',
         'type' => 'setType',
         'access_information' => 'setAccessInformation',
         'last_commit' => 'setLastCommit',
         'build_config' => 'setBuildConfig',
-        'ssh_public_key' => 'setSshPublicKey',
         'allow_public_status' => 'setAllowPublicStatus',
 
         // Foreign key setters:
@@ -117,6 +117,11 @@ class ProjectBase extends Model
             'nullable' => true,
             'default' => null,
         ),
+        'ssh_public_key' => array(
+            'type' => 'text',
+            'nullable' => true,
+            'default' => null,
+        ),
         'type' => array(
             'type' => 'varchar',
             'length' => 50,
@@ -139,11 +144,6 @@ class ProjectBase extends Model
             'nullable' => true,
             'default' => null,
         ),
-        'ssh_public_key' => array(
-            'type' => 'text',
-            'nullable' => true,
-            'default' => null,
-        ),
         'allow_public_status' => array(
             'type' => 'int',
             'length' => 11,
@@ -224,6 +224,18 @@ class ProjectBase extends Model
         return $rtn;
     }
 
+    /**
+    * Get the value of SshPublicKey / ssh_public_key.
+    *
+    * @return string
+    */
+    public function getSshPublicKey()
+    {
+        $rtn    = $this->data['ssh_public_key'];
+
+        return $rtn;
+    }
+
     /**
     * Get the value of Type / type.
     *
@@ -272,18 +284,6 @@ class ProjectBase extends Model
         return $rtn;
     }
 
-    /**
-    * Get the value of SshPublicKey / ssh_public_key.
-    *
-    * @return string
-    */
-    public function getSshPublicKey()
-    {
-        $rtn    = $this->data['ssh_public_key'];
-
-        return $rtn;
-    }
-
     /**
     * Get the value of AllowPublicStatus / allow_public_status.
     *
@@ -394,6 +394,24 @@ class ProjectBase extends Model
         $this->_setModified('ssh_private_key');
     }
 
+    /**
+    * Set the value of SshPublicKey / ssh_public_key.
+    *
+    * @param $value string
+    */
+    public function setSshPublicKey($value)
+    {
+        $this->_validateString('SshPublicKey', $value);
+
+        if ($this->data['ssh_public_key'] === $value) {
+            return;
+        }
+
+        $this->data['ssh_public_key'] = $value;
+
+        $this->_setModified('ssh_public_key');
+    }
+
     /**
     * Set the value of Type / type.
     *
@@ -468,24 +486,6 @@ class ProjectBase extends Model
         $this->_setModified('build_config');
     }
 
-    /**
-    * Set the value of SshPublicKey / ssh_public_key.
-    *
-    * @param $value string
-    */
-    public function setSshPublicKey($value)
-    {
-        $this->_validateString('SshPublicKey', $value);
-
-        if ($this->data['ssh_public_key'] === $value) {
-            return;
-        }
-
-        $this->data['ssh_public_key'] = $value;
-
-        $this->_setModified('ssh_public_key');
-    }
-
     /**
     * Set the value of AllowPublicStatus / allow_public_status.
     *

PHPCI/Model/Build.php

@@ -46,6 +46,10 @@ class Build extends BuildBase
         return '#';
     }
 
+    /**
+     * Return a template to use to generate a link to a specific file.
+     * @return null
+     */
     public function getFileLinkTemplate()
     {
         return null;
@@ -119,6 +123,11 @@ class Build extends BuildBase
         return true;
     }
 
+    /**
+     * Get an array of plugins to run if there's no phpci.yml file.
+     * @param Builder $builder
+     * @return array
+     */
     protected function getZeroConfigPlugins(Builder $builder)
     {
         $pluginDir = PHPCI_DIR . 'PHPCI/Plugin/';
@@ -165,6 +174,11 @@ class Build extends BuildBase
         return $config;
     }
 
+    /**
+     * Return a value from the build's "extra" JSON array.
+     * @param null $key
+     * @return mixed|null|string
+     */
     public function getExtra($key = null)
     {
         $data = json_decode($this->data['extra'], true);

PHPCI/Model/Build/GithubBuild.php

@@ -95,6 +95,10 @@ class GithubBuild extends RemoteGitBuild
         }
     }
 
+    /**
+     * Get a parsed version of the commit message, with links to issues and commits.
+     * @return string
+     */
     public function getCommitMessage()
     {
         $rtn = $this->data['commit_message'];
@@ -107,6 +111,11 @@ class GithubBuild extends RemoteGitBuild
         return $rtn;
     }
 
+    /**
+     * Get a template to use for generating links to files.
+     * e.g. https://github.com/block8/phpci/blob/master/{FILE}#L{LINE}
+     * @return string
+     */
     public function getFileLinkTemplate()
     {
         $reference = $this->getProject()->getReference();
@@ -128,6 +137,12 @@ class GithubBuild extends RemoteGitBuild
         return $link;
     }
 
+    /**
+     * Handle any post-clone tasks, like applying a pull request patch on top of the branch.
+     * @param Builder $builder
+     * @param $cloneTo
+     * @return bool
+     */
     protected function postCloneSetup(Builder $builder, $cloneTo)
     {
         $buildType = $this->getExtra('build_type');

PHPCI/Model/Build/LocalBuild.php

@@ -54,6 +54,13 @@ class LocalBuild extends Build
         return true;
     }
 
+    /**
+     * Check if this is a "bare" git repository, and if so, unarchive it.
+     * @param Builder $builder
+     * @param $reference
+     * @param $buildPath
+     * @return bool
+     */
     protected function handleBareRepository(Builder $builder, $reference, $buildPath)
     {
         $gitConfig = parse_ini_file($reference.'/config', true);
@@ -68,6 +75,13 @@ class LocalBuild extends Build
         return false;
     }
 
+    /**
+     * Create a symlink if required.
+     * @param Builder $builder
+     * @param $reference
+     * @param $buildPath
+     * @return bool
+     */
     protected function handleSymlink(Builder $builder, $reference, $buildPath)
     {
         if (is_link($buildPath) && is_file($buildPath)) {

PHPCI/Model/Build/RemoteGitBuild.php

@@ -113,6 +113,12 @@ class RemoteGitBuild extends Build
         return $success;
     }
 
+    /**
+     * Handle any post-clone tasks, like switching branches.
+     * @param Builder $builder
+     * @param $cloneTo
+     * @return bool
+     */
     protected function postCloneSetup(Builder $builder, $cloneTo)
     {
         $success = true;

PHPCI/Model/Project.php

@@ -22,6 +22,12 @@ use b8\Store;
 */
 class Project extends ProjectBase
 {
+    /**
+     * Return the latest build from a specific branch, of a specific status, for this project.
+     * @param string $branch
+     * @param null $status
+     * @return mixed|null
+     */
     public function getLatestBuild($branch = 'master', $status = null)
     {
         $criteria       = array('branch' => $branch, 'project_id' => $this->getId());
@@ -44,6 +50,10 @@ class Project extends ProjectBase
         return null;
     }
 
+    /**
+     * Store this project's access_information data
+     * @param string|array $value
+     */
     public function setAccessInformation($value)
     {
         if (is_array($value)) {
@@ -53,6 +63,11 @@ class Project extends ProjectBase
         parent::setAccessInformation($value);
     }
 
+    /**
+     * Get this project's access_information data. Pass a specific key or null for all data.
+     * @param string|null $key
+     * @return mixed|null|string
+     */
     public function getAccessInformation($key = null)
     {
         $info = $this->data['access_information'];
@@ -89,6 +104,10 @@ class Project extends ProjectBase
         }
     }
 
+    /**
+     * Return the name of a FontAwesome icon to represent this project, depending on its type.
+     * @return string
+     */
     public function getIcon()
     {
         switch ($this->getType()) {

PHPCI/Plugin/Atoum.php

@@ -12,12 +12,22 @@ namespace PHPCI\Plugin;
 use PHPCI\Builder;
 use PHPCI\Model\Build;
 
+/**
+ * Atoum plugin, runs Atoum tests within a project.
+ * @package PHPCI\Plugin
+ */
 class Atoum implements \PHPCI\Plugin
 {
     private $args;
     private $config;
     private $directory;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;
@@ -42,6 +52,10 @@ class Atoum implements \PHPCI\Plugin
         }
     }
 
+    /**
+     * Run the Atoum plugin.
+     * @return bool
+     */
     public function execute()
     {
         $cmd = $this->executable;

PHPCI/Plugin/Behat.php

@@ -25,6 +25,18 @@ class Behat implements \PHPCI\Plugin
     protected $build;
     protected $features;
 
+    /**
+     * Standard Constructor
+     *
+     * $options['directory'] Output Directory. Default: %BUILDPATH%
+     * $options['filename']  Phar Filename. Default: build.phar
+     * $options['regexp']    Regular Expression Filename Capture. Default: /\.php$/
+     * $options['stub']      Stub Content. No Default Value
+     *
+     * @param Builder $phpci
+     * @param Build   $build
+     * @param array   $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci    = $phpci;

PHPCI/Plugin/Campfire.php

@@ -29,6 +29,13 @@ class Campfire implements \PHPCI\Plugin
     private $verbose;
     private $roomId;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     * @throws \Exception
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;
@@ -50,6 +57,10 @@ class Campfire implements \PHPCI\Plugin
 
     }
 
+    /**
+     * Run the Campfire plugin.
+     * @return bool|mixed
+     */
     public function execute()
     {
         $url = PHPCI_URL."build/view/".$this->build->getId();
@@ -62,16 +73,31 @@ class Campfire implements \PHPCI\Plugin
 
     }
 
+    /**
+     * Join a Campfire room.
+     * @param $roomId
+     */
     public function joinRoom($roomId)
     {
         $this->getPageByPost('/room/'.$roomId.'/join.json');
     }
 
+    /**
+     * Leave a Campfire room.
+     * @param $roomId
+     */
     public function leaveRoom($roomId)
     {
         $this->getPageByPost('/room/'.$roomId.'/leave.json');
     }
 
+    /**
+     * Send a message to a campfire room.
+     * @param $message
+     * @param $roomId
+     * @param bool $isPaste
+     * @return bool|mixed
+     */
     public function speak($message, $roomId, $isPaste = false)
     {
         $page = '/room/'.$roomId.'/speak.json';
@@ -85,6 +111,12 @@ class Campfire implements \PHPCI\Plugin
 
     }
 
+    /**
+     * Make a request to Campfire.
+     * @param $page
+     * @param null $data
+     * @return bool|mixed
+     */
     private function getPageByPost($page, $data = null)
     {
         $url = $this->url . $page;

PHPCI/Plugin/CleanBuild.php

@@ -25,6 +25,18 @@ class CleanBuild implements \PHPCI\Plugin
     protected $phpci;
     protected $build;
 
+    /**
+     * Standard Constructor
+     *
+     * $options['directory'] Output Directory. Default: %BUILDPATH%
+     * $options['filename']  Phar Filename. Default: build.phar
+     * $options['regexp']    Regular Expression Filename Capture. Default: /\.php$/
+     * $options['stub']      Stub Content. No Default Value
+     *
+     * @param Builder $phpci
+     * @param Build   $build
+     * @param array   $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci        = $phpci;

PHPCI/Plugin/Codeception.php

@@ -38,6 +38,12 @@ class Codeception implements \PHPCI\Plugin
      */
     protected $xmlConfigFile;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;
@@ -66,6 +72,11 @@ class Codeception implements \PHPCI\Plugin
         return $success;
     }
 
+    /**
+     * Run tests from a Codeception config file.
+     * @param $configPath
+     * @return bool|mixed
+     */
     protected function runConfigFile($configPath)
     {
         if (is_array($configPath)) {
@@ -91,6 +102,11 @@ class Codeception implements \PHPCI\Plugin
         }
     }
 
+    /**
+     * @param $array
+     * @param $callable
+     * @return bool|mixed
+     */
     protected function recurseArg($array, $callable)
     {
         $success = true;

PHPCI/Plugin/Composer.php

@@ -28,6 +28,13 @@ class Composer implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
     protected $phpci;
     protected $build;
 
+    /**
+     * Check if this plugin can be executed.
+     * @param $stage
+     * @param Builder $builder
+     * @param Build $build
+     * @return bool
+     */
     public static function canExecute($stage, Builder $builder, Build $build)
     {
         $path = $builder->buildPath . '/composer.json';
@@ -39,6 +46,12 @@ class Composer implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return false;
     }
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $path = $phpci->buildPath;

PHPCI/Plugin/CopyBuild.php

@@ -27,6 +27,12 @@ class CopyBuild implements \PHPCI\Plugin
     protected $phpci;
     protected $build;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $path               = $phpci->buildPath;
@@ -62,6 +68,10 @@ class CopyBuild implements \PHPCI\Plugin
         return $success;
     }
 
+    /**
+     * Wipe the destination directory if it already exists.
+     * @throws \Exception
+     */
     protected function wipeExistingDirectory()
     {
         if ($this->wipe == true && $this->directory != '/' && is_dir($this->directory)) {
@@ -74,6 +84,9 @@ class CopyBuild implements \PHPCI\Plugin
         }
     }
 
+    /**
+     * Delete any ignored files from the build prior to copying.
+     */
     protected function deleteIgnoredFiles()
     {
         if ($this->ignore) {

PHPCI/Plugin/Email.php

@@ -42,6 +42,13 @@ class Email implements \PHPCI\Plugin
      */
     protected $fromAddress;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param \Swift_Mailer $mailer
+     * @param array $options
+     */
     public function __construct(
         Builder $phpci,
         Build $build,
@@ -131,6 +138,13 @@ class Email implements \PHPCI\Plugin
         return $failedAddresses;
     }
 
+    /**
+     * Send out build status emails.
+     * @param array $toAddresses
+     * @param $subject
+     * @param $body
+     * @return array
+     */
     public function sendSeparateEmails(array $toAddresses, $subject, $body)
     {
         $failures = array();
@@ -145,6 +159,10 @@ class Email implements \PHPCI\Plugin
         return $failures;
     }
 
+    /**
+     * Get the list of email addresses to send to.
+     * @return array
+     */
     protected function getEmailAddresses()
     {
         $addresses = array();
@@ -167,6 +185,10 @@ class Email implements \PHPCI\Plugin
         return $addresses;
     }
 
+    /**
+     * Get the list of email addresses to CC.
+     * @return array
+     */
     protected function getCcAddresses()
     {
         $ccAddresses = array();

PHPCI/Plugin/Env.php

@@ -25,6 +25,12 @@ class Env implements \PHPCI\Plugin
     protected $build;
     protected $env_vars;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;

PHPCI/Plugin/Git.php

@@ -25,6 +25,12 @@ class Git implements \PHPCI\Plugin
     protected $build;
     protected $actions = array();
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;
@@ -32,6 +38,10 @@ class Git implements \PHPCI\Plugin
         $this->actions = $options;
     }
 
+    /**
+     * Run the Git plugin.
+     * @return bool
+     */
     public function execute()
     {
         $buildPath = $this->phpci->buildPath;
@@ -58,6 +68,12 @@ class Git implements \PHPCI\Plugin
         return $success;
     }
 
+    /**
+     * Determine which action to run, and run it.
+     * @param $action
+     * @param array $options
+     * @return bool
+     */
     protected function runAction($action, array $options = array())
     {
         switch ($action) {
@@ -78,6 +94,11 @@ class Git implements \PHPCI\Plugin
         return false;
     }
 
+    /**
+     * Handle a merge action.
+     * @param $options
+     * @return bool
+     */
     protected function runMergeAction($options)
     {
         if (array_key_exists('branch', $options)) {
@@ -87,6 +108,11 @@ class Git implements \PHPCI\Plugin
         }
     }
 
+    /**
+     * Handle a tag action.
+     * @param $options
+     * @return bool
+     */
     protected function runTagAction($options)
     {
         $tagName = date('Ymd-His');
@@ -104,6 +130,11 @@ class Git implements \PHPCI\Plugin
         return $this->phpci->executeCommand($cmd, $tagName, $message);
     }
 
+    /**
+     * Handle a pull action.
+     * @param $options
+     * @return bool
+     */
     protected function runPullAction($options)
     {
         $branch = $this->build->getBranch();
@@ -120,6 +151,11 @@ class Git implements \PHPCI\Plugin
         return $this->phpci->executeCommand('git pull %s %s', $remote, $branch);
     }
 
+    /**
+     * Handle a push action.
+     * @param $options
+     * @return bool
+     */
     protected function runPushAction($options)
     {
         $branch = $this->build->getBranch();

PHPCI/Plugin/Grunt.php

@@ -28,6 +28,18 @@ class Grunt implements \PHPCI\Plugin
     protected $grunt;
     protected $gruntfile;
 
+    /**
+     * Standard Constructor
+     *
+     * $options['directory'] Output Directory. Default: %BUILDPATH%
+     * $options['filename']  Phar Filename. Default: build.phar
+     * $options['regexp']    Regular Expression Filename Capture. Default: /\.php$/
+     * $options['stub']      Stub Content. No Default Value
+     *
+     * @param Builder $phpci
+     * @param Build   $build
+     * @param array   $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $path = $phpci->buildPath;

PHPCI/Plugin/Gulp.php

@@ -28,6 +28,18 @@ class Gulp implements \PHPCI\Plugin
     protected $gulp;
     protected $gulpfile;
 
+    /**
+     * Standard Constructor
+     *
+     * $options['directory'] Output Directory. Default: %BUILDPATH%
+     * $options['filename']  Phar Filename. Default: build.phar
+     * $options['regexp']    Regular Expression Filename Capture. Default: /\.php$/
+     * $options['stub']      Stub Content. No Default Value
+     *
+     * @param Builder $phpci
+     * @param Build   $build
+     * @param array   $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $path = $phpci->buildPath;

PHPCI/Plugin/HipchatNotify.php

@@ -27,6 +27,13 @@ class HipchatNotify implements \PHPCI\Plugin
     private $color;
     private $notify;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     * @throws \Exception
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;
@@ -62,6 +69,10 @@ class HipchatNotify implements \PHPCI\Plugin
 
     }
 
+    /**
+     * Run the HipChat plugin.
+     * @return bool
+     */
     public function execute()
     {
         $hipChat = new \HipChat\HipChat($this->authToken);

PHPCI/Plugin/Irc.php

@@ -29,6 +29,18 @@ class Irc implements \PHPCI\Plugin
     protected $room;
     protected $nick;
 
+    /**
+     * Standard Constructor
+     *
+     * $options['directory'] Output Directory. Default: %BUILDPATH%
+     * $options['filename']  Phar Filename. Default: build.phar
+     * $options['regexp']    Regular Expression Filename Capture. Default: /\.php$/
+     * $options['stub']      Stub Content. No Default Value
+     *
+     * @param Builder $phpci
+     * @param Build   $build
+     * @param array   $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;
@@ -48,6 +60,10 @@ class Irc implements \PHPCI\Plugin
         }
     }
 
+    /**
+     * Run IRC plugin.
+     * @return bool
+     */
     public function execute()
     {
         $msg = $this->phpci->interpolate($this->message);

PHPCI/Plugin/Lint.php

@@ -27,6 +27,18 @@ class Lint implements PHPCI\Plugin
     protected $phpci;
     protected $build;
 
+    /**
+     * Standard Constructor
+     *
+     * $options['directory'] Output Directory. Default: %BUILDPATH%
+     * $options['filename']  Phar Filename. Default: build.phar
+     * $options['regexp']    Regular Expression Filename Capture. Default: /\.php$/
+     * $options['stub']      Stub Content. No Default Value
+     *
+     * @param Builder $phpci
+     * @param Build   $build
+     * @param array   $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci        = $phpci;
@@ -68,6 +80,13 @@ class Lint implements PHPCI\Plugin
         return $success;
     }
 
+    /**
+     * Lint an item (file or directory) by calling the appropriate method.
+     * @param $php
+     * @param $item
+     * @param $itemPath
+     * @return bool
+     */
     protected function lintItem($php, $item, $itemPath)
     {
         $success = true;
@@ -81,6 +100,12 @@ class Lint implements PHPCI\Plugin
         return $success;
     }
 
+    /**
+     * Run php -l against a directory of files.
+     * @param $php
+     * @param $path
+     * @return bool
+     */
     protected function lintDirectory($php, $path)
     {
         $success = true;
@@ -105,6 +130,12 @@ class Lint implements PHPCI\Plugin
         return $success;
     }
 
+    /**
+     * Run php -l against a specific file.
+     * @param $php
+     * @param $path
+     * @return bool
+     */
     protected function lintFile($php, $path)
     {
         $success = true;

PHPCI/Plugin/PackageBuild.php

@@ -25,6 +25,12 @@ class PackageBuild implements \PHPCI\Plugin
     protected $format;
     protected $phpci;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $path               = $phpci->buildPath;

PHPCI/Plugin/Pdepend.php

@@ -48,6 +48,12 @@ class Pdepend implements \PHPCI\Plugin
      */
     protected $location;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;

PHPCI/Plugin/Phar.php

@@ -204,6 +204,10 @@ class Phar implements \PHPCI\Plugin
         return $this->stub;
     }
 
+    /**
+     * Get stub content for the Phar file.
+     * @return string
+     */
     public function getStubContent()
     {
         $content  = '';
@@ -214,7 +218,10 @@ class Phar implements \PHPCI\Plugin
         return $content;
     }
 
-    // Execution
+    /**
+     * Run the phar plugin.
+     * @return bool
+     */
     public function execute()
     {
         $success = false;

PHPCI/Plugin/Phing.php

@@ -32,6 +32,12 @@ class Phing implements \PHPCI\Plugin
     protected $phpci;
     protected $build;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->setPhpci($phpci);
@@ -139,6 +145,10 @@ class Phing implements \PHPCI\Plugin
         return $this->targets;
     }
 
+    /**
+     * Converts an array of targets into a string.
+     * @return string
+     */
     private function targetsToString()
     {
         return implode(' ', $this->targets);
@@ -181,6 +191,10 @@ class Phing implements \PHPCI\Plugin
         $this->buildFile = $buildFile;
     }
 
+    /**
+     * Get phing build file path.
+     * @return string
+     */
     public function getBuildFilePath()
     {
         return $this->getDirectory() . $this->buildFile;

PHPCI/Plugin/PhpCodeSniffer.php

@@ -72,6 +72,13 @@ class PhpCodeSniffer implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
      */
     protected $ignore;
 
+    /**
+     * Check if this plugin can be executed.
+     * @param $stage
+     * @param Builder $builder
+     * @param Build $build
+     * @return bool
+     */
     public static function canExecute($stage, Builder $builder, Build $build)
     {
         if ($stage == 'test') {
@@ -120,6 +127,10 @@ class PhpCodeSniffer implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         $this->setOptions($options);
     }
 
+    /**
+     * Handle this plugin's options.
+     * @param $options
+     */
     protected function setOptions($options)
     {
         foreach (array('directory', 'standard', 'path', 'ignore', 'allowed_warnings', 'allowed_errors') as $key) {
@@ -177,6 +188,10 @@ class PhpCodeSniffer implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return $success;
     }
 
+    /**
+     * Process options and produce an arguments string for PHPCS.
+     * @return array
+     */
     protected function getFlags()
     {
         $ignore = '';
@@ -198,6 +213,12 @@ class PhpCodeSniffer implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return array($ignore, $standard, $suffixes);
     }
 
+    /**
+     * Process the PHPCS output report.
+     * @param $output
+     * @return array
+     * @throws \Exception
+     */
     protected function processReport($output)
     {
         $data = json_decode(trim($output), true);

PHPCI/Plugin/PhpCpd.php

@@ -37,6 +37,12 @@ class PhpCpd implements \PHPCI\Plugin
      */
     protected $ignore;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;
@@ -105,6 +111,12 @@ class PhpCpd implements \PHPCI\Plugin
         return $success;
     }
 
+    /**
+     * Process the PHPCPD XML report.
+     * @param $xmlString
+     * @return array
+     * @throws \Exception
+     */
     protected function processReport($xmlString)
     {
         $xml = simplexml_load_string($xmlString);

PHPCI/Plugin/PhpCsFixer.php

@@ -37,6 +37,18 @@ class PhpCsFixer implements \PHPCI\Plugin
     protected $diff       = '';
     protected $levels     = array('psr0', 'psr1', 'psr2', 'all');
 
+    /**
+     * Standard Constructor
+     *
+     * $options['directory'] Output Directory. Default: %BUILDPATH%
+     * $options['filename']  Phar Filename. Default: build.phar
+     * $options['regexp']    Regular Expression Filename Capture. Default: /\.php$/
+     * $options['stub']      Stub Content. No Default Value
+     *
+     * @param Builder $phpci
+     * @param Build   $build
+     * @param array   $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;
@@ -46,6 +58,10 @@ class PhpCsFixer implements \PHPCI\Plugin
         $this->buildArgs($options);
     }
 
+    /**
+     * Run PHP CS Fixer.
+     * @return bool
+     */
     public function execute()
     {
         $curdir = getcwd();
@@ -66,6 +82,10 @@ class PhpCsFixer implements \PHPCI\Plugin
         return $success;
     }
 
+    /**
+     * Build an args string for PHPCS Fixer.
+     * @param $options
+     */
     public function buildArgs($options)
     {
         if (isset($options['verbose']) && $options['verbose']) {

PHPCI/Plugin/PhpDocblockChecker.php

@@ -45,6 +45,13 @@ class PhpDocblockChecker implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
     protected $skipClasses = false;
     protected $skipMethods = false;
 
+    /**
+     * Check if this plugin can be executed.
+     * @param $stage
+     * @param Builder $builder
+     * @param Build $build
+     * @return bool
+     */
     public static function canExecute($stage, Builder $builder, Build $build)
     {
         if ($stage == 'test') {
@@ -54,7 +61,12 @@ class PhpDocblockChecker implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return false;
     }
 
-
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;

PHPCI/Plugin/PhpLoc.php

@@ -30,6 +30,13 @@ class PhpLoc implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
      */
     protected $phpci;
 
+    /**
+     * Check if this plugin can be executed.
+     * @param $stage
+     * @param Builder $builder
+     * @param Build $build
+     * @return bool
+     */
     public static function canExecute($stage, Builder $builder, Build $build)
     {
         if ($stage == 'test') {
@@ -39,6 +46,12 @@ class PhpLoc implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return false;
     }
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci     = $phpci;

PHPCI/Plugin/PhpMessDetector.php

@@ -55,6 +55,13 @@ class PhpMessDetector implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
      */
     protected $rules;
 
+    /**
+     * Check if this plugin can be executed.
+     * @param $stage
+     * @param Builder $builder
+     * @param Build $build
+     * @return bool
+     */
     public static function canExecute($stage, Builder $builder, Build $build)
     {
         if ($stage == 'test') {
@@ -64,7 +71,18 @@ class PhpMessDetector implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return false;
     }
 
-
+    /**
+     * Standard Constructor
+     *
+     * $options['directory'] Output Directory. Default: %BUILDPATH%
+     * $options['filename']  Phar Filename. Default: build.phar
+     * $options['regexp']    Regular Expression Filename Capture. Default: /\.php$/
+     * $options['stub']      Stub Content. No Default Value
+     *
+     * @param Builder $phpci
+     * @param Build   $build
+     * @param array   $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;
@@ -117,6 +135,11 @@ class PhpMessDetector implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return $this->wasLastExecSuccessful($errorCount);
     }
 
+    /**
+     * Override a default setting.
+     * @param $options
+     * @param $key
+     */
     protected function overrideSetting($options, $key)
     {
         if (isset($options[$key]) && is_array($options[$key])) {
@@ -124,6 +147,12 @@ class PhpMessDetector implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         }
     }
 
+    /**
+     * Process PHPMD's XML output report.
+     * @param $xmlString
+     * @return array
+     * @throws \Exception
+     */
     protected function processReport($xmlString)
     {
         $xml = simplexml_load_string($xmlString);
@@ -159,6 +188,10 @@ class PhpMessDetector implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return array($warnings, $data);
     }
 
+    /**
+     * Try and process the rules parameter from phpci.yml.
+     * @return bool
+     */
     protected function tryAndProcessRules()
     {
         if (!empty($this->rules) && !is_array($this->rules)) {
@@ -175,6 +208,10 @@ class PhpMessDetector implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return true;
     }
 
+    /**
+     * Execute PHP Mess Detector.
+     * @param $binaryPath
+     */
     protected function executePhpMd($binaryPath)
     {
         $cmd = $binaryPath . ' "%s" xml %s %s %s';
@@ -207,6 +244,10 @@ class PhpMessDetector implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         $this->phpci->logExecOutput(true);
     }
 
+    /**
+     * Get the path PHPMD should be run against.
+     * @return string
+     */
     protected function getTargetPath()
     {
         $path = $this->phpci->buildPath . $this->path;

PHPCI/Plugin/PhpParallelLint.php

@@ -41,6 +41,18 @@ class PhpParallelLint implements \PHPCI\Plugin
      */
     protected $ignore;
 
+    /**
+     * Standard Constructor
+     *
+     * $options['directory'] Output Directory. Default: %BUILDPATH%
+     * $options['filename']  Phar Filename. Default: build.phar
+     * $options['regexp']    Regular Expression Filename Capture. Default: /\.php$/
+     * $options['stub']      Stub Content. No Default Value
+     *
+     * @param Builder $phpci
+     * @param Build   $build
+     * @param array   $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci        = $phpci;
@@ -88,6 +100,10 @@ class PhpParallelLint implements \PHPCI\Plugin
         return $success;
     }
 
+    /**
+     * Produce an argument string for PHP Parallel Lint.
+     * @return array
+     */
     protected function getFlags()
     {
         $ignore = '';

PHPCI/Plugin/PhpSpec.php

@@ -36,6 +36,12 @@ class PhpSpec implements PHPCI\Plugin
      */
     protected $options;
 
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;

PHPCI/Plugin/PhpUnit.php

@@ -49,6 +49,13 @@ class PhpUnit implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
      */
     protected $xmlConfigFile;
 
+    /**
+     * Check if this plugin can be executed.
+     * @param $stage
+     * @param Builder $builder
+     * @param Build $build
+     * @return bool
+     */
     public static function canExecute($stage, Builder $builder, Build $build)
     {
         if ($stage == 'test' && !is_null(self::findConfigFile($builder->buildPath))) {
@@ -58,6 +65,11 @@ class PhpUnit implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return false;
     }
 
+    /**
+     * Try and find the phpunit XML config file.
+     * @param $buildPath
+     * @return null|string
+     */
     public static function findConfigFile($buildPath)
     {
         if (file_exists($buildPath . 'phpunit.xml')) {
@@ -79,6 +91,18 @@ class PhpUnit implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return null;
     }
 
+    /**
+     * Standard Constructor
+     *
+     * $options['directory'] Output Directory. Default: %BUILDPATH%
+     * $options['filename']  Phar Filename. Default: build.phar
+     * $options['regexp']    Regular Expression Filename Capture. Default: /\.php$/
+     * $options['stub']      Stub Content. No Default Value
+     *
+     * @param Builder $phpci
+     * @param Build   $build
+     * @param array   $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;
@@ -152,6 +176,11 @@ class PhpUnit implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         return $success;
     }
 
+    /**
+     * Run the tests defined in a PHPUnit config file.
+     * @param $configPath
+     * @return bool|mixed
+     */
     protected function runConfigFile($configPath)
     {
         if (is_array($configPath)) {
@@ -182,6 +211,11 @@ class PhpUnit implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         }
     }
 
+    /**
+     * Run the PHPUnit tests in a specific directory or array of directories.
+     * @param $directory
+     * @return bool|mixed
+     */
     protected function runDir($directory)
     {
         if (is_array($directory)) {
@@ -204,6 +238,11 @@ class PhpUnit implements PHPCI\Plugin, PHPCI\ZeroConfigPlugin
         }
     }
 
+    /**
+     * @param $array
+     * @param $callable
+     * @return bool|mixed
+     */
     protected function recurseArg($array, $callable)
     {
         $success = true;

PHPCI/Plugin/Shell.php

@@ -38,6 +38,18 @@ class Shell implements \PHPCI\Plugin
      */
     protected $commands = array();
 
+    /**
+     * Standard Constructor
+     *
+     * $options['directory'] Output Directory. Default: %BUILDPATH%
+     * $options['filename']  Phar Filename. Default: build.phar
+     * $options['regexp']    Regular Expression Filename Capture. Default: /\.php$/
+     * $options['stub']      Stub Content. No Default Value
+     *
+     * @param Builder $phpci
+     * @param Build   $build
+     * @param array   $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $this->phpci = $phpci;

PHPCI/Plugin/Util/ComposerPluginInformation.php

@@ -2,7 +2,10 @@
 
 namespace PHPCI\Plugin\Util;
 
-
+/**
+ * Class ComposerPluginInformation
+ * @package PHPCI\Plugin\Util
+ */
 class ComposerPluginInformation implements InstalledPluginInformation
 {
     /**
@@ -67,6 +70,9 @@ class ComposerPluginInformation implements InstalledPluginInformation
         );
     }
 
+    /**
+     * Load a list of available plugins from the installed composer packages.
+     */
     protected function loadPluginInfo()
     {
         if ($this->pluginInfo !== null) {

PHPCI/Plugin/Util/Executor.php

@@ -5,6 +5,10 @@ namespace PHPCI\Plugin\Util;
 use PHPCI\Helper\Lang;
 use \PHPCI\Logging\BuildLogger;
 
+/**
+ * Plugin Executor - Runs the configured plugins for a given build stage.
+ * @package PHPCI\Plugin\Util
+ */
 class Executor
 {
     /**
@@ -17,6 +21,10 @@ class Executor
      */
     protected $pluginFactory;
 
+    /**
+     * @param Factory $pluginFactory
+     * @param BuildLogger $logger
+     */
     public function __construct(Factory $pluginFactory, BuildLogger $logger)
     {
         $this->pluginFactory = $pluginFactory;

PHPCI/Plugin/Util/Factory.php

@@ -2,14 +2,14 @@
 
 namespace PHPCI\Plugin\Util;
 
-
+/**
-
+ * Plugin Factory - Loads Plugins and passes required dependencies.
+ * @package PHPCI\Plugin\Util
+ */
 class Factory
 {
-
     const TYPE_ARRAY = "array";
     const TYPE_CALLABLE = "callable";
-
     const INTERFACE_PHPCI_PLUGIN = '\PHPCI\Plugin';
 
     private $currentPluginOptions;
@@ -19,6 +19,9 @@ class Factory
      */
     private $container;
 
+    /**
+     * @param \Pimple $container
+     */
     public function __construct(\Pimple $container = null)
     {
         if ($container) {
@@ -59,6 +62,10 @@ class Factory
         return false;
     }
 
+    /**
+     * Get most recently used factory options.
+     * @return mixed
+     */
     public function getLastOptions()
     {
         return $this->currentPluginOptions;
@@ -129,6 +136,12 @@ class Factory
         $this->container[$resourceID] = $loader;
     }
 
+    /**
+     * Get an internal resource ID.
+     * @param null $type
+     * @param null $name
+     * @return string
+     */
     private function getInternalID($type = null, $name = null)
     {
         $type = $type ? : "";
@@ -136,6 +149,11 @@ class Factory
         return $type . "-" . $name;
     }
 
+    /**
+     * @param null $type
+     * @param null $name
+     * @return null
+     */
     private function getResourceFor($type = null, $name = null)
     {
         $fullId = $this->getInternalID($type, $name);
@@ -156,6 +174,10 @@ class Factory
         return null;
     }
 
+    /**
+     * @param \ReflectionParameter $param
+     * @return null|string
+     */
     private function getParamType(\ReflectionParameter $param)
     {
         $class = $param->getClass();
@@ -170,6 +192,12 @@ class Factory
         }
     }
 
+    /**
+     * @param $existingArgs
+     * @param \ReflectionParameter $param
+     * @return array
+     * @throws \DomainException
+     */
     private function addArgFromParam($existingArgs, \ReflectionParameter $param)
     {
         $name = $param->getName();

PHPCI/Plugin/Util/FilesPluginInformation.php

@@ -2,6 +2,10 @@
 
 namespace PHPCI\Plugin\Util;
 
+/**
+ * Class FilesPluginInformation
+ * @package PHPCI\Plugin\Util
+ */
 class FilesPluginInformation implements InstalledPluginInformation
 {
 
@@ -21,11 +25,18 @@ class FilesPluginInformation implements InstalledPluginInformation
      */
     protected $pluginInfo = null;
 
+    /**
+     * @param $dirPath
+     * @return FilesPluginInformation
+     */
     public static function newFromDir($dirPath)
     {
         return new self(new \DirectoryIterator($dirPath));
     }
 
+    /**
+     * @param \Iterator $files
+     */
     public function __construct(\Iterator $files)
     {
         $this->files = $files;
@@ -62,6 +73,9 @@ class FilesPluginInformation implements InstalledPluginInformation
         );
     }
 
+    /**
+     * Load plugin information from a given list of files.
+     */
     protected function loadPluginInfo()
     {
         $this->pluginInfo = array();
@@ -74,6 +88,10 @@ class FilesPluginInformation implements InstalledPluginInformation
         }
     }
 
+    /**
+     * Add a plugin to the list from a given file.
+     * @param \SplFileInfo $fileInfo
+     */
     protected function addPluginFromFile(\SplFileInfo $fileInfo)
     {
         $class = $this->getFullClassFromFile($fileInfo);
@@ -89,6 +107,11 @@ class FilesPluginInformation implements InstalledPluginInformation
         }
     }
 
+    /**
+     * Determine plugin class name for a given file.
+     * @param \SplFileInfo $fileInfo
+     * @return null|string
+     */
     protected function getFullClassFromFile(\SplFileInfo $fileInfo)
     {
         //TODO: Something less horrible than a regular expression

PHPCI/Plugin/Util/InstalledPluginInformation.php

@@ -1,7 +1,10 @@
 <?php
 namespace PHPCI\Plugin\Util;
 
-
+/**
+ * Interface InstalledPluginInformation
+ * @package PHPCI\Plugin\Util
+ */
 interface InstalledPluginInformation
 {
     /**

PHPCI/Plugin/Util/PluginInformationCollection.php

@@ -2,6 +2,10 @@
 
 namespace PHPCI\Plugin\Util;
 
+/**
+ * Class PluginInformationCollection
+ * @package PHPCI\Plugin\Util
+ */
 class PluginInformationCollection implements InstalledPluginInformation
 {
     /**
@@ -9,6 +13,10 @@ class PluginInformationCollection implements InstalledPluginInformation
      */
     protected $pluginInformations = array();
 
+    /**
+     * Add a plugin to the collection.
+     * @param InstalledPluginInformation $information
+     */
     public function add(InstalledPluginInformation $information)
     {
         $this->pluginInformations[] = $information;

PHPCI/Plugin/Util/TapParser.php

@@ -4,6 +4,10 @@ namespace PHPCI\Plugin\Util;
 
 use PHPCI\Helper\Lang;
 
+/**
+ * Processes TAP format strings into usable test result data.
+ * @package PHPCI\Plugin\Util
+ */
 class TapParser
 {
     const TEST_COUNTS_PATTERN = '/([0-9]+)\.\.([0-9]+)/';
@@ -75,6 +79,11 @@ class TapParser
         return $rtn;
     }
 
+    /**
+     * Process the individual test lines within a TAP string.
+     * @param $lines
+     * @return array
+     */
     protected function processTestLines($lines)
     {
         $rtn = array();
@@ -106,6 +115,10 @@ class TapParser
         return $rtn;
     }
 
+    /**
+     * Get the total number of failures from the current TAP file.
+     * @return int
+     */
     public function getTotalFailures()
     {
         return $this->failures;

PHPCI/Plugin/Wipe.php

@@ -32,7 +32,12 @@ class Wipe implements \PHPCI\Plugin
 
     protected $directory;
 
-
+    /**
+     * Set up the plugin, configure options, etc.
+     * @param Builder $phpci
+     * @param Build $build
+     * @param array $options
+     */
     public function __construct(Builder $phpci, Build $build, array $options = array())
     {
         $path               = $phpci->buildPath;

PHPCI/Service/BuildService.php

@@ -13,6 +13,11 @@ use PHPCI\Model\Build;
 use PHPCI\Model\Project;
 use PHPCI\Store\BuildStore;
 
+/**
+ * The build service handles the creation, duplication and deletion of builds.
+ * Class BuildService
+ * @package PHPCI\Service
+ */
 class BuildService
 {
     /**

PHPCI/Service/ProjectService.php

@@ -12,6 +12,11 @@ namespace PHPCI\Service;
 use PHPCI\Model\Project;
 use PHPCI\Store\ProjectStore;
 
+/**
+ * The project service handles the creation, modification and deletion of projects.
+ * Class ProjectService
+ * @package PHPCI\Service
+ */
 class ProjectService
 {
     /**

PHPCI/Service/UserService.php

@@ -12,6 +12,11 @@ namespace PHPCI\Service;
 use PHPCI\Model\User;
 use PHPCI\Store\UserStore;
 
+/**
+ * The user service handles the creation, modification and deletion of users.
+ * Class UserService
+ * @package PHPCI\Service
+ */
 class UserService
 {
     /**
@@ -27,6 +32,14 @@ class UserService
         $this->store = $store;
     }
 
+    /**
+     * Create a new user within PHPCI.
+     * @param $name
+     * @param $emailAddress
+     * @param $password
+     * @param bool $isAdmin
+     * @return \PHPCI\Model\User
+     */
     public function createUser($name, $emailAddress, $password, $isAdmin = false)
     {
         $user = new User();
@@ -38,6 +51,15 @@ class UserService
         return $this->store->save($user);
     }
 
+    /**
+     * Update a user.
+     * @param User $user
+     * @param $name
+     * @param $emailAddress
+     * @param null $password
+     * @param null $isAdmin
+     * @return \PHPCI\Model\User
+     */
     public function updateUser(User $user, $name, $emailAddress, $password = null, $isAdmin = null)
     {
         $user->setName($name);
@@ -54,6 +76,11 @@ class UserService
         return $this->store->save($user);
     }
 
+    /**
+     * Delete a user.
+     * @param User $user
+     * @return bool
+     */
     public function deleteUser(User $user)
     {
         return $this->store->delete($user);

PHPCI/Store.php

@@ -9,6 +9,10 @@
 
 namespace PHPCI;
 
+/**
+ * PHPCI Base Store
+ * @package PHPCI
+ */
 abstract class Store extends \b8\Store
 {
 

PHPCI/Store/Base/BuildMetaStoreBase.php

@@ -20,11 +20,24 @@ class BuildMetaStoreBase extends Store
     protected $modelName   = '\PHPCI\Model\BuildMeta';
     protected $primaryKey  = 'id';
 
+    /**
+     * Get a BuildMeta by primary key.
+     * @param mixed $value Primary key.
+     * @param string $useConnection Connection to use (read / write)
+     * @return \PHPCI\Model\BuildMeta|null
+     */
     public function getByPrimaryKey($value, $useConnection = 'read')
     {
         return $this->getById($value, $useConnection);
     }
 
+    /**
+     * Get a BuildMeta by Id.
+     * @param mixed $value.
+     * @param string $useConnection Connection to use (read / write)
+     * @throws \b8\Exception\HttpException
+     * @return \PHPCI\Model\BuildMeta|null;
+     */
     public function getById($value, $useConnection = 'read')
     {
         if (is_null($value)) {
@@ -44,6 +57,14 @@ class BuildMetaStoreBase extends Store
         return null;
     }
 
+    /**
+     * Get an array of BuildMeta by ProjectId.
+     * @param mixed $value.
+     * @param int $limit
+     * @param string $useConnection Connection to use (read / write)
+     * @throws \b8\Exception\HttpException
+     * @return \PHPCI\Model\BuildMeta[]
+     */
     public function getByProjectId($value, $limit = null, $useConnection = 'read')
     {
         if (is_null($value)) {
@@ -56,6 +77,7 @@ class BuildMetaStoreBase extends Store
             $add .= ' LIMIT ' . $limit;
         }
 
+        $count = null;
 
         $query = 'SELECT * FROM `build_meta` WHERE `project_id` = :project_id' . $add;
         $stmt = Database::getConnection($useConnection)->prepare($query);
@@ -69,15 +91,20 @@ class BuildMetaStoreBase extends Store
             };
             $rtn = array_map($map, $res);
 
-            $count = count($rtn);
-
-
             return array('items' => $rtn, 'count' => $count);
         } else {
             return array('items' => array(), 'count' => 0);
         }
     }
 
+    /**
+     * Get an array of BuildMeta by BuildId.
+     * @param mixed $value.
+     * @param int $limit
+     * @param string $useConnection Connection to use (read / write)
+     * @throws \b8\Exception\HttpException
+     * @return \PHPCI\Model\BuildMeta[]
+     */
     public function getByBuildId($value, $limit = null, $useConnection = 'read')
     {
         if (is_null($value)) {
@@ -90,6 +117,7 @@ class BuildMetaStoreBase extends Store
             $add .= ' LIMIT ' . $limit;
         }
 
+        $count = null;
 
         $query = 'SELECT * FROM `build_meta` WHERE `build_id` = :build_id' . $add;
         $stmt = Database::getConnection($useConnection)->prepare($query);
@@ -103,9 +131,6 @@ class BuildMetaStoreBase extends Store
             };
             $rtn = array_map($map, $res);
 
-            $count = count($rtn);
-
-
             return array('items' => $rtn, 'count' => $count);
         } else {
             return array('items' => array(), 'count' => 0);

PHPCI/Store/Base/BuildStoreBase.php

@@ -20,11 +20,24 @@ class BuildStoreBase extends Store
     protected $modelName   = '\PHPCI\Model\Build';
     protected $primaryKey  = 'id';
 
+    /**
+     * Get a Build by primary key.
+     * @param mixed $value Primary key.
+     * @param string $useConnection Connection to use (read / write)
+     * @return \PHPCI\Model\Build|null
+     */
     public function getByPrimaryKey($value, $useConnection = 'read')
     {
         return $this->getById($value, $useConnection);
     }
 
+    /**
+     * Get a Build by Id.
+     * @param mixed $value.
+     * @param string $useConnection Connection to use (read / write)
+     * @throws \b8\Exception\HttpException
+     * @return \PHPCI\Model\Build|null;
+     */
     public function getById($value, $useConnection = 'read')
     {
         if (is_null($value)) {
@@ -44,6 +57,14 @@ class BuildStoreBase extends Store
         return null;
     }
 
+    /**
+     * Get an array of Build by ProjectId.
+     * @param mixed $value.
+     * @param int $limit
+     * @param string $useConnection Connection to use (read / write)
+     * @throws \b8\Exception\HttpException
+     * @return \PHPCI\Model\Build[]
+     */
     public function getByProjectId($value, $limit = null, $useConnection = 'read')
     {
         if (is_null($value)) {
@@ -56,6 +77,7 @@ class BuildStoreBase extends Store
             $add .= ' LIMIT ' . $limit;
         }
 
+        $count = null;
 
         $query = 'SELECT * FROM `build` WHERE `project_id` = :project_id' . $add;
         $stmt = Database::getConnection($useConnection)->prepare($query);
@@ -69,15 +91,20 @@ class BuildStoreBase extends Store
             };
             $rtn = array_map($map, $res);
 
-            $count = count($rtn);
-
-
             return array('items' => $rtn, 'count' => $count);
         } else {
             return array('items' => array(), 'count' => 0);
         }
     }
 
+    /**
+     * Get an array of Build by Status.
+     * @param mixed $value.
+     * @param int $limit
+     * @param string $useConnection Connection to use (read / write)
+     * @throws \b8\Exception\HttpException
+     * @return \PHPCI\Model\Build[]
+     */
     public function getByStatus($value, $limit = null, $useConnection = 'read')
     {
         if (is_null($value)) {
@@ -90,6 +117,7 @@ class BuildStoreBase extends Store
             $add .= ' LIMIT ' . $limit;
         }
 
+        $count = null;
 
         $query = 'SELECT * FROM `build` WHERE `status` = :status' . $add;
         $stmt = Database::getConnection($useConnection)->prepare($query);
@@ -103,9 +131,6 @@ class BuildStoreBase extends Store
             };
             $rtn = array_map($map, $res);
 
-            $count = count($rtn);
-
-
             return array('items' => $rtn, 'count' => $count);
         } else {
             return array('items' => array(), 'count' => 0);

PHPCI/Store/Base/ProjectStoreBase.php

@@ -20,11 +20,24 @@ class ProjectStoreBase extends Store
     protected $modelName   = '\PHPCI\Model\Project';
     protected $primaryKey  = 'id';
 
+    /**
+     * Get a Project by primary key.
+     * @param mixed $value Primary key.
+     * @param string $useConnection Connection to use (read / write)
+     * @return \PHPCI\Model\Project|null
+     */
     public function getByPrimaryKey($value, $useConnection = 'read')
     {
         return $this->getById($value, $useConnection);
     }
 
+    /**
+     * Get a Project by Id.
+     * @param mixed $value.
+     * @param string $useConnection Connection to use (read / write)
+     * @throws \b8\Exception\HttpException
+     * @return \PHPCI\Model\Project|null;
+     */
     public function getById($value, $useConnection = 'read')
     {
         if (is_null($value)) {
@@ -44,6 +57,14 @@ class ProjectStoreBase extends Store
         return null;
     }
 
+    /**
+     * Get an array of Project by Title.
+     * @param mixed $value.
+     * @param int $limit
+     * @param string $useConnection Connection to use (read / write)
+     * @throws \b8\Exception\HttpException
+     * @return \PHPCI\Model\Project[]
+     */
     public function getByTitle($value, $limit = null, $useConnection = 'read')
     {
         if (is_null($value)) {
@@ -56,6 +77,7 @@ class ProjectStoreBase extends Store
             $add .= ' LIMIT ' . $limit;
         }
 
+        $count = null;
 
         $query = 'SELECT * FROM `project` WHERE `title` = :title' . $add;
         $stmt = Database::getConnection($useConnection)->prepare($query);
@@ -69,9 +91,6 @@ class ProjectStoreBase extends Store
             };
             $rtn = array_map($map, $res);
 
-            $count = count($rtn);
-
-
             return array('items' => $rtn, 'count' => $count);
         } else {
             return array('items' => array(), 'count' => 0);

PHPCI/Store/Base/UserStoreBase.php

@@ -20,11 +20,24 @@ class UserStoreBase extends Store
     protected $modelName   = '\PHPCI\Model\User';
     protected $primaryKey  = 'id';
 
+    /**
+     * Get a User by primary key.
+     * @param mixed $value Primary key.
+     * @param string $useConnection Connection to use (read / write)
+     * @return \PHPCI\Model\User|null
+     */
     public function getByPrimaryKey($value, $useConnection = 'read')
     {
         return $this->getById($value, $useConnection);
     }
 
+    /**
+     * Get a User by Id.
+     * @param mixed $value.
+     * @param string $useConnection Connection to use (read / write)
+     * @throws \b8\Exception\HttpException
+     * @return \PHPCI\Model\User|null;
+     */
     public function getById($value, $useConnection = 'read')
     {
         if (is_null($value)) {
@@ -44,6 +57,13 @@ class UserStoreBase extends Store
         return null;
     }
 
+    /**
+     * Get a User by Email.
+     * @param mixed $value.
+     * @param string $useConnection Connection to use (read / write)
+     * @throws \b8\Exception\HttpException
+     * @return \PHPCI\Model\User|null;
+     */
     public function getByEmail($value, $useConnection = 'read')
     {
         if (is_null($value)) {

PHPCI/Store/BuildStore.php

@@ -22,6 +22,12 @@ use PHPCI\Store\Base\BuildStoreBase;
 */
 class BuildStore extends BuildStoreBase
 {
+    /**
+     * Return an array of the latest builds for a given project.
+     * @param null $projectId
+     * @param int $limit
+     * @return array
+     */
     public function getLatestBuilds($projectId = null, $limit = 5)
     {
         $where = '';
@@ -53,6 +59,12 @@ class BuildStore extends BuildStoreBase
         }
     }
 
+    /**
+     * Return the latest build for a specific project, of a specific build status.
+     * @param null $projectId
+     * @param int $status
+     * @return array|Build
+     */
     public function getLastBuildByStatus($projectId = null, $status = Build::STATUS_SUCCESS)
     {
         $query = 'SELECT * FROM build WHERE project_id = :pid AND status = :status ORDER BY id DESC LIMIT 1';
@@ -69,6 +81,12 @@ class BuildStore extends BuildStoreBase
         }
     }
 
+    /**
+     * Return an array of builds for a given project and commit ID.
+     * @param $projectId
+     * @param $commitId
+     * @return array
+     */
     public function getByProjectAndCommit($projectId, $commitId)
     {
         $query = 'SELECT * FROM `build` WHERE `project_id` = :project_id AND `commit_id` = :commit_id';
@@ -91,6 +109,14 @@ class BuildStore extends BuildStoreBase
         }
     }
 
+    /**
+     * Return build metadata by key, project and optionally build id.
+     * @param $key
+     * @param $projectId
+     * @param null $buildId
+     * @param int $numResults
+     * @return array|null
+     */
     public function getMeta($key, $projectId, $buildId = null, $numResults = 1)
     {
         $select = '`build_id`, `meta_key`, `meta_value`';
@@ -124,6 +150,14 @@ class BuildStore extends BuildStoreBase
         }
     }
 
+    /**
+     * Set a metadata value for a given project and build ID.
+     * @param $projectId
+     * @param $buildId
+     * @param $key
+     * @param $value
+     * @return bool
+     */
     public function setMeta($projectId, $buildId, $key, $value)
     {
         $cols = '`project_id`, `build_id`, `meta_key`, `meta_value`';

PHPCI/Store/ProjectStore.php

@@ -21,6 +21,11 @@ use PHPCI\Store\Base\ProjectStoreBase;
 */
 class ProjectStore extends ProjectStoreBase
 {
+    /**
+     * Returns a list of all branch names PHPCI has run builds against.
+     * @param $projectId
+     * @return array
+     */
     public function getKnownBranches($projectId)
     {
         $query = 'SELECT DISTINCT branch from build WHERE project_id = :pid';
@@ -41,6 +46,10 @@ class ProjectStore extends ProjectStoreBase
         }
     }
 
+    /**
+     * Get a list of all projects, ordered by their title.
+     * @return array
+     */
     public function getAll()
     {
         $query = 'SELECT * FROM `project` ORDER BY `title` ASC';

phpci.yml

@@ -24,7 +24,7 @@ test:
   php_loc:
   php_unit:
   php_docblock_checker:
-    allowed_warnings: -1 # Allow unlimited warnings for now.
+    allowed_warnings: 0
 
 failure:
   email: