Version 1 by Ralph Schindler
on May 12, 2008 12:20.

compared with
Current by Ralph Schindler
on May 15, 2008 08:45.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (121)

View Page History
h1. Zend_Tool_CommandSystem

h2. Goals
<h1>Zend_Tool_Rpc</h1>

Zend_Tool_CommandSystem is a framework that provides:
* common interfaces, abstracts that allow will allow developers (through the most minimal of efforts) to create functionality and capabilities that are dispatchable by "tooling clients" (1).
* Implementation of "endpoints" (5) to be used to connect "tooling clients" to the Zend_Tool_CommandSystem, the primary endpoint implementation being that of the "Command Line Interface Endpoint" (6)
* Implement a stardard set of "providers" (8) that allow the system to report what the full capabilities of the system are as well as provide useful feedback. This might also be known as a "Help System".
<h2>Goals</h2>

In a more general sense, Zend_Tool_CommandSystem might be useful in creating a system that can expose common functionalities such as the creation of files, the creation of project scaffolds, building of indexes, ... the list goes on. Central to all of the tasks of tooling is a resounding theme:
<p>Zend_Tool_Rpc is a framework that provides:</p>
<ul>
<li>common interfaces, abstracts that allow will allow developers (through the most minimal of efforts) to create functionality and capabilities that are dispatchable by &quot;tooling clients&quot; (1).</li>
<li>Implementation of &quot;endpoints&quot; (5) to be used to connect &quot;tooling clients&quot; to the Zend_Tool_Rpc, the primary endpoint implementation being that of the &quot;Command Line Interface Endpoint&quot; (6)</li>
<li>Implement a stardard set of &quot;providers&quot; (8) that allow the system to report what the full capabilities of the system are as well as provide useful feedback. This might also be known as a &quot;Help System&quot;.</li>
</ul>

"Dont work harder, work smarter."

<p>In a more general sense, Zend_Tool_Rpc might be useful in creating a system that can expose common functionalities such as the creation of files, the creation of project scaffolds, building of indexes, ... the list goes on. Central to all of the tasks of tooling is a resounding theme: </p>

h2. The subsystems that make up Zend_Tool_CommandSystem
<p>&quot;Dont work harder, work smarter.&quot;</p>

h3. Zend_Tool_CommandSystem_Provider
<h2>The subsystems that make up Zend_Tool_Rpc</h2>

Zend_Tool_CommandSystem_Provider represents the functional or "capability" aspect of the Zend_Tool_CommandSystem framework. Fundamentally, Zend_Tool_CommandSystem_Provider will provide the interfaces and abstracts necessary to produce "providers", or bits of tooling functionality, that can be called and used inside the Zend_Tool_CommandSystem toolchain. The simplistic nature of extending this "provider abstract" allows the developer a "one-stop-shop" of adding functionality/capabilities to the Zend_Tool_CommandSystem.
<h3>Zend_Tool_Rpc_Provider &amp; Zend_Tool_Rpc_ProviderAbstract</h3>

Here is the abstract for the provider to get a sense for what this sub-system is responsible for:
<p>Zend_Tool_Rpc_Provider represents the functional or &quot;capability&quot; aspect of the Zend_Tool_Rpc framework. Fundamentally, Zend_Tool_Rpc_Provider will provide the interfaces and abstracts necessary to produce &quot;providers&quot;, or bits of tooling functionality, that can be called and used inside the Zend_Tool_Rpc toolchain. The simplistic nature of extending this &quot;provider abstract&quot; allows the developer a &quot;one-stop-shop&quot; of adding functionality/capabilities to the Zend_Tool_Rpc.</p>

<p>Here is the abstract for the provider to get a sense for what this sub-system is responsible for:</p>
{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
<?php

abstract class Zend_Tool_CommandSystem_ProviderAbstract Zend_Tool_Rpc_ProviderAbstract
{
/**

/**
* @var Zend_Tool_CommandSystem_Manifest Zend_Tool_Rpc_Endpoint_Request
*/
protected $_manifest = null;

/**
* @var Zend_Tool_CommandSystem_Endpoint_Request
*/
protected $_request = null;

/**
* @var Zend_Tool_CommandSystem_Endpoint_Response Zend_Tool_Rpc_Endpoint_Response
*/
protected $_response = null;

/**
* @var Zend_Tool_CommandSystem_Provider_Action Zend_Tool_Rpc_Provider_Action
*/
protected $_action = null;
public function getName();

public function setManifest(Zend_Tool_CommandSystem_Manifest setManifest(Zend_Tool_Rpc_Manifest $manifest);

public function getManifest();

public function setRequest(Zend_Tool_CommandSystem_Endpoint_Request setRequest(Zend_Tool_Rpc_Endpoint_Request $request);

public function setResponse(Zend_Tool_CommandSystem_Endpoint_Response setResponse(Zend_Tool_Rpc_Endpoint_Response $response);

public function getSpecialties();
}

{code}
]]></ac:plain-text-body></ac:macro>


<p>For example, if a developer wants to add the capability of showing the version of a datafile that his 3rd party component is working from, there is only one class the developer would need to implement. Assuming the components is called Some3rdParty_Component, he would create a class/file named Some3rdParty_Component_MyZfTool (MyZfTool.php). This class would extend Zend_Tool_CommandSystem_ProviderAbstract Zend_Tool_Rpc_ProviderAbstract and the body of this file would only have to look like the following:</p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
class Some3rdParty_Component_MyZfTool extends Zend_Tool_CommandSystem_ProviderAbstract Zend_Tool_Rpc_ProviderAbstract
{
public function showDatafileVersion()
}

{code}
]]></ac:plain-text-body></ac:macro>

<p>Given that code above, and assuming the developer wishes to access this functionilty through the Command Line Tooling Client, the call would look like this:</p>

#zf show my-zf-tool.datafile-version
<p>#zf show my-zf-tool.datafile-version<br />
Version number is: 4.0</p>


<h3>Zend_Tool_Rpc_Registry</h3>

h3. Zend_Tool_CommandSystem_Manifest
<p>The Zend_Tool_Rpc_Registry is a runtime bootstrapped registry of all available providers and manifestation metadata.</p>

Zend_Tool_CommandSystem_Manifest provides the means by which Zend_Tool_CommandSystem can find, consume, and supply "providers" within the system. It deploys a set of "loaders" which shall bootstrap the system, and allow the Zend_Tool_CommandSystem to locate and load providers from various locations within a given system. The manifest skeleton is displayed below to give you a sense for what it is responsible for:

{code} <h3>Zend_Tool_Rpc_Registry_Loader</h3>
<?php

class Zend_Tool_CommandSystem_Manifest
{
<p>The purpose of the Registry Loader is to find Providers and Manifest files within the php include_path who's file names match a specific set of patterns and implement/extend either Zend_Tool_Rpc_ProviderAbstract or Zend_Tool_Rpc_ManifestInterface. Once these files are found, the providers are loaded into the Provider Registry and manifest metadata is loaded into the Manifest Registry.</p>

protected $_loaders = array();
protected $_providers = array();
<p>Currently, it has been decided that the file names to be search for (which will be configurable), will be *Tool.php and *Manifest.php. The registry loader will make use of RecursiveDirectoryIterator as well as RecursiveFilterIterator in order to find which files match the patterns described. </p>

public function __construct();

public function addLoader(Zend_Tool_CommandSystem_Manifest_Loader_Abstract $manifestLoader);
<h3>Zend_Tool_Rpc_ManifestInterface</h3>

public function load();
<p>Zend_Tool_Rpc_Manifest provides the means by which those creating providers and endpoint can decorate providers in such a way that is consumable and reusable by all components within the system. The interface for the files implementing a manifest is below (also remember this file should be named *Manifest.php in order to be found and parsed when the tooling systme bootstraps.)</p>

public function addProvider(Zend_Tool_CommandSystem_Provider_Abstract $provider);

public function getProviders();

/**
* Enter description here...
*
* @param string $name
* @return Zend_Tool_CommandSystem_Provider_Abstract
*/
public function getProvider($name);

public function resetProviders();

public function addAction(Zend_Tool_CommandSystem_Provider_Action $action);

public function getAction($name);

}
{code}

The loader abstract below is also listed so that you may get more familiar with the tasks all loaders must fulfill:

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
<?php

abstract class Zend_Tool_CommandSystem_Manifest_Loader_Abstract
class Zend_Tool_Rpc_ManifestInterface
{

protected $_name = null;

/**
* @var Zend_Tool_CommandSystem_Manifest
*/
protected $_manifest = null;

abstract public function load(); getMetadata();

public function setName($name);

public function getName();

public function setManifest(Zend_Tool_CommandSystem_Manifest $manifest);

public function addProvider(Zend_Tool_CommandSystem_Provider_Abstract $provider);

public function addAction(Zend_Tool_CommandSystem_Provider_Action $action);


}
{code}

h4. Loading Providers

By default, there will be three methods to locate providers. The first is via Zend_Tool_CommandSystem_Manifest_Finder_PluginLoader. This class will accept known paths and prefixes, and load the classes found within it which will then be registered with the Zend_Tool_CommandSystem_Manifest registry. The second method is via Zend_Tool_CommandSystem_Manifest_Finder_NamedClass. This method will look for a class/file naming convention in a given path, and load the files into the manifest registry. The third built in finder will be Zend_Tool_CommandSystem_Manifest_Finder_NamedManifest. This method will look for manifest files in a given path, parse them, and load them into the manifest registry.


h5. PluginDirectory Provider Manifest Loader

{code}
<?php

require_once 'Zend/Loader/PluginLoader.php';

class Zend_Tool_CommandSystem_Manifest_Loader_PluginDirectory extends Zend_Tool_CommandSystem_Manifest_Loader_Abstract
{

/**
* @var Zend_Loader_PluginLoader
* Optional Methods - this method will be tested for, and if it exists will be used
* to load local providers into the provider registry
*/
protected $_pluginLoader = null; // public function getProviders()

public function __construct(Array $prefixToPaths = array())
{
$this->_pluginLoader = new Zend_Loader_PluginLoader();

if ($prefixToPaths) {
$this->addPrefixToPaths($prefixToPaths);
}

}


public function addPrefixToPaths($prefix, $path = null)
{
if (is_array($prefix)) {
$prefixToPaths = $prefix;
} else {
$prefixToPaths = array($prefix => $path);
}

foreach ($prefixToPaths as $prefix => $path) {
$this->_pluginLoader->addPrefixPath($prefix, $path);
}

return $this;
}

public function load()
{
$loadedClasses = $this->_pluginLoader->loadAll();

foreach ($loadedClasses as $className) {
$reflector = new ReflectionClass($className);
if ($reflector->isInstantiable() && $reflector->isSubclassOf('Zend_Tool_CommandSystem_Provider_Abstract')) {
$this->addProvider($reflector->newInstance());
continue;
}

if ($reflector->isInstantiable() && ( ($reflector->getName() == 'Zend_Tool_CommandSystem_Provider_Action') || $reflector->isSubclassOf('Zend_Tool_CommandSystem_Provider_Action')) ) {
$this->addAction($reflector->newInstance());
continue;
}

}

return $this;
}

}
{code}
]]></ac:plain-text-body></ac:macro>

As you can see, this Manifest loader leverages Zend_Loader_PluginLoader to load providers from a specified directory into the manifest. For example, assuming the Endpoint setup this as the manifest loader:

{code}
$manifest = $this->getManifest();
$manifest->addLoader(new Zend_Tool_Manifest_Loader_PluginDirectory(array('Zend_Tool_CommandSystem_Provider' => 'Zend/Tool/CommandSystem/Provider')));
{code}

this will allow all of the 'built-in' loaders that extend the Zend_Tool_CommandSystem_ProviderAbstract shall be loaded into the manifest.
<h2>Zend_Tool_Rpc_Endpoint</h2>

h5. FilenameConvention Manifest Loader
<p>Zend_Tool_Rpc_Endpoint is the externally exposed interface that consumers are expected interact with the Zend_Tool_Rpc system through. The first endpoint executed shall be a command line interface. The Endpoint shall implement a static main() method such that will setup a default instance of the endpoint being used. The endpoint will be responsible for taking any environment or user supplied information, parsing it, and executing an action on a provider. The output from the provider will then be provided to the endpoint implementation to send back to the user in a format that makes sense to the endpoint implementation.</p>

This loader will scan all files within the include path and load all files which extend Zend_Tool_CommandSystem_ProviderAbstract and are named *ZfTool.php

h5. ManifestXmlFile Manifest Loader

This loader will take a specially formatted XML file and load the appropriate Providers into the Manifest as well as allow for the loading of extraneous information. This method of loading is suggested in situations where multiple providers might be required for a component and/or in situations where the above method of FileCOnvention does not fit the needs of the component with respect to the naming convention requirement (and where having and XML file within the component is not disallowed).


h3. Querying the Manifest

The manifest shall contain all information about providers.

XXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXX Talk about granularity of information, and the ability for tools to supply information that is
XXXXXXXXXXXXXXXX considered extraneous to the goals of Zend_Tool_CommandSystem
XXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXX




h2. Zend_Tool_CommandSystem_Endpoint

Zend_Tool_CommandSystem_Endpoint is the externally exposed interface that consumers are expected interact with the Zend_Tool_CommandSystem system through. The first endpoint executed shall be a command line interface. The Endpoint shall implement a static main() method such that will setup a default instance of the endpoint being used. The endpoint will be responsible for taking any environment or user supplied information, parsing it, and executing an action on a provider. The output from the provider will then be provided to the endpoint implementation to send back to the user in a format that makes sense to the endpoint implementation.

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
<?php

abstract class Zend_Tool_CommandSystem_Endpoint_Abstract Zend_Tool_Rpc_Endpoint_Abstract
{
/**
* @var Zend_Tool_CommandSystem_Manifest Zend_Tool_Rpc_Manifest
*/
protected $_manifest = null;

/**
* @var Zend_Tool_CommandSystem_Endpoint_Inflector_Interface Zend_Tool_Rpc_Endpoint_Inflector_Interface
*/
protected $_inflector = null;

/**
* @var Zend_Tool_CommandSystem_Endpoint_Request Zend_Tool_Rpc_Endpoint_Request
*/
protected $_request = null;

/**
* @var Zend_Tool_CommandSystem_Endpoint_Response Zend_Tool_Rpc_Endpoint_Response
*/
protected $_response = null;
final public function __construct();

public function setManifest(Zend_Tool_CommandSystem_Manifest setManifest(Zend_Tool_Rpc_Manifest $manifest);

public function getManifest();

public function setInflector(Zend_Tool_CommandSystem_Endpoint_Inflector_Interface setInflector(Zend_Tool_Rpc_Endpoint_Inflector_Interface $inflector);

/**
* Enter description here...
*
* @return Zend_Tool_CommandSystem_Endpoint_Inflector_Interface Zend_Tool_Rpc_Endpoint_Inflector_Interface
*/
public function getInflector();
* Enter description here...
*
* @return Zend_Tool_CommandSystem_Endpoint_Request Zend_Tool_Rpc_Endpoint_Request
*/
public function getRequest();
* Enter description here...
*
* @return Zend_Tool_CommandSystem_Endpoint_Response Zend_Tool_Rpc_Endpoint_Response
*/
public function getResponse();

}
{code}
]]></ac:plain-text-body></ac:macro>

h3. Zend_Tool_CommandSystem_Endpoint_Cli & Zend_Tool_CommandSystem_Endpoint_Rpci
<h3>Zend_Tool_Rpc_Endpoint_Cli &amp; Zend_Tool_Rpc_Endpoint_Rpci</h3>

<p>The command line interface endpoint shall make use of the command line arguments to initiate the action/provider) request, and also make use of standard out to alert the user of any output that came from the exection of the provider.</p>

<p>XXXXXXXXXXXXXXXX<br />
XXXXXXXXXXXXXXXX Discuss Rcpi endpoint<br />
XXXXXXXXXXXXXXXX<br />
XXXXXXXXXXXXXXXX<br />
XXXXXXXXXXXXXXXX</p>
XXXXXXXXXXXXXXXX Discuss Rcpi endpoint
XXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXX


h2. Zend_Tool_CommandSystem_Provider's built in providers
<h2>Zend_Tool_Rpc_Provider's built in providers</h2>

<p>These providers will be able to allow the system to reflect back to the user all of the capabilities and providers that are loaded within the tooling system.</p>

* System
* Test

XXXXXXXXXXXXXXXX <ul>
XXXXXXXXXXXXXXXX Talk about internal methods
XXXXXXXXXXXXXXXX <li>System</li>
XXXXXXXXXXXXXXXX <li>Test</li>
XXXXXXXXXXXXXXXX </ul>


<p>XXXXXXXXXXXXXXXX<br />
XXXXXXXXXXXXXXXX Talk about internal methods<br />
XXXXXXXXXXXXXXXX<br />
XXXXXXXXXXXXXXXX<br />
XXXXXXXXXXXXXXXX</p>




h2. Definitions and Terms

(1) Zend_Tool_CommandSystem - The framework which exposes tooling capabilities.

(2) Tooling Client - A developer tool that connects to and consumes "Zend_Tool_CommandSystem".

(3) Command Line Tool / Command Line Interface / zf.php - The "tooling client" for the command line.

(4) Zend Studio - An IDE based "tooling client", connects via the RPC "Zend_Tool_CommandSystem_Endpoint"
<h2>Definitions and Terms</h2>

(5) Endpoint - The subsystem of "Zend Tool" that exposes an interface such that "tooling clients" can connect, query and execute commands.
<p> (1) Zend_Tool_Rpc - The framework which exposes tooling capabilities.</p>
(6) Cli Endpoint - An endpoint implementation responsible for exposing "Zend Tool CommandSystem" via the "command line interface".

(7) Rpci Endpoint - An endpoint implementation responsible for exposing "Zend Tool CommandSystem" via the "remote procedure call interface".
<p> (2) Tooling Client - A developer tool that connects to and consumes &quot;Zend_Tool_Rpc&quot;.</p>
(8) Provider - A subsystem and a collection of built-in functionality that the "Zend Tool" system exports.

<p> (3) Command Line Tool / Command Line Interface / zf.php - The &quot;tooling client&quot; for the command line.</p>

<p> (4) Zend Studio - An IDE based &quot;tooling client&quot;, connects via the RPC &quot;Zend_Tool_Rpc_Endpoint&quot;</p>

<p> (5) Endpoint - The subsystem of &quot;Zend Tool&quot; that exposes an interface such that &quot;tooling clients&quot; can connect, query and execute commands.</p>

<p> (6) Cli Endpoint - An endpoint implementation responsible for exposing &quot;Zend Tool RPC&quot; via the &quot;command line interface&quot;.</p>

<p> (7) Rpci Endpoint - An endpoint implementation responsible for exposing &quot;Zend Tool RPC&quot; via the &quot;remote procedure call interface&quot;.</p>

<p> (8) Provider - A subsystem and a collection of built-in functionality that the &quot;Zend Tool&quot; system exports.</p>

<p> (9) ZFProject Provider - A set of providers specifically for creating and maintaining Zend Framework based projects.</p>

(10) Manifest - A subsystem for defining, organizing, and disseminating "provider" requirement data.
<p> (10) Manifest - A subsystem for defining, organizing, and disseminating &quot;provider&quot; requirement data.</p>