Zend Framework: Zend_Tool_Framework_Endpoint_Cli Component Proposal

Proposed Component Name	Zend_Tool_Framework_Endpoint_Cli
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Tool_Framework_Endpoint_Cli
Proposers	Ralph Schindler
Zend Liaison	TBD
Revision	1.0 - 1 January 2008: Initial Draft. (wiki revision: 6)

What should the command line argument structure look like? How can this be intuitive?
Provider names are in camel case and command line arguments are usually dash-separated, how can we maintain this consistency?
Will interactivity be supported? If so, how?
How can we maintain consistency with respect to other future endpoints?

Command Line Argument Structure

The command line application

First and foremost, the actual command line application should be short and concise. For this reason, this proposal suggests that the name of the command line application be "zf". This application should be installed into the PATH of the host operating system, and the rest of Zend Framework (including the whole of Zend_Tool), should be inside of an accessible include_path.

This means that specific operating systems should make use of semantics that are as specific as their needs. For example, on windows there might be a zf.bat file that calls the zf.php file. On *nix systems, there might be a zf.sh or zf command inside a path that calls out to the zf.php file.

The command line arguments

In OO design of Zend Framework, there is a level of consistency in class and method namings. More specifically, in most cases we attempt to stick with the following structure:

class Noun
{

    public function verb()
    {}
    
    // OR
    public function verbAdjective()
    {}
    
    // OR
    public function verbNoun()
    {}
    
}

As you can see, when most classes follow the above structure when developing an API, it makes the API predictable and consistent. Those two tenants are two that we also wish to have with respect to the command line tool and its arguments.

Similar to how western languages (like english) are read and spoken, I propose we follow a command like syntax's:

zf <verb> <noun>

// OR

zf <verb> <noun>.<adjective|noun>

The above allows us to build a command sytax that might look like: "zf show version", or "zf create project", or "zf create model.dbtable", so on and so forth. The primary objective is to build a command syntax with arguments that closely resembles spoken language commands.

Command Line Parameters

Commands from the command line are parsed and will attempt to dispatch/execute a specific method inside a Zend_Tool provider. As we can see inside the Zend_Tool_Framework proposal, providers are made up of Providers (the noun), actions (the verb), and optional specialties (the adjective/noun). Those elements are set inside a request object which is then passed down to a Zend_Tool_Framework dispatcher (also described in the Zend_Tool_Framework proposal).

Also included in this request object can be parameters. Parameters in the Zend_Tool Providers sense, are simply method arguments. For exmaple in this class:

class Version
{
    public function show($details = false)
    {}

}

we see that the show() method has an optional argument for "details". In order to properly model this on the command line, we will make use of command line "options". We will make use of Zend_Console_GetOpt to parse out options. Generally speaking, options are command line words that start with one or two dashes (-, or --).

Since in the above example the "details" option is specific to the "show version" command, it will be expected after the "noun" portion of the command, like this:

zf show version --details=true

Multiple optional parameters can be included on the command line, and DO NOT have to be in the same order they appear in the actual class/method since they are referred to by their name.

Alternate Usage

It is allowed to have positional parameters in the command line endpoint. For example, if a method takes two methods Foo::bar($one, $two), then the following command line is allowed:

zf bar foo onevalue twovalue

where onevalue will be passed in as $one parameters, and twovalue will be passed in via $two parameter.

Command Line Naming Semantics

With all of the above examples, there should be one lingering question: How does Version become version? How does any camelCase name become the dash-separated name we see on the command line? AND, will this information be available to me when using OTHER endpoints.

The answer to this question is simple: we will make use of the Zend_Tool_Framework Metadata (Manifest) mechanism. As we noted inside the Zend_Tool_Framework proposal, the metadata manifest can be utilized to attach and store information and metadata to any of the providers and actions within the system. In our case here, we want to store naming information.

When the Zend_Tool_Framework system bootstraps itself (ie: it looks for providers and manifests inside the include_path), it will pick up on Zend_Tool_Framework_Endpoint_Cli_Manifest. This manifest will create a "command line" version of all of the necessary namings for its own use.

To do this, it will make use of Zend_Filter_Words_CamelCaseToDash to make this translation. These translations are then put inside the Zend_Tool_Framework global manifest for later usage. By nature of the Manifest system, regardless of if the CLI tool or some other tool is consuming the Zend_Tool_Framework system, this metadata will always be available. So, this means, if IDE XYZ was to implement an endpoint into the Zend_Tool_Framework system, it will have access to the cli namings setup by Zend_Tool_Framework_Endpoint_Cli_Manifest.

6. Milestones / Tasks

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
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 ...

7. Class Index

Zend_Tool_Framework_Endpoint_Cli
Zend_Tool_Framework_Endpoint_Cli_Manifest
Zend_Tool_Framework_Endpoint_Cli_OptionParser

8. Use Cases

Show the version from the "version provider"

# zf show version 
Zend Framework Version: 1.5.2

Show the major part of the version from the "version provider"

# zf show version.major-part 
ZF Major Version: 1

Show the major part of the version (as passed as a parameter) from the "version provider"

# zf show version -m major 
Zend Framework Version: 1

Create a new project from the "project provider"

# pwd
/Users/ralphschindler/tmp/scratch
# zf create project 
creating project at /Users/ralphschindler/tmp/scratch

Create a new controller inside a project from the "controller provider"

# zf create controller --name foo 
Creating new controller named 'foo' 
Updating project profile '/Users/ralphschindler/tmp/scratch/.zfproject.xml' 
Creating a view script. 
Updating project profile '/Users/ralphschindler/tmp/scratch/.zfproject.xml'

9. Class Skeletons

Zend_Tool_Framework_Endpoint_Cli

<?php

class Zend_Tool_Framework_Endpoint_Cli extends Zend_Tool_Framework_Endpoint_Abstract
{

    // called by the actual zf.php
    public static function main()
    {}
    
    protected function _init()
    {}
    
    protected function _preHandle()
    {}
    
    protected function _postHandle()
    {}
    
}

Zend_Tool_Framework_Endpoint_Cli_GetoptParser

<?php

class Zend_Tool_Framework_Endpoint_Cli_GetoptParser
{
    
    /**
     * @var Zend_Tool_Framework_Endpoint_Cli
     */
    protected $_endpoint = null;
    
    protected $_arguments = null;
    protected $_workingArguments = null;
    
    protected $_validActions = array();
    protected $_validProviders = array();
    

    public function __construct(ZendL_Tool_Framework_Endpoint_Cli $endpoint, Array $arguments)
    {}
    
    public function parse()
    {}
    
    public function getActionName()
    {}
    
    public function getActionOptions()
    {}
    
    public function getProviderName()
    {}
    
    public function getProviderOptions()
    {}
    
}

Zend_Tool_Framework_Endpoint_Cli_Manifest

<?php

class Zend_Tool_Framework_Endpoint_Cli_Manifest implements Zend_Tool_Framework_Manifest_Interface
{
    
    public function getMetadata()
    {}
    
    public function getIndex()
    {}
    
}

Page Operations

Browse Space

Zend_Tool_Framework_Endpoint_Cli - Ralph Schindler

Labels

Zend Framework: Zend_Tool_Framework_Endpoint_Cli Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

4. Dependencies on Other Framework Components

5. Theory of Operation