Permalink
Browse files

update docblocks, and minor changes

  • Loading branch information...
1 parent 01f9679 commit 3181f83defdf559d1e21dab488d500bfdb38cd86 @pmjones pmjones committed Feb 13, 2012
View
1 config/default.php
@@ -19,7 +19,6 @@
];
$di->setter['Aura\Framework\Cli\MakeTest\Command'] = [
- 'setInflect' => $di->lazyGet('framework_inflect'),
'setPhpunit' => 'phpunit',
'setBootstrap' => dirname(__DIR__) . '/tests/bootstrap.php',
'setSystem' => $di->lazyGet('framework_system'),
View
61 src/Aura/Framework/Bootstrap.php
@@ -21,14 +21,49 @@
*/
class Bootstrap
{
+ /**
+ *
+ * The System object.
+ *
+ * @var System
+ *
+ */
protected $system;
+ /**
+ *
+ * The autoloader object.
+ *
+ * @var Aura\Autoloader\Loader
+ *
+ */
protected $loader;
+ /**
+ *
+ * The Config object.
+ *
+ * @var Config
+ *
+ */
protected $config;
+ /**
+ *
+ * The dependency injection container.
+ *
+ * @var Aura\Di\Container
+ *
+ */
protected $di;
+ /**
+ *
+ * Execution setup method.
+ *
+ * @return void
+ *
+ */
public function exec()
{
// turn up error reporting
@@ -82,6 +117,13 @@ public function exec()
// done!
}
+ /**
+ *
+ * Execute bootstrap in a web context.
+ *
+ * @return void
+ *
+ */
public function execWeb()
{
try {
@@ -95,6 +137,15 @@ public function execWeb()
}
}
+ /**
+ *
+ * Execute bootstrap in a CLI context.
+ *
+ * @param string $class The command class to instantiate and execute.
+ *
+ * @return void
+ *
+ */
public function execCli($class)
{
try {
@@ -109,6 +160,16 @@ public function execCli($class)
}
}
+ /**
+ *
+ * Require a file in a limited scope with variables for `$system`,
+ * `$loader`, and `$di`. Generally for loading PHP-based config files.
+ *
+ * @param string $file The file to require.
+ *
+ * @return mixed
+ *
+ */
public function load($file)
{
$system = $this->system->getRootPath();
View
38 src/Aura/Framework/Cli/AbstractCommand.php
@@ -1,11 +1,42 @@
<?php
+/**
+ *
+ * This file is part of the Aura project for PHP.
+ *
+ * @license http://opensource.org/licenses/bsd-license.php BSD
+ *
+ */
namespace Aura\Framework\Cli;
use Aura\Cli\AbstractCommand as AbstractCliCommand;
use Aura\Signal\Manager as SignalManager;
+
+/**
+ *
+ * Abstract class for framework commands.
+ *
+ * @package Aura.Framework
+ *
+ */
abstract class AbstractCommand extends AbstractCliCommand
{
+ /**
+ *
+ * A signal manager.
+ *
+ * @var SignalManager
+ *
+ */
protected $signal;
+ /**
+ *
+ * Sets the signal manager and adds handler hooks.
+ *
+ * @param SignalManager $signal The signal manager.
+ *
+ * @return void
+ *
+ */
public function setSignal(SignalManager $signal)
{
$this->signal = $signal;
@@ -15,6 +46,13 @@ public function setSignal(SignalManager $signal)
$this->signal->handler($this, 'post_exec', [$this, 'postExec']);
}
+ /**
+ *
+ * Executes the action while invoking signal manager hooks.
+ *
+ * @return mixed
+ *
+ */
public function exec()
{
$this->signal->send($this, 'pre_exec', $this);
View
24 src/Aura/Framework/Cli/CacheClassmap/Command.php
@@ -12,20 +12,42 @@
/**
*
- * Caches all package source class files.
+ * Caches the map of package source class files to `tmp/cache/classmap.php`.
*
* @package Aura.Framework
*
*/
class Command extends AbstractCommand
{
+ /**
+ *
+ * The System object.
+ *
+ * @var System
+ *
+ */
protected $system;
+ /**
+ *
+ * Sets the system object.
+ *
+ * @param System $system The system object.
+ *
+ */
public function setSystem(System $system)
{
$this->system = $system;
}
+ /**
+ *
+ * Caches the map of package source class files to
+ * `tmp/cache/classmap.php`.
+ *
+ * @return mixed
+ *
+ */
public function action()
{
$this->stdio->outln("Caching package class map ... ");
View
38 src/Aura/Framework/Cli/CacheConfig/Command.php
@@ -12,20 +12,43 @@
/**
*
- * Caches all package source class files.
+ * Caches all mode-specific package config files to
+ * `tmp/cache/config/{$mode}.php`.
*
* @package Aura.Framework
*
*/
class Command extends AbstractCommand
{
+ /**
+ *
+ * The System object.
+ *
+ * @var System
+ *
+ */
protected $system;
+ /**
+ *
+ * Sets the system object.
+ *
+ * @param System $system The system object.
+ *
+ */
public function setSystem(System $system)
{
$this->system = $system;
}
+ /**
+ *
+ * Caches the mode-specific package config files to
+ * `tmp/cache/config/{$mode}.php`.
+ *
+ * @return mixed
+ *
+ */
public function action()
{
if (! isset($this->params[0])) {
@@ -58,6 +81,19 @@ public function action()
$this->stdio->outln('Done.');
}
+ /**
+ *
+ * Reads a config file from a package directory; replaces __DIR__ and
+ * __FILE__ constants with string values so that the original values
+ * are honored regardless of where the cached configs are placed.
+ *
+ * @param string $package_dir The package directory.
+ *
+ * @param string $mode The config mode to read.
+ *
+ * @return string The config file, with __DIR__ and
+ *
+ */
protected function read($package_dir, $mode)
{
// is there a mode-specific config file?
View
7 src/Aura/Framework/Cli/HelloWorld/Command.php
@@ -18,6 +18,13 @@
*/
class Command extends AbstractCommand
{
+ /**
+ *
+ * Sends "Hello World!" to standard output.
+ *
+ * @return void
+ *
+ */
public function action()
{
$this->stdio->outln("Hello World!");
View
44 src/Aura/Framework/Cli/MakeTest/Command.php
@@ -17,71 +17,60 @@
/**
*
- * This command uses PHPUnit to make a skeleton test file from an existing
- * class.
+ * Using PHPUnit, creates a test file from an existing package source class
+ * and places it in the package tests directory.
*
* Usage is ...
*
* $ php package/Aura.Framework/cli/make-test {$FILE}
*
* ... where `$FILE` is a package file path, e.g.
- * `package/Aura.Framework/System.php`.
+ * `package/Vendor.Package/src/Vendor/Package/Class.php`.
*
* @package Aura.Framework
*
- * @todo Include path/autoloader is not honored by the phpunit test creator.
- *
*/
class Command extends AbstractCommand
{
/**
*
- * A word inflector.
+ * A system object.
*
- * @var Inflect
+ * @var System
*
*/
- protected $inflect;
+ protected $system;
/**
*
- * A system object.
+ * The `phpunit` executable path.
*
- * @var System
+ * @var string
*
*/
- protected $system;
-
protected $phpunit;
- protected $bootstrap;
-
/**
*
- * Sets a System object for this class.
+ * The bootstrap file PHPUnit should load.
*
- * @param System $system The System object.
- *
- * @return void
+ * @var string
*
*/
- public function setSystem(System $system)
- {
- $this->system = $system;
- }
+ protected $bootstrap;
/**
*
- * Sets an Inflect object for this class.
+ * Sets a System object for this class.
*
- * @param Inflect $inflect An Inflect object.
+ * @param System $system The System object.
*
* @return void
*
*/
- public function setInflect(Inflect $inflect)
+ public function setSystem(System $system)
{
- $this->inflect = $inflect;
+ $this->system = $system;
}
/**
@@ -112,7 +101,8 @@ public function setBootstrap($bootstrap)
/**
*
- * Creates a test file from an existing class.
+ * Creates a test file from an existing package source class and places
+ * it in the package tests directory.
*
* @return void
*
View
122 src/Aura/Framework/Config.php
@@ -1,18 +1,80 @@
<?php
+/**
+ *
+ * This file is part of the Aura project for PHP.
+ *
+ * @license http://opensource.org/licenses/bsd-license.php BSD
+ *
+ */
namespace Aura\Framework;
use Aura\Autoload\Loader;
use Aura\Di\Container;
+/**
+ *
+ * Loads config values from package and system config files.
+ *
+ * @package Aura.Framework
+ *
+ */
class Config
{
- public $system;
+ /**
+ *
+ * The System object.
+ *
+ * @var System
+ *
+ */
+ protected $system;
- public $loader;
+ /**
+ *
+ * The autoloader object.
+ *
+ * @var Aura\Autoloader\Loader
+ *
+ */
+ protected $loader;
- public $di;
+ /**
+ *
+ * The dependency injection container.
+ *
+ * @var Aura\Di\Container
+ *
+ */
+ protected $di;
- public $files;
+ /**
+ *
+ * Config files that have been loaded.
+ *
+ * @var array
+ *
+ */
+ protected $files;
+ /**
+ *
+ * The config mode.
+ *
+ * @var string
+ *
+ */
+ protected $mode;
+
+ /**
+ *
+ * Constructor.
+ *
+ * @param System $system The System object.
+ *
+ * @param Loader $loader The autoloader object.
+ *
+ * @param Container $di The dependency injection container.
+ *
+ */
public function __construct(System $system, Loader $loader, Container $di)
{
$this->system = $system;
@@ -23,16 +85,38 @@ public function __construct(System $system, Loader $loader, Container $di)
: $_ENV['AURA_CONFIG_MODE'];
}
+ /**
+ *
+ * Returns the config mode.
+ *
+ * @return string The config mode.
+ *
+ */
public function getMode()
{
return $this->mode;
}
+ /**
+ *
+ * Returns the list of config files that have been loaded.
+ *
+ * @return array The loaded config files.
+ *
+ */
public function getFiles()
{
return $this->files;
}
+ /**
+ *
+ * Loads config files, either from the cache or from the packages, and
+ * for the system mode config file.
+ *
+ * @return void
+ *
+ */
public function exec()
{
$cache_file = $this->getCacheFile();
@@ -45,6 +129,13 @@ public function exec()
$this->loadMode();
}
+ /**
+ *
+ * Gets the name of the config cache file.
+ *
+ * @return mixed The config file path, or null if not readable.
+ *
+ */
public function getCacheFile()
{
$file = $this->system->getTmpPath("cache/config/{$this->mode}.php");
@@ -53,6 +144,13 @@ public function getCacheFile()
}
}
+ /**
+ *
+ * Loads each package config file for the mode.
+ *
+ * @return void
+ *
+ */
public function loadFromPackages()
{
$package_glob = $this->system->getPackagePath('*');
@@ -81,6 +179,13 @@ public function loadFromPackages()
}
}
+ /**
+ *
+ * Loads the system-level config file for the current mode.
+ *
+ * @return void
+ *
+ */
public function loadMode()
{
$file = $this->system->getConfigPath("{$this->mode}.php");
@@ -89,6 +194,15 @@ public function loadMode()
}
}
+ /**
+ *
+ * Loads a config file in a limited scope.
+ *
+ * @param string $file The config file to load.
+ *
+ * @return void
+ *
+ */
public function load($file)
{
$system = $this->system->getRootPath();
View
8 src/Aura/Framework/Exception/NoClassForController.php
@@ -7,4 +7,12 @@
*
*/
namespace Aura\Framework\Exception;
+
+/**
+ *
+ * Could not find a class mapped to a controller name.
+ *
+ * @package Aura.Framework
+ *
+ */
class NoClassForController extends \Aura\Framework\Exception {}
View
8 src/Aura/Framework/Exception/TestFileNotCreated.php
@@ -7,4 +7,12 @@
*
*/
namespace Aura\Framework\Exception;
+
+/**
+ *
+ * The requested test file was not created.
+ *
+ * @package Aura.Framework
+ *
+ */
class TestFileNotCreated extends \Aura\Framework\Exception {}
View
8 src/Aura/Framework/Exception/TestFileNotMoved.php
@@ -7,4 +7,12 @@
*
*/
namespace Aura\Framework\Exception;
+
+/**
+ *
+ * The test file could not be moved to its proper location.
+ *
+ * @package Aura.Framework
+ *
+ */
class TestFileNotMoved extends \Aura\Framework\Exception {}
View
10 src/Aura/Framework/System.php
@@ -140,6 +140,16 @@ public function getIncludePath($sub = null)
return $this->getSubPath('include', $sub);
}
+ /**
+ *
+ * Gets the web path for the Aura system, along with an optional
+ * subdirectory path.
+ *
+ * @param string $sub An optional subdirectory path.
+ *
+ * @return The full directory path, with proper directory separators.
+ *
+ */
public function getWebPath($sub = null)
{
return $this->getSubPath('web', $sub);
View
14 src/Aura/Framework/View/Helper/AssetHref.php
@@ -18,11 +18,25 @@
*/
class AssetHref extends AbstractHelper
{
+ /**
+ *
+ * Sets the base (prefix) href for all asset hrefs.
+ *
+ * @param string $base The base href.
+ *
+ */
public function setBase($base)
{
$this->base = rtrim($base, '/');
}
+ /**
+ *
+ * Returns the href for an asset.
+ *
+ * @param string $href The asset href, prefixed with the base href.
+ *
+ */
public function __invoke($href)
{
return $this->base . '/' . ltrim($href, '/');
View
118 src/Aura/Framework/Web/AbstractPage.php
@@ -1,4 +1,11 @@
<?php
+/**
+ *
+ * This file is part of the Aura project for PHP.
+ *
+ * @license http://opensource.org/licenses/bsd-license.php BSD
+ *
+ */
namespace Aura\Framework\Web;
use Aura\Framework\Inflect;
use Aura\Framework\System;
@@ -7,28 +14,97 @@
use Aura\View\TwoStep;
use Aura\Web\AbstractPage as WebAbstractPage;
+/**
+ *
+ * An abstract web page controller for the framework.
+ *
+ * @package Aura.Framework
+ *
+ */
abstract class AbstractPage extends WebAbstractPage
{
+ /**
+ *
+ * An inflection object.
+ *
+ * @var Inflect
+ *
+ */
protected $inflect;
+ /**
+ *
+ * A router object.
+ *
+ * @var RouterMap
+ *
+ */
protected $router;
+ /**
+ *
+ * A signal manager
+ *
+ * @var SignalManager
+ *
+ */
protected $signal;
+ /**
+ *
+ * A system object.
+ *
+ * @var System
+ *
+ */
protected $system;
+ /**
+ *
+ * A two-step view object.
+ *
+ * @var TwoStep
+ *
+ */
protected $view;
+ /**
+ *
+ * Sets the inflection object.
+ *
+ * @param Inflect $inflect The inflection object.
+ *
+ * @return void
+ *
+ */
public function setInflect(Inflect $inflect)
{
$this->inflect = $inflect;
}
+ /**
+ *
+ * Sets the router object.
+ *
+ * @param RouterMap $router The router object.
+ *
+ * @return void
+ *
+ */
public function setRouter(RouterMap $router)
{
$this->router = $router;
}
+ /**
+ *
+ * Sets the signal manager and adds handlers for hooks.
+ *
+ * @param SignalManager $signal The signal manager.
+ *
+ * @return void
+ *
+ */
public function setSignal(SignalManager $signal)
{
$this->signal = $signal;
@@ -40,24 +116,45 @@ public function setSignal(SignalManager $signal)
$this->signal->handler($this, 'post_exec', [$this, 'postExec']);
}
+ /**
+ *
+ * Sets the system object.
+ *
+ * @param System $system The system object.
+ *
+ * @return void
+ *
+ */
public function setSystem(System $system)
{
$this->system = $system;
}
+ /**
+ *
+ * Sets the two-step view object and sets inner and outer template paths.
+ *
+ * @param TwoStep $view The two-step view object.
+ *
+ * @return void
+ *
+ */
public function setView(TwoStep $view)
{
$this->view = $view;
// get all included files
$includes = array_reverse(get_included_files());
- // get the class hierarchy, dropping Aura.Web and Aura.Framework,
- // and adding this class itself
+ // get the class hierarchy stack
$class = get_class($this);
$stack = class_parents($class);
+
+ // drop Aura.Web and Aura.Framework
array_pop($stack);
array_pop($stack);
+
+ // add this class itself
array_unshift($stack, $class);
// go through the hierarchy and look for each class file
@@ -78,6 +175,13 @@ public function setView(TwoStep $view)
}
}
+ /**
+ *
+ * Executes the page action, invoking hooks via the signal manager.
+ *
+ * @return Aura\Web\Response
+ *
+ */
public function exec()
{
// prep
@@ -98,6 +202,16 @@ public function exec()
return $this->response;
}
+ /**
+ *
+ * Renders the view into the response and sets the response content-type.
+ *
+ * N.b.: If the response content is already set, the view will not be
+ * rendered.
+ *
+ * @return void
+ *
+ */
protected function render()
{
$this->view->setFormat($this->getFormat());
View
2 src/Aura/Framework/Web/Factory.php
@@ -15,8 +15,6 @@
* A factory to create controller objects; these need not be only Page
* controllers, but (e.g.) Resource or App controllers.
*
- * @package Aura.Web
- *
* @package Aura.Framework
*
*/
View
42 src/Aura/Framework/Web/Front.php
@@ -51,17 +51,48 @@ class Front
*/
protected $response;
+ /**
+ *
+ * A page controller factory.
+ *
+ * @var Aura\Framework\Web\Factory
+ *
+ */
protected $factory;
+ /**
+ *
+ * A signal manager.
+ *
+ * @var Aura\Signal\Manager
+ *
+ */
protected $signal;
+ /**
+ *
+ * A router map.
+ *
+ * @var Aura\Router\Map
+ *
+ */
protected $router;
/**
*
* Constructor.
*
+ * @param SignalManager $signal A signal manager.
+ *
+ * @param Context $context The web context.
+ *
+ * @param RouterMap $router The router map.
+ *
+ * @param Factory $factory A web page controller factory.
+ *
+ * @param HttpResponse $response The eventual HTTP response object.
+ *
*/
public function __construct(
SignalManager $signal,
@@ -96,8 +127,6 @@ public function __get($key)
* Dispatches a Route to a web controller, renders a view into the
* ReponseTransfer, and returns an HTTP response.
*
- * @return Aura\Http\Response
- *
* @signal pre_exec
*
* @signal pre_request
@@ -110,6 +139,8 @@ public function __get($key)
*
* @signal post_exec
*
+ * @return Aura\Http\Response
+ *
*/
public function exec()
{
@@ -131,6 +162,13 @@ public function exec()
return $this->response;
}
+ /**
+ *
+ * Handle the incoming request.
+ *
+ * @return void
+ *
+ */
public function request()
{
// match to a route
View
29 src/Aura/Framework/Web/Hello/Page.php
@@ -1,13 +1,42 @@
<?php
+/**
+ *
+ * This file is part of the Aura Project for PHP.
+ *
+ * @license http://opensource.org/licenses/bsd-license.php BSD
+ *
+ */
namespace Aura\Framework\Web\Hello;
use Aura\Framework\Web\AbstractPage;
+
+/**
+ *
+ * A basic controller to show "Hello world" or an image asset.
+ *
+ * @package Aura.Framework
+ *
+ */
class Page extends AbstractPage
{
+ /**
+ *
+ * Sets the inner view to "world" and does nothing else.
+ *
+ * @return void
+ *
+ */
public function actionWorld()
{
$this->view->setInnerView('world');
}
+ /**
+ *
+ * Sets the inner view to "asset" and does nothing else.
+ *
+ * @return void
+ *
+ */
public function actionAsset()
{
$this->view->setInnerView('asset');
View
11 src/Aura/Framework/Web/Hello/view/asset.php
@@ -1 +1,12 @@
+<?php
+/**
+ *
+ * This file is part of the Aura Project for PHP.
+ *
+ * @license http://opensource.org/licenses/bsd-license.php BSD
+ *
+ * @package Aura.Framework
+ *
+ */
+?>
<img src="/asset/Aura.Framework/images/auralogo.jpg" />
View
11 src/Aura/Framework/Web/Hello/view/world.php
@@ -1 +1,12 @@
+<?php
+/**
+ *
+ * This file is part of the Aura Project for PHP.
+ *
+ * @license http://opensource.org/licenses/bsd-license.php BSD
+ *
+ * @package Aura.Framework
+ *
+ */
+?>
Hello World!
View
40 src/Aura/Framework/Web/NotFound/Page.php
@@ -1,22 +1,54 @@
<?php
+/**
+ *
+ * This file is part of the Aura Project for PHP.
+ *
+ * @license http://opensource.org/licenses/bsd-license.php BSD
+ *
+ */
namespace Aura\Framework\Web\NotFound;
use Aura\Framework\Web\AbstractPage;
+
+/**
+ *
+ * Show this when a page controller could not be found for the request.
+ *
+ * @package Aura.Framework
+ *
+ */
class Page extends AbstractPage
{
- // force the action to "index"
+ /**
+ *
+ * Force the action to "index".
+ *
+ * @return void
+ *
+ */
public function preExec()
{
$this->action = 'index';
}
+ /**
+ *
+ * Shows information about what happened.
+ *
+ * @return void
+ *
+ */
public function actionIndex()
{
$uri = htmlspecialchars(
- var_export($this->context->getServer('REQUEST_URI'), true)
+ var_export($this->context->getServer('REQUEST_URI'), true),
+ ENT_QUOTES,
+ 'UTF-8'
);
$path = htmlspecialchars(
- var_export($this->context->getServer('PATH_INFO', '/'), true)
+ var_export($this->context->getServer('PATH_INFO', '/'), true),
+ ENT_QUOTES,
+ 'UTF-8'
);
$html = <<<HTML
@@ -31,7 +63,7 @@ public function actionIndex()
<ol>
<li>An <code>Aura\\Router\\Map</code> route for the path <code>$path</code></li>
<li>A <code>['values']['controller']</code> value for the mapped route</li>
- <li>A <code>\$di->params['Aura\Framework\Web\Factory']['map']</code> entry for the controller value.</li>
+ <li>A <code>\$di->params['Aura\\Framework\\Web\\Factory']['map']</code> entry for the controller value.</li>
</ol>
</body>
</html>
View
5 tests/Aura/Framework/Cli/MakeTest/CommandTest.php
@@ -1,7 +1,6 @@
<?php
namespace Aura\Framework\Cli\MakeTest;
use Aura\Framework\Cli\AbstractCommandTest;
-use Aura\Framework\Inflect;
/**
* Test class for make_test\Command.
@@ -10,14 +9,10 @@ class CommandTest extends AbstractCommandTest
{
protected $command_name = 'MakeTest';
- protected $inflect;
-
protected function newCommand($argv = [])
{
$command = parent::newCommand($argv);
- $this->inflect = new Inflect;
$command->setSystem($this->system);
- $command->setInflect($this->inflect);
$command->setPhpunit('phpunit');
// note that we do not set the bootstrap
return $command;
View
2 tests/Aura/Framework/Web/NotFound/PageTest.php
@@ -27,7 +27,7 @@ public function testActionIndex()
<p>No controller found for <code>NULL</code></p>
<p>Please check that your config has:</p>
<ol>
- <li>An <code>Aura\Router\Map</code> route for the path <code>'/'</code></li>
+ <li>An <code>Aura\Router\Map</code> route for the path <code>&#039;/&#039;</code></li>
<li>A <code>['values']['controller']</code> value for the mapped route</li>
<li>A <code>\$di->params['Aura\Framework\Web\Factory']['map']</code> entry for the controller value.</li>
</ol>

0 comments on commit 3181f83

Please sign in to comment.