- pear discover-channel pear.zfcampus.org
- pear install zfcampus/zf
Using Zend_Tool On The Command Line
The CLI, or command line tool (internally known as the console tool), is currently the primary interface for dispatching Zend_Tool requests. With the CLI tool, developers can issue tooling requests inside the "command line window", also commonly known as a "terminal" window. This environment is predominant in the *nix environment, but also has a common implementation in windows with the cmd.exe, console2 and also with the Cygwin project.
Download And Go
First download Zend Framework. This can be done by going to framework.zend.com and downloading the latest release. After you've downloaded the package and placed it on your system. The next step is to make the zf command available to your system. The easiest way to do this, is to copy the proper files from the bin/ directory of the download, and place these files within the same directory as the location of the PHP cli binary.
Installing Via Pear
To install via PEAR, you must use the 3rd party zfcampus.org site to retrieve the latest Zend Framework PEAR package. These packages are typically built within a day of an official Zend Framework release. The benefit of installing via the PEAR package manager is that during the install process, the ZF library will end up on the include_path, and the zf.php and zf scripts will end up in a place on your system that will allow you to run them without any additional setup.
That is it. After the initial install, you should be able to continue on by running the zf command. Go good way to check to see if it't there is to run zf --help
Installing by Hand
Installing by hand refers to the process of forcing the zf.php and Zend Framework library to work together when they are placed in non-convential places, or at least, in a place that your system cannot dispatch from easily (typical of programs in your system PATH).
If you are on a *nix or mac system, you can also create a link from somewhere in your path to the zf.sh file. If you do this, you do not need to worry about having Zend Framework's library on your include_path, as the zf.php and zf.sh files will be able to access the library relative to where they are (meaning the ./bin/ files are ../library/ relative to the Zend Framework library).
There are a number of other options available for setting up the zf.php and library on your system. These options revolve around setting specific environment variables. These are described in the later section on "customizing the CLI environement". The environment variables for setting the zf.php include_path, ZF_INCLUDE_PATH and ZF_INCLUDE_PATH_PREPEND, are the ones of most interest.
General Purpose Commands
This will show the current version number of the copy of Zend Framework the zf.php tool is using.
- zf show version
The built-in help system is the primary place where you can get up-to-date information on what your system is capable of doing. The help system is dynamic in that as providers are added to your system, they are automatically dispatchable, and as such, the parameters required to run them will be in the help screen. The easiest way to retrieve the help screen is the following:
- zf --help
This will give you an overview of the various capabilities of the system. Sometimes, there are more finite commands than can be run, and to gain more information about these, you might have to run a more specialized help command. For specialized help, simply replace any of the elements of the command with a "?". This will tell the help system that you want more information about what commands can go in place of the question mark. For example:
- zf ? controller
The above means "show me all 'actions' for the provider 'controller'"; while the following:
- zf show ?
means "show me all providers that support the 'show' action". This works for drilling down into options as well as you can see in the following examples:
- zf show version.? (show any specialties)
- zf show version ? (show any options)
This will show what information is in the tooling systems manifest. This is more important for provider developers than casual users of the tooling system.
- zf show manifest
Project Specific Commands
The project provider is the first command you might want to run. This will setup the basic structure of your application. This is required before any of the other providers can be executed.
- zf create project MyProjectName
This will create a project in a directory called ./MyProjectName. From this point on, it is important to note that any subsequent commands on the command line must be issued from within the project directory you had just created. So, after creation, changing into that directory is required.
The module provider allows for the easy creation of a Zend Framework module. A module follows the hMVC pattern loosely. When creating modules, it will take the same structure used at the application/ level, and duplicate it inside of the chosen name for your module, inside of the "modules" directory of the application/ directory without duplicating the modules directory itself. For example:
- zf create module Blog
This will create a module named Blog at application/modules/Blog, and all of the artifacts that a module will need.
The controller provider is responsible for creating (mostly) empty controllers as well as their corresponding view script directories and files. To utilize it to create an 'Auth' controlller, for example, execute:
- zf create controller Auth
This will create a controller named Auth, specifically it will create a file at application/controllers/AuthController.php with the AuthController inside. If you wish to create a controller for a module, use any of the following:
- zf create controller Post 1 Blog
- zf create controller Post -m Blog
- zf create controller Post --module=Blog
Note: In the first command, 1 is the value for the "includeIndexAction" flag.
To create an action within an existing controller:
- zf create action login Auth
- zf create action login -c Auth
- zf create action login --controller-name=Auth
To create a view outside of the normal controller/action creation, you would use one of the following:
- zf create view Auth my-script-name
- zf create view -c Auth -a my-script-name
This will create a view script in the controller folder of Auth.
The model provider is only responsible for creating the proper model files, with the proper name inside the application folder. For example
- zf create model User
If you wish to create a model within a specific module:
- zf create model Post -m Blog
The above will create a 'Post' model inside of the 'Blog' module.
The form provider is only responsible for creating the proper form file and init() method, with the proper name inside the application folder. For example:
- zf create form Auth
If you wish to create a model within a specific module:
- zf create form Comment -m Blog
The above will create a 'Comment' form inside of the 'Blog' module.
To configure a DbAdapter, you will need to provide the information as a url encoded string. This string needs to be in quotes on the command line.
For example, to enter the following information:
- zf configure dbadapter "adapter=Pdo_Mysql&username=test&password=test&dbname=test"
This assumes you wish to store this information inside of the 'production' space of the application configuration file. The following will demonstrate an sqlite configuration, in the 'development' section of the application config file.
- zf configure dbadapter "adapter=Pdo_Sqlite&dbname=../data/test.db" development
- zf configure dbadapter "adapter=Pdo_Sqlite&dbname=../data/test.db" -s development
The DbTable provider is responsible for creating Zend_Db_Table model/data access files for your application to consume, with the proper class name, and in the proper location in the application. The two important pieces of information are the DbTable name, and the actual database table name. For example:
- zf create dbtable User user
- zf create dbtable User -a user
- // also accepts a force option to overwrite existing files
- zf create dbtable User user -f
- zf create dbtable User user --force-override
The DbTable provider is also capable of creating the proper files by scanning the database configured with the above DbAdapter provider.
- zf create dbtable.from-database
When executing the above, it might make sense to use the pretend / "-p" flag first so that you can see what would be done, and what tables can be found in the database.
- zf -p create dbtable.from-database
Currently, the only supported action for layouts is simply to enable them will setup the proper keys in the application.ini file for the application resource to work, and create the proper directories and layout.phtml file.
- zf enable layout
The Storage Directory
The storage directory is important so that providers may have a place to find custom user generated logic that might change the way they behave. One example can be found below is the placement of a custom project profile file.
- zf --setup storage-directory
The Configuration File
This will create the proper zf.ini file. This should
be run after
zf --setup storage-directory. If it is not, it will
be located inside the users home directory. If it is, it will be located inside
the users storage directory.
- zf --setup config-file
These should be set if you wish to override the default places where zf will attempt to read their values.
the directory this tool will look for a home directory
directory must exist
ZF_HOME environment variable
HOME environment variable
then HOMEPATH environment variable
where this tool will look for a storage directory
directory must exist
ZF_STORAGE_DIRECTORY environment variable
where this tool will look for a configuration file
ZF_CONFIG_FILE environment variable
$homeDirectory/.zf.ini file if it exists
$storageDirectory/zf.ini file if it exists
set the include_path for this tool to use this value
use PHP's include_path to find ZF
use the ZF_INCLUDE_PATH environment variable
use the path ../library (relative to zf.php) to find ZF
prepend the current php.ini include_path with this value