View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFPROP:Proposal Zone Template}

{zone-data:component-name}
Zend_Tool_Project
{zone-data}

{zone-data:proposer-list}
[~ralph]
{zone-data}

{zone-data:liaison}
TBD
{zone-data}

{zone-data:revision}
1.0 - 2 June 2008: Initial Draft.
{zone-data}

{zone-data:overview}
Zend_Tool_Project is a component that facilitates Project based development through extending Zend_Tool_Framework.
{zone-data}

{zone-data:references}
{zone-data}

{zone-data:requirements}

* This component *will* contain Providers for Zend_Tool_Framework to facilitate execution through the command line and various other endpoints.
* This component *will* provide interfaces and abstracts that facilitate the extension of the base functionality related to "project" context nodes.
* This component *wil
{zone-data}

{zone-data:dependencies}
* Zend_Tool_Framework
* Zend_Tool_CodeGenerator
* Zend_Exception
* simplexml
{zone-data}

{zone-data:operation}


h3. Goals

The goals of Zend_Tool_Project is two fold:
* provide a suite of functionality that can build, modify, and serialize an object graph representation of various nodes/elements within a Zend Framework oriented project, also known as a "Project Profile".
* a registry for project context nodes (ie the names of the nodes in the xml file)
* provide a set of providers for tooling framework interaction with the Project Profile with respect to Controller,Actions,View Scripts and other primary ZF Project elements.

h3. The Serialization Format

The primary serialization format needs to support recursive nodes with a varying amount of attributes further defining that nodes context. The primary format that fully meets this expectation is XML. Furthermore, PHP has basic classes in the SPL that facilitate and support XML as an object graph, specifically the RecursiveIterator. It is for this reason that the primary serialization medium will be XML. This is not to say that future formats will/can not be supported, only that XML will be the first and primary format.

An example of a serialized project profile:

This profile taken from [http://framework.zend.com/wiki/display/ZFPROP/Zend+Framework+Default+Project+Structure+-+Wil+Sinclair]

{code}
<?xml version="1.0" encoding="UTF-8"?>
<projectProfile name="default">
<projectDirectory>
<projectProfileFile />
<applicationDirectory>
<apisDirectory enabled="false" />
<configsDirectory />
<controllersDirectory>
<controllerFile controllerName="index" />
<controllerFile controllerName="error" />
</controllersDirectory>
<layoutsDirectory enabled="false" />
<modelsDirectory />
<modulesDirectory enabled="false" />
<viewsDirectory>
<viewScriptsDirectory>
<viewControllerScriptsDirectory forControllerName="index">
<viewScriptFile scriptName="index" />
</viewControllerScriptsDirectory>
</viewScriptsDirectory>
<viewHelpersDirectory />
<viewFiltersDirectory enabled="false" />
</viewsDirectory>
<bootstrapFile />
</applicationDirectory>
<dataDirectory enabled="false">
<cacheDirectory enabled="false" />
<searchIndexesDirectory enabled="false" />
<localesDirectory enabled="false" />
<logsDirectory enabled="false" />
<sessionsDirectory enabled="false" />
<uploadsDirectory enabled="false" />
</dataDirectory>
<libraryDirectory>
<zfStandardLibraryDirectory />
</libraryDirectory>
<publicDirectory>
<publicStylesheetsDirectory enabled="false" />
<publicScriptsDirectory enabled="false" />
<publicImagesDirectory enabled="false" />
<publicIndexFile />
<htaccessFile />
</publicDirectory>
<providersDirectory enabled="false" />
<!--
<temporaryDirectory enabled="false" />
<testsDirectory enabled="false" />
-->
</projectDirectory>
</projectProfile>

{code}

This structure is capable of being parsed into the object graph by Zend_Tool_Project_Structure_Parser_Xml.

h3. The Object Graph

The goal of the object graph (implemented as Zend_Tool_Project_Structure_Graph), is to be able to serialize and unserialize the project's structure (See above) into an object graph that can be modified in runtime. This object graph is made up of Zend_Tool_Project_Structure_Node(s), all of which should be decorated with a Node Context (Zend_Tool_Project_Structure_Context_Interface).



h3. The Context Node Registry

Providers will be responsible for registering context nodes within the registry for later use within a project profile. There can only be a node available of a singular name, for example, only one node named 'controllerFile' should exist in the registry. The registry would allow overwriting of a contextNode if and only if an overwrite flag was passed at set time.

h3. The Filesystem ProjectContext Nodes

Assuming the above abstracts, the first order of business is to implement context nodes for the purposes of creating, modifying and deleting filesystem nodes. This includes (but is not limited to) controllers, bootstrap files, the Zend Framework library, view scripts, models and the .htaccess file to name a few. There exists a default abstract for this filesystem context:



The nodes implemented would include the following list:

|| Context Name || Where it Resides ||
|ApplicationDirectory |Zend_Tool_Project_Structure_Context_Zf_ApplicationDirectory|
|BootstrapFile |Zend_Tool_Project_Structure_Context_Zf_BootstrapFile|
|ClassFileAbstract |Zend_Tool_Project_Structure_Context_Zf_ClassFileAbstract|
|ControllerFile |Zend_Tool_Project_Structure_Context_Zf_ControllerFileContextNode|
|ControllersDirectory |Zend_Tool_Project_Structure_Context_Zf_ControllersDirectoryContextNode|
|HtaccessFile |Zend_Tool_Project_Structure_Context_Zf_HtaccessFile|
|LibraryDirectory |Zend_Tool_Project_Structure_Context_Zf_LibraryDirectory|
|ModelsDirectory |Zend_Tool_Project_Structure_Context_Zf_ModelsDirectory|
|ModulesDirectory |Zend_Tool_Project_Structure_Context_Zf_ModulesDirectory|
|ProjectDirectory |Zend_Tool_Project_Structure_Context_Zf_ProjectDirectory|
|PublicDirectory |Zend_Tool_Project_Structure_Context_Zf_PublicDirectory|
|PublicIndexFile |Zend_Tool_Project_Structure_Context_Zf_PublicIndexFile|
|ViewControllerScriptsDirectory |Zend_View_Tool_ViewControllerScriptsDirectory|
|ViewFiltersDirectory |Zend_Tool_Project_Structure_Context_Zf_ViewFiltersDirectory|
|ViewHelpersDirectory |Zend_Tool_Project_Structure_Context_Zf_ViewHelpersDirectory|
|ViewScriptFile |Zend_Tool_Project_Structure_Context_Zf_ViewScriptFile|
|ViewScriptsDirectory |Zend_Tool_Project_Structure_Context_Zf_ViewScriptsDirectory|
|ViewsDirectory |Zend_Tool_Project_Structure_Context_Zf_ViewsDirectory|
|ZendFrameworkStandardLibrary |Zend_Tool_Project_Structure_Context_Zf_ZendFrameworkStandardLibrary|

There are also some base contexts that have been created to facilitate filesystem based operation

|| Context Name || Where it Resides ||
|Directory|Zend_Tool_Project_Structure_Filesystem_Directory|
|File|Zend_Tool_Project_Structure_Filesystem_File|

h3. The Providers

To expose the manipulation of the object graph to the end user, this component makes use of the Zend_Tool_Framework Provider hooks in order to extend these capabilities outward. If, for example, from the command line, a user wanted to create a new "user" controller and the resulting view script, it would be ideal if the user could do: zf create controller -n user. The way Zend_Tool_Project would expose that capability would be through implementing a provider for that action.

In the above example of creating a new controller, it is important to describe the relationship between providers and contexts. Being able to say "zf create controller", means that here is a "Controller Provider" available, which has an actionable method named "create". In terms of code, this means that the following exists: Zend_Controller_Tool_ControllerProvider::create() (consequently, this class extends Zend_Tool_Project_Provider_Abstract). This method is responsible taking the object graph created by the base class Zend_Tool_Project_Provider_Abstract, interacting with it (by means of creating a new controller node in much the same way one would create a new node in a DomDocument), and writing the profile back to disk (also another function of the base abstract Zend_Tool_Project_Provider_Abstract class.)



{zone-data}

{zone-data:milestones}
Describe some intermediate state of this component in terms of design notes, additional material added to this page, and / code. Note any significant dependencies here, such as, "Milestone #3 can not be completed until feature Foo has been added to ZF component XYZ." Milestones will be required for acceptance of future proposals. They are not hard, and many times you will only need to think of the first three below.
* Milestone 1: [design notes will be published here|http://framework.zend.com/wiki/x/sg]
* Milestone 2: Working prototype checked into the incubator supporting use cases #1, #2, ...
* Milestone 3: Working prototype checked into the incubator supporting use cases #3 and #4.
* Milestone 4: Unit tests exist, work, and are checked into SVN.
* Milestone 5: Initial documentation exists.

If a milestone is already done, begin the description with "\[DONE\]", like this:
* Milestone #: \[DONE\] Unit tests ...
{zone-data}

{zone-data:class-list}
* Zend_Tool_Project_Provider
* Zend_Tool_Project_Provider_Abstract
* Zend_Tool_Project_Provider_Manifest
* Zend_Tool_Project_Provider_Project
* Zend_Tool_Project_Structure
* Zend_Tool_Project_Structure_Context
* Zend_Tool_Project_Structure_Context_Exception
* Zend_Tool_Project_Structure_Context_Filesystem
* Zend_Tool_Project_Structure_Context_Filesystem_Abstract
* Zend_Tool_Project_Structure_Context_Filesystem_Directory
* Zend_Tool_Project_Structure_Context_Filesystem_File
* Zend_Tool_Project_Structure_Context_Interface
* Zend_Tool_Project_Structure_Context_Registry
* Zend_Tool_Project_Structure_Context_Zf
* Zend_Tool_Project_Structure_Context_Zf_ApisDirectory
* Zend_Tool_Project_Structure_Context_Zf_ApplicationDirectory
* Zend_Tool_Project_Structure_Context_Zf_BootstrapFile
* Zend_Tool_Project_Structure_Context_Zf_CacheDirectory
* Zend_Tool_Project_Structure_Context_Zf_ConfigsDirectory
* Zend_Tool_Project_Structure_Context_Zf_DataDirectory
* Zend_Tool_Project_Structure_Context_Zf_HtaccessFile
* Zend_Tool_Project_Structure_Context_Zf_LayoutsDirectory
* Zend_Tool_Project_Structure_Context_Zf_LibraryDirectory
* Zend_Tool_Project_Structure_Context_Zf_LocalesDirectory
* Zend_Tool_Project_Structure_Context_Zf_LogsDirectory
* Zend_Tool_Project_Structure_Context_Zf_ModelsDirectory
* Zend_Tool_Project_Structure_Context_Zf_ModulesDirectory
* Zend_Tool_Project_Structure_Context_Zf_ProjectDirectory
* Zend_Tool_Project_Structure_Context_Zf_ProjectProfileFile
* Zend_Tool_Project_Structure_Context_Zf_ProvidersDirectory
* Zend_Tool_Project_Structure_Context_Zf_PublicDirectory
* Zend_Tool_Project_Structure_Context_Zf_PublicImagesDirectory
* Zend_Tool_Project_Structure_Context_Zf_PublicIndexFile
* Zend_Tool_Project_Structure_Context_Zf_PublicScriptsDirectory
* Zend_Tool_Project_Structure_Context_Zf_PublicStylesheetsDirectory
* Zend_Tool_Project_Structure_Context_Zf_SearchIndexesDirectory
* Zend_Tool_Project_Structure_Context_Zf_SessionsDirectory
* Zend_Tool_Project_Structure_Context_Zf_TemporaryDirectory
* Zend_Tool_Project_Structure_Context_Zf_TestsDirectory
* Zend_Tool_Project_Structure_Context_Zf_UploadsDirectory
* Zend_Tool_Project_Structure_Context_Zf_ZfStandardLibraryDirectory
* Zend_Tool_Project_Structure_Exception
* Zend_Tool_Project_Structure_Graph
* Zend_Tool_Project_Structure_Node
* Zend_Tool_Project_Structure_Parser
* Zend_Tool_Project_Structure_Parser_Interface
* Zend_Tool_Project_Structure_Parser_Xml
{zone-data}

{zone-data:use-cases}
||UC-01||

{code}
// from the command line command: zf create controller -n auth

<?php

require_once 'Zend/Tool/Project/Provider/Abstract.php';

class Zend_Controller_Tool_ControllerProvider extends Zend_Tool_Project_Provider_Abstract
{

// which context files to require?
public function getContextClasses()
{
return array(
'Zend_Controller_Tool_ControllerFileContext', // Context: ControllerFile
'Zend_Controller_Tool_ControllersDirectoryContext' // Context: ControllersDirectory
);
}

/**
* this is what is executed by Zend_Tool_Framework when "create controller"
* is encountered, also -n auth has been passed as the first parameter
*/
public function create($name, $viewincluded = true)
{
// from the abstract provider, get the existing graph.
$structureGraph = $this->_getExistingStructureGraph();

// find the controllersDirectory within the graph
$controllersDirectoryNode = $structureGraph->findNodeByContext('controllersDirectory');

// create a new "ControllerFile" context
$controllerFileContext = Zend_Tool_Project_Structure_Context_Registry::getInstance()->getContext('controllerFile');

// create a new structure node with context "ControllerFIle"
$newNode = new Zend_Tool_Project_Structure_Node($controllerFileContext);

// set the base path and name (as provided by $name)
$newNode->setBaseDirectory($controllersDirectoryNode->getContext()->getPath());
$newNode->setControllerName($name);


echo 'Creating new controller named \'' . $name . '\'' . PHP_EOL;
$newNode->create();
$controllersDirectoryNode->append($newNode);

// save the graph back to disk
$this->_storeLoadedStructureGraph();

if ($viewincluded) {
$viewProvider = Zend_Tool_Framework_Provider_Registry::getInstance()->getProvider('View');
$viewProvider->create($name, 'index');
}

}

}


{code}

{zone-data}

{zone-data:skeletons}
{code}
// none at this time
{code}
{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>