From 7f9a09fa2947e91dc42d5c7e0ea78472e2b59cee Mon Sep 17 00:00:00 2001 From: Dan Cryer Date: Mon, 8 Dec 2014 11:25:33 +0000 Subject: [PATCH] Adding Docblocks throughout the project and lowering the missing docblock limit in phpci.yml to zero. Closes #692 --- PHPCI/Application.php | 13 ++++ PHPCI/Builder.php | 10 +++ PHPCI/Controller.php | 25 ++++++ PHPCI/Controller/BuildController.php | 17 ++++- PHPCI/Controller/BuildStatusController.php | 9 +++ PHPCI/Controller/HomeController.php | 11 +++ PHPCI/Controller/PluginController.php | 25 ++++++ PHPCI/Controller/ProjectController.php | 8 ++ PHPCI/Controller/SessionController.php | 17 +++++ PHPCI/Controller/SettingsController.php | 39 ++++++++++ PHPCI/Controller/UserController.php | 7 ++ PHPCI/Controller/WebhookController.php | 24 ++++++ PHPCI/Helper/BaseCommandExecutor.php | 4 + PHPCI/Helper/Build.php | 5 ++ PHPCI/Helper/BuildInterpolator.php | 4 + PHPCI/Helper/Email.php | 50 ++++++++++++ PHPCI/Helper/Github.php | 10 +++ PHPCI/Helper/MailerFactory.php | 20 ++++- PHPCI/Helper/SshKey.php | 12 +++ PHPCI/Helper/UnixCommandExecutor.php | 9 +++ PHPCI/Helper/User.php | 6 ++ PHPCI/Helper/WindowsCommandExecutor.php | 9 +++ PHPCI/Logging/BuildDBLogHandler.php | 13 ++++ PHPCI/Logging/BuildLogger.php | 9 +++ PHPCI/Logging/Handler.php | 15 ++++ PHPCI/Logging/LoggedBuildContextTidier.php | 7 ++ PHPCI/Logging/LoggerConfig.php | 11 ++- PHPCI/Logging/OutputLogHandler.php | 13 ++++ PHPCI/Model.php | 4 + PHPCI/Model/Base/ProjectBase.php | 76 +++++++++---------- PHPCI/Model/Build.php | 14 ++++ PHPCI/Model/Build/GithubBuild.php | 15 ++++ PHPCI/Model/Build/LocalBuild.php | 14 ++++ PHPCI/Model/Build/RemoteGitBuild.php | 6 ++ PHPCI/Model/Project.php | 19 +++++ PHPCI/Plugin/Atoum.php | 14 ++++ PHPCI/Plugin/Behat.php | 12 +++ PHPCI/Plugin/Campfire.php | 32 ++++++++ PHPCI/Plugin/CleanBuild.php | 12 +++ PHPCI/Plugin/Codeception.php | 16 ++++ PHPCI/Plugin/Composer.php | 13 ++++ PHPCI/Plugin/CopyBuild.php | 13 ++++ PHPCI/Plugin/Email.php | 22 ++++++ PHPCI/Plugin/Env.php | 6 ++ PHPCI/Plugin/Git.php | 36 +++++++++ PHPCI/Plugin/Grunt.php | 12 +++ PHPCI/Plugin/Gulp.php | 12 +++ PHPCI/Plugin/HipchatNotify.php | 11 +++ PHPCI/Plugin/Irc.php | 16 ++++ PHPCI/Plugin/Lint.php | 31 ++++++++ PHPCI/Plugin/PackageBuild.php | 6 ++ PHPCI/Plugin/Pdepend.php | 6 ++ PHPCI/Plugin/Phar.php | 9 ++- PHPCI/Plugin/Phing.php | 14 ++++ PHPCI/Plugin/PhpCodeSniffer.php | 21 +++++ PHPCI/Plugin/PhpCpd.php | 12 +++ PHPCI/Plugin/PhpCsFixer.php | 20 +++++ PHPCI/Plugin/PhpDocblockChecker.php | 14 +++- PHPCI/Plugin/PhpLoc.php | 13 ++++ PHPCI/Plugin/PhpMessDetector.php | 43 ++++++++++- PHPCI/Plugin/PhpParallelLint.php | 16 ++++ PHPCI/Plugin/PhpSpec.php | 6 ++ PHPCI/Plugin/PhpUnit.php | 39 ++++++++++ PHPCI/Plugin/Shell.php | 12 +++ .../Plugin/Util/ComposerPluginInformation.php | 8 +- PHPCI/Plugin/Util/Executor.php | 8 ++ PHPCI/Plugin/Util/Factory.php | 36 ++++++++- PHPCI/Plugin/Util/FilesPluginInformation.php | 23 ++++++ .../Util/InstalledPluginInformation.php | 5 +- .../Util/PluginInformationCollection.php | 8 ++ PHPCI/Plugin/Util/TapParser.php | 13 ++++ PHPCI/Plugin/Wipe.php | 7 +- PHPCI/Service/BuildService.php | 5 ++ PHPCI/Service/ProjectService.php | 5 ++ PHPCI/Service/UserService.php | 27 +++++++ PHPCI/Store.php | 4 + PHPCI/Store/Base/BuildMetaStoreBase.php | 37 +++++++-- PHPCI/Store/Base/BuildStoreBase.php | 37 +++++++-- PHPCI/Store/Base/ProjectStoreBase.php | 25 +++++- PHPCI/Store/Base/UserStoreBase.php | 20 +++++ PHPCI/Store/BuildStore.php | 34 +++++++++ PHPCI/Store/ProjectStore.php | 9 +++ phpci.yml | 2 +- 83 files changed, 1283 insertions(+), 69 deletions(-) diff --git a/PHPCI/Application.php b/PHPCI/Application.php index 16fab7cf..21565d2f 100644 --- a/PHPCI/Application.php +++ b/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 */ diff --git a/PHPCI/Builder.php b/PHPCI/Builder.php index 69e23ff1..9517f05e 100644 --- a/PHPCI/Builder.php +++ b/PHPCI/Builder.php @@ -251,6 +251,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; @@ -321,6 +325,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); diff --git a/PHPCI/Controller.php b/PHPCI/Controller.php index 57ed81f2..b065e857 100644 --- a/PHPCI/Controller.php +++ b/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); diff --git a/PHPCI/Controller/BuildController.php b/PHPCI/Controller/BuildController.php index a46a094a..cc2f9cb3 100644 --- a/PHPCI/Controller/BuildController.php +++ b/PHPCI/Controller/BuildController.php @@ -33,7 +33,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'); @@ -77,6 +80,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(); @@ -182,6 +189,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( @@ -194,6 +204,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'); diff --git a/PHPCI/Controller/BuildStatusController.php b/PHPCI/Controller/BuildStatusController.php index 5b6cdfd9..71ad1e11 100644 --- a/PHPCI/Controller/BuildStatusController.php +++ b/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); diff --git a/PHPCI/Controller/HomeController.php b/PHPCI/Controller/HomeController.php index 0bb176dc..e7a6caef 100644 --- a/PHPCI/Controller/HomeController.php +++ b/PHPCI/Controller/HomeController.php @@ -31,6 +31,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'); @@ -67,12 +70,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(); diff --git a/PHPCI/Controller/PluginController.php b/PHPCI/Controller/PluginController.php index de9f5e0f..12aa18fc 100644 --- a/PHPCI/Controller/PluginController.php +++ b/PHPCI/Controller/PluginController.php @@ -42,6 +42,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(); @@ -68,6 +72,9 @@ class PluginController extends \PHPCI\Controller return $this->view->render(); } + /** + * Remove a given package. + */ public function remove() { $this->requireAdmin(); @@ -87,6 +94,9 @@ class PluginController extends \PHPCI\Controller die; } + /** + * Install a given package. + */ public function install() { $this->requireAdmin(); @@ -102,6 +112,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'); @@ -124,6 +138,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)) { @@ -152,6 +171,9 @@ class PluginController extends \PHPCI\Controller return null; } + /** + * Perform a search on packagist.org. + */ public function packagistSearch() { $searchQuery = $this->getParam('q', ''); @@ -162,6 +184,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', ''); diff --git a/PHPCI/Controller/ProjectController.php b/PHPCI/Controller/ProjectController.php index 69d8b95e..e92f21e1 100644 --- a/PHPCI/Controller/ProjectController.php +++ b/PHPCI/Controller/ProjectController.php @@ -51,6 +51,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) { diff --git a/PHPCI/Controller/SessionController.php b/PHPCI/Controller/SessionController.php index f7bfa982..cc2fc5e6 100644 --- a/PHPCI/Controller/SessionController.php +++ b/PHPCI/Controller/SessionController.php @@ -25,6 +25,9 @@ class SessionController extends \PHPCI\Controller */ protected $userStore; + /** + * Initialise the controller, set up stores and services. + */ public function init() { $this->response->disableLayout(); @@ -92,6 +95,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') { @@ -135,6 +142,12 @@ MSG; 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); @@ -162,6 +175,10 @@ MSG; 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; diff --git a/PHPCI/Controller/SettingsController.php b/PHPCI/Controller/SettingsController.php index 09dd6bf3..806a4683 100644 --- a/PHPCI/Controller/SettingsController.php +++ b/PHPCI/Controller/SettingsController.php @@ -27,6 +27,9 @@ class SettingsController extends Controller { protected $settings; + /** + * Initialise the controller, set up stores and services. + */ public function init() { parent::init(); @@ -36,6 +39,10 @@ class SettingsController extends Controller $this->settings = $parser->parse($yaml); } + /** + * Display settings forms. + * @return string + */ public function index() { $this->requireAdmin(); @@ -65,6 +72,9 @@ class SettingsController extends Controller return $this->view->render(); } + /** + * Save Github settings. + */ public function github() { $this->requireAdmin(); @@ -82,6 +92,9 @@ class SettingsController extends Controller die; } + /** + * Save email settings. + */ public function email() { $this->requireAdmin(); @@ -100,6 +113,9 @@ class SettingsController extends Controller die; } + /** + * Save build settings. + */ public function build() { $this->requireAdmin(); @@ -163,6 +179,10 @@ class SettingsController extends Controller } } + /** + * Get the Github settings form. + * @return Form + */ protected function getGithubForm() { $form = new Form(); @@ -202,6 +222,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(); @@ -272,6 +297,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'); @@ -280,11 +310,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(); diff --git a/PHPCI/Controller/UserController.php b/PHPCI/Controller/UserController.php index 583381f6..6144b5aa 100644 --- a/PHPCI/Controller/UserController.php +++ b/PHPCI/Controller/UserController.php @@ -35,6 +35,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'); @@ -54,6 +57,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']; diff --git a/PHPCI/Controller/WebhookController.php b/PHPCI/Controller/WebhookController.php index 4a89edd2..d1bf35bb 100644 --- a/PHPCI/Controller/WebhookController.php +++ b/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: diff --git a/PHPCI/Helper/BaseCommandExecutor.php b/PHPCI/Helper/BaseCommandExecutor.php index b1cdbc26..ef2a6a74 100644 --- a/PHPCI/Helper/BaseCommandExecutor.php +++ b/PHPCI/Helper/BaseCommandExecutor.php @@ -12,6 +12,10 @@ namespace PHPCI\Helper; use \PHPCI\Logging\BuildLogger; use Psr\Log\LogLevel; +/** + * Handles running system commands with variables. + * @package PHPCI\Helper + */ abstract class BaseCommandExecutor implements CommandExecutor { /** diff --git a/PHPCI/Helper/Build.php b/PHPCI/Helper/Build.php index 7e3d28d3..65231b4a 100644 --- a/PHPCI/Helper/Build.php +++ b/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))); diff --git a/PHPCI/Helper/BuildInterpolator.php b/PHPCI/Helper/BuildInterpolator.php index 216194ce..c2b625d6 100644 --- a/PHPCI/Helper/BuildInterpolator.php +++ b/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 { /** diff --git a/PHPCI/Helper/Email.php b/PHPCI/Helper/Email.php index 7c44e0f7..3ca15e94 100644 --- a/PHPCI/Helper/Email.php +++ b/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 '; @@ -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); diff --git a/PHPCI/Helper/Github.php b/PHPCI/Helper/Github.php index 6060f2fe..b83b06c3 100644 --- a/PHPCI/Helper/Github.php +++ b/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'); diff --git a/PHPCI/Helper/MailerFactory.php b/PHPCI/Helper/MailerFactory.php index 4eb57c13..641c06b9 100644 --- a/PHPCI/Helper/MailerFactory.php +++ b/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] != "") { diff --git a/PHPCI/Helper/SshKey.php b/PHPCI/Helper/SshKey.php index f36940ca..ca12a815 100644 --- a/PHPCI/Helper/SshKey.php +++ b/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'); diff --git a/PHPCI/Helper/UnixCommandExecutor.php b/PHPCI/Helper/UnixCommandExecutor.php index 4706c934..b922caff 100644 --- a/PHPCI/Helper/UnixCommandExecutor.php +++ b/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)); diff --git a/PHPCI/Helper/User.php b/PHPCI/Helper/User.php index 51f3de42..5d88d392 100644 --- a/PHPCI/Helper/User.php +++ b/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']; diff --git a/PHPCI/Helper/WindowsCommandExecutor.php b/PHPCI/Helper/WindowsCommandExecutor.php index 5cae3041..aa01fea4 100644 --- a/PHPCI/Helper/WindowsCommandExecutor.php +++ b/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)); diff --git a/PHPCI/Logging/BuildDBLogHandler.php b/PHPCI/Logging/BuildDBLogHandler.php index 782471db..bda8cfce 100644 --- a/PHPCI/Logging/BuildDBLogHandler.php +++ b/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']; diff --git a/PHPCI/Logging/BuildLogger.php b/PHPCI/Logging/BuildLogger.php index 062783e1..73f3b464 100644 --- a/PHPCI/Logging/BuildLogger.php +++ b/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; diff --git a/PHPCI/Logging/Handler.php b/PHPCI/Logging/Handler.php index 34d2f179..ebfa2620 100644 --- a/PHPCI/Logging/Handler.php +++ b/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) { diff --git a/PHPCI/Logging/LoggedBuildContextTidier.php b/PHPCI/Logging/LoggedBuildContextTidier.php index 7e550976..cfcfb8b8 100644 --- a/PHPCI/Logging/LoggedBuildContextTidier.php +++ b/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)); diff --git a/PHPCI/Logging/LoggerConfig.php b/PHPCI/Logging/LoggerConfig.php index 0a1ea7fb..69617ee6 100644 --- a/PHPCI/Logging/LoggerConfig.php +++ b/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(); diff --git a/PHPCI/Logging/OutputLogHandler.php b/PHPCI/Logging/OutputLogHandler.php index 3106787e..4b4c81a4 100644 --- a/PHPCI/Logging/OutputLogHandler.php +++ b/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']); diff --git a/PHPCI/Model.php b/PHPCI/Model.php index d1adf9ec..5d911533 100644 --- a/PHPCI/Model.php +++ b/PHPCI/Model.php @@ -9,6 +9,10 @@ namespace PHPCI; +/** + * PHPCI Base Model. + * @package PHPCI + */ abstract class Model extends \b8\Model { diff --git a/PHPCI/Model/Base/ProjectBase.php b/PHPCI/Model/Base/ProjectBase.php index 305cafbf..bcf793ab 100644 --- a/PHPCI/Model/Base/ProjectBase.php +++ b/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. * diff --git a/PHPCI/Model/Build.php b/PHPCI/Model/Build.php index 0286b3b8..6dfef060 100644 --- a/PHPCI/Model/Build.php +++ b/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); diff --git a/PHPCI/Model/Build/GithubBuild.php b/PHPCI/Model/Build/GithubBuild.php index e0ff0fc0..feef147a 100644 --- a/PHPCI/Model/Build/GithubBuild.php +++ b/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'); diff --git a/PHPCI/Model/Build/LocalBuild.php b/PHPCI/Model/Build/LocalBuild.php index 3fd5e532..b94ede4e 100644 --- a/PHPCI/Model/Build/LocalBuild.php +++ b/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)) { diff --git a/PHPCI/Model/Build/RemoteGitBuild.php b/PHPCI/Model/Build/RemoteGitBuild.php index 125515c3..80718011 100644 --- a/PHPCI/Model/Build/RemoteGitBuild.php +++ b/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; diff --git a/PHPCI/Model/Project.php b/PHPCI/Model/Project.php index 98283d77..4a8b3c69 100644 --- a/PHPCI/Model/Project.php +++ b/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()) { diff --git a/PHPCI/Plugin/Atoum.php b/PHPCI/Plugin/Atoum.php index 4bbdb27b..fb0f421f 100644 --- a/PHPCI/Plugin/Atoum.php +++ b/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; diff --git a/PHPCI/Plugin/Behat.php b/PHPCI/Plugin/Behat.php index f6334d05..32266006 100644 --- a/PHPCI/Plugin/Behat.php +++ b/PHPCI/Plugin/Behat.php @@ -24,6 +24,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; diff --git a/PHPCI/Plugin/Campfire.php b/PHPCI/Plugin/Campfire.php index d4506a07..ebdaced1 100644 --- a/PHPCI/Plugin/Campfire.php +++ b/PHPCI/Plugin/Campfire.php @@ -28,6 +28,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; @@ -49,6 +56,10 @@ class Campfire implements \PHPCI\Plugin } + /** + * Run the Campfire plugin. + * @return bool|mixed + */ public function execute() { $url = PHPCI_URL."build/view/".$this->build->getId(); @@ -61,16 +72,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'; @@ -84,6 +110,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; diff --git a/PHPCI/Plugin/CleanBuild.php b/PHPCI/Plugin/CleanBuild.php index af0a6e02..2d33aee4 100644 --- a/PHPCI/Plugin/CleanBuild.php +++ b/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; diff --git a/PHPCI/Plugin/Codeception.php b/PHPCI/Plugin/Codeception.php index e29b81a2..b7fed5e0 100644 --- a/PHPCI/Plugin/Codeception.php +++ b/PHPCI/Plugin/Codeception.php @@ -37,6 +37,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; @@ -65,6 +71,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)) { @@ -90,6 +101,11 @@ class Codeception implements \PHPCI\Plugin } } + /** + * @param $array + * @param $callable + * @return bool|mixed + */ protected function recurseArg($array, $callable) { $success = true; diff --git a/PHPCI/Plugin/Composer.php b/PHPCI/Plugin/Composer.php index dbea469c..c4d3c009 100644 --- a/PHPCI/Plugin/Composer.php +++ b/PHPCI/Plugin/Composer.php @@ -27,6 +27,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'; @@ -38,6 +45,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; diff --git a/PHPCI/Plugin/CopyBuild.php b/PHPCI/Plugin/CopyBuild.php index 9be32395..b50c3b54 100644 --- a/PHPCI/Plugin/CopyBuild.php +++ b/PHPCI/Plugin/CopyBuild.php @@ -26,6 +26,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; @@ -61,6 +67,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)) { @@ -72,6 +82,9 @@ class CopyBuild implements \PHPCI\Plugin } } + /** + * Delete any ignored files from the build prior to copying. + */ protected function deleteIgnoredFiles() { if ($this->ignore) { diff --git a/PHPCI/Plugin/Email.php b/PHPCI/Plugin/Email.php index 70fca197..7df1af9b 100644 --- a/PHPCI/Plugin/Email.php +++ b/PHPCI/Plugin/Email.php @@ -41,6 +41,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, @@ -129,6 +136,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(); @@ -143,6 +157,10 @@ class Email implements \PHPCI\Plugin return $failures; } + /** + * Get the list of email addresses to send to. + * @return array + */ protected function getEmailAddresses() { $addresses = array(); @@ -165,6 +183,10 @@ class Email implements \PHPCI\Plugin return $addresses; } + /** + * Get the list of email addresses to CC. + * @return array + */ protected function getCcAddresses() { $ccAddresses = array(); diff --git a/PHPCI/Plugin/Env.php b/PHPCI/Plugin/Env.php index bb65f51f..26fda6bd 100644 --- a/PHPCI/Plugin/Env.php +++ b/PHPCI/Plugin/Env.php @@ -24,6 +24,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; diff --git a/PHPCI/Plugin/Git.php b/PHPCI/Plugin/Git.php index 4fe6f530..4cd2693d 100644 --- a/PHPCI/Plugin/Git.php +++ b/PHPCI/Plugin/Git.php @@ -24,6 +24,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; @@ -31,6 +37,10 @@ class Git implements \PHPCI\Plugin $this->actions = $options; } + /** + * Run the Git plugin. + * @return bool + */ public function execute() { $buildPath = $this->phpci->buildPath; @@ -57,6 +67,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) { @@ -77,6 +93,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)) { @@ -86,6 +107,11 @@ class Git implements \PHPCI\Plugin } } + /** + * Handle a tag action. + * @param $options + * @return bool + */ protected function runTagAction($options) { $tagName = date('Ymd-His'); @@ -103,6 +129,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(); @@ -119,6 +150,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(); diff --git a/PHPCI/Plugin/Grunt.php b/PHPCI/Plugin/Grunt.php index 106a11b4..1ad0ceec 100644 --- a/PHPCI/Plugin/Grunt.php +++ b/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; diff --git a/PHPCI/Plugin/Gulp.php b/PHPCI/Plugin/Gulp.php index b79fdbfc..97ad9246 100644 --- a/PHPCI/Plugin/Gulp.php +++ b/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; diff --git a/PHPCI/Plugin/HipchatNotify.php b/PHPCI/Plugin/HipchatNotify.php index 10d804ef..02d76bbf 100644 --- a/PHPCI/Plugin/HipchatNotify.php +++ b/PHPCI/Plugin/HipchatNotify.php @@ -26,6 +26,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; @@ -61,6 +68,10 @@ class HipchatNotify implements \PHPCI\Plugin } + /** + * Run the HipChat plugin. + * @return bool + */ public function execute() { $hipChat = new \HipChat\HipChat($this->authToken); diff --git a/PHPCI/Plugin/Irc.php b/PHPCI/Plugin/Irc.php index cdc72491..0c4384e0 100644 --- a/PHPCI/Plugin/Irc.php +++ b/PHPCI/Plugin/Irc.php @@ -28,6 +28,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; @@ -47,6 +59,10 @@ class Irc implements \PHPCI\Plugin } } + /** + * Run IRC plugin. + * @return bool + */ public function execute() { $msg = $this->phpci->interpolate($this->message); diff --git a/PHPCI/Plugin/Lint.php b/PHPCI/Plugin/Lint.php index a43682ba..90436d70 100644 --- a/PHPCI/Plugin/Lint.php +++ b/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; diff --git a/PHPCI/Plugin/PackageBuild.php b/PHPCI/Plugin/PackageBuild.php index e5dcda41..8e40c71f 100644 --- a/PHPCI/Plugin/PackageBuild.php +++ b/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; diff --git a/PHPCI/Plugin/Pdepend.php b/PHPCI/Plugin/Pdepend.php index 54bffd5e..02a536fa 100644 --- a/PHPCI/Plugin/Pdepend.php +++ b/PHPCI/Plugin/Pdepend.php @@ -47,6 +47,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; diff --git a/PHPCI/Plugin/Phar.php b/PHPCI/Plugin/Phar.php index 03415007..0320ed81 100644 --- a/PHPCI/Plugin/Phar.php +++ b/PHPCI/Plugin/Phar.php @@ -203,6 +203,10 @@ class Phar implements \PHPCI\Plugin return $this->stub; } + /** + * Get stub content for the Phar file. + * @return string + */ public function getStubContent() { $content = ''; @@ -213,7 +217,10 @@ class Phar implements \PHPCI\Plugin return $content; } - // Execution + /** + * Run the phar plugin. + * @return bool + */ public function execute() { $success = false; diff --git a/PHPCI/Plugin/Phing.php b/PHPCI/Plugin/Phing.php index 21f7a972..8d026f52 100644 --- a/PHPCI/Plugin/Phing.php +++ b/PHPCI/Plugin/Phing.php @@ -31,6 +31,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); @@ -138,6 +144,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); @@ -180,6 +190,10 @@ class Phing implements \PHPCI\Plugin $this->buildFile = $buildFile; } + /** + * Get phing build file path. + * @return string + */ public function getBuildFilePath() { return $this->getDirectory() . $this->buildFile; diff --git a/PHPCI/Plugin/PhpCodeSniffer.php b/PHPCI/Plugin/PhpCodeSniffer.php index 37778e8a..4b8b7b68 100755 --- a/PHPCI/Plugin/PhpCodeSniffer.php +++ b/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); diff --git a/PHPCI/Plugin/PhpCpd.php b/PHPCI/Plugin/PhpCpd.php index 18fb5f86..cda3683b 100644 --- a/PHPCI/Plugin/PhpCpd.php +++ b/PHPCI/Plugin/PhpCpd.php @@ -36,6 +36,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; @@ -104,6 +110,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); diff --git a/PHPCI/Plugin/PhpCsFixer.php b/PHPCI/Plugin/PhpCsFixer.php index 1d2f6afe..f1cdf855 100644 --- a/PHPCI/Plugin/PhpCsFixer.php +++ b/PHPCI/Plugin/PhpCsFixer.php @@ -36,6 +36,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; @@ -45,6 +57,10 @@ class PhpCsFixer implements \PHPCI\Plugin $this->buildArgs($options); } + /** + * Run PHP CS Fixer. + * @return bool + */ public function execute() { $curdir = getcwd(); @@ -65,6 +81,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']) { diff --git a/PHPCI/Plugin/PhpDocblockChecker.php b/PHPCI/Plugin/PhpDocblockChecker.php index eafbda96..d84c2d52 100755 --- a/PHPCI/Plugin/PhpDocblockChecker.php +++ b/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; diff --git a/PHPCI/Plugin/PhpLoc.php b/PHPCI/Plugin/PhpLoc.php index 6e402cc7..5e4c5c7f 100644 --- a/PHPCI/Plugin/PhpLoc.php +++ b/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; diff --git a/PHPCI/Plugin/PhpMessDetector.php b/PHPCI/Plugin/PhpMessDetector.php index 6b0f3a65..59efa8e3 100755 --- a/PHPCI/Plugin/PhpMessDetector.php +++ b/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; diff --git a/PHPCI/Plugin/PhpParallelLint.php b/PHPCI/Plugin/PhpParallelLint.php index 3787fd0c..2b37b956 100644 --- a/PHPCI/Plugin/PhpParallelLint.php +++ b/PHPCI/Plugin/PhpParallelLint.php @@ -40,6 +40,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; @@ -87,6 +99,10 @@ class PhpParallelLint implements \PHPCI\Plugin return $success; } + /** + * Produce an argument string for PHP Parallel Lint. + * @return array + */ protected function getFlags() { $ignore = ''; diff --git a/PHPCI/Plugin/PhpSpec.php b/PHPCI/Plugin/PhpSpec.php index 7fbc332e..6564d8ff 100644 --- a/PHPCI/Plugin/PhpSpec.php +++ b/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; diff --git a/PHPCI/Plugin/PhpUnit.php b/PHPCI/Plugin/PhpUnit.php index c643416b..0d7a7ba8 100644 --- a/PHPCI/Plugin/PhpUnit.php +++ b/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; diff --git a/PHPCI/Plugin/Shell.php b/PHPCI/Plugin/Shell.php index fceea3e2..3c28de81 100644 --- a/PHPCI/Plugin/Shell.php +++ b/PHPCI/Plugin/Shell.php @@ -37,6 +37,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; diff --git a/PHPCI/Plugin/Util/ComposerPluginInformation.php b/PHPCI/Plugin/Util/ComposerPluginInformation.php index c870514e..1f022b4a 100644 --- a/PHPCI/Plugin/Util/ComposerPluginInformation.php +++ b/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) { diff --git a/PHPCI/Plugin/Util/Executor.php b/PHPCI/Plugin/Util/Executor.php index 15754f84..cfa27e59 100644 --- a/PHPCI/Plugin/Util/Executor.php +++ b/PHPCI/Plugin/Util/Executor.php @@ -4,6 +4,10 @@ namespace PHPCI\Plugin\Util; use \PHPCI\Logging\BuildLogger; +/** + * Plugin Executor - Runs the configured plugins for a given build stage. + * @package PHPCI\Plugin\Util + */ class Executor { /** @@ -16,6 +20,10 @@ class Executor */ protected $pluginFactory; + /** + * @param Factory $pluginFactory + * @param BuildLogger $logger + */ public function __construct(Factory $pluginFactory, BuildLogger $logger) { $this->pluginFactory = $pluginFactory; diff --git a/PHPCI/Plugin/Util/Factory.php b/PHPCI/Plugin/Util/Factory.php index 971b3e23..5430b56f 100644 --- a/PHPCI/Plugin/Util/Factory.php +++ b/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(); diff --git a/PHPCI/Plugin/Util/FilesPluginInformation.php b/PHPCI/Plugin/Util/FilesPluginInformation.php index 5465f470..6bad028f 100644 --- a/PHPCI/Plugin/Util/FilesPluginInformation.php +++ b/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 diff --git a/PHPCI/Plugin/Util/InstalledPluginInformation.php b/PHPCI/Plugin/Util/InstalledPluginInformation.php index 133b8de8..821c511c 100644 --- a/PHPCI/Plugin/Util/InstalledPluginInformation.php +++ b/PHPCI/Plugin/Util/InstalledPluginInformation.php @@ -1,7 +1,10 @@ pluginInformations[] = $information; diff --git a/PHPCI/Plugin/Util/TapParser.php b/PHPCI/Plugin/Util/TapParser.php index a18e89e5..19632a90 100644 --- a/PHPCI/Plugin/Util/TapParser.php +++ b/PHPCI/Plugin/Util/TapParser.php @@ -2,6 +2,10 @@ namespace PHPCI\Plugin\Util; +/** + * Processes TAP format strings into usable test result data. + * @package PHPCI\Plugin\Util + */ class TapParser { const TEST_COUNTS_PATTERN = '/([0-9]+)\.\.([0-9]+)/'; @@ -73,6 +77,11 @@ class TapParser return $rtn; } + /** + * Process the individual test lines within a TAP string. + * @param $lines + * @return array + */ protected function processTestLines($lines) { $rtn = array(); @@ -104,6 +113,10 @@ class TapParser return $rtn; } + /** + * Get the total number of failures from the current TAP file. + * @return int + */ public function getTotalFailures() { return $this->failures; diff --git a/PHPCI/Plugin/Wipe.php b/PHPCI/Plugin/Wipe.php index e87800b4..1a71e293 100644 --- a/PHPCI/Plugin/Wipe.php +++ b/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; diff --git a/PHPCI/Service/BuildService.php b/PHPCI/Service/BuildService.php index 300df728..b4721779 100644 --- a/PHPCI/Service/BuildService.php +++ b/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 { /** diff --git a/PHPCI/Service/ProjectService.php b/PHPCI/Service/ProjectService.php index 1bc1b248..a0b4837f 100644 --- a/PHPCI/Service/ProjectService.php +++ b/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 { /** diff --git a/PHPCI/Service/UserService.php b/PHPCI/Service/UserService.php index 8f20044f..2d9b070d 100644 --- a/PHPCI/Service/UserService.php +++ b/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); diff --git a/PHPCI/Store.php b/PHPCI/Store.php index bb8e4a21..71522638 100644 --- a/PHPCI/Store.php +++ b/PHPCI/Store.php @@ -9,6 +9,10 @@ namespace PHPCI; +/** + * PHPCI Base Store + * @package PHPCI + */ abstract class Store extends \b8\Store { diff --git a/PHPCI/Store/Base/BuildMetaStoreBase.php b/PHPCI/Store/Base/BuildMetaStoreBase.php index f6158c13..36a94f9d 100644 --- a/PHPCI/Store/Base/BuildMetaStoreBase.php +++ b/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); diff --git a/PHPCI/Store/Base/BuildStoreBase.php b/PHPCI/Store/Base/BuildStoreBase.php index 20927caa..cb1b2824 100644 --- a/PHPCI/Store/Base/BuildStoreBase.php +++ b/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); diff --git a/PHPCI/Store/Base/ProjectStoreBase.php b/PHPCI/Store/Base/ProjectStoreBase.php index dda946a5..02692f62 100644 --- a/PHPCI/Store/Base/ProjectStoreBase.php +++ b/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); diff --git a/PHPCI/Store/Base/UserStoreBase.php b/PHPCI/Store/Base/UserStoreBase.php index fd903d8e..24d247e3 100644 --- a/PHPCI/Store/Base/UserStoreBase.php +++ b/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)) { diff --git a/PHPCI/Store/BuildStore.php b/PHPCI/Store/BuildStore.php index a355ac68..fc445f54 100644 --- a/PHPCI/Store/BuildStore.php +++ b/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`'; diff --git a/PHPCI/Store/ProjectStore.php b/PHPCI/Store/ProjectStore.php index 4657fb8d..5f58fcc8 100644 --- a/PHPCI/Store/ProjectStore.php +++ b/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'; diff --git a/phpci.yml b/phpci.yml index 20419bda..bcbd5e30 100644 --- a/phpci.yml +++ b/phpci.yml @@ -23,7 +23,7 @@ test: php_loc: php_unit: php_docblock_checker: - allowed_warnings: -1 # Allow unlimited warnings for now. + allowed_warnings: 0 failure: email: