In today’s tutorial, we go through the key options in ZFTool, the tooling support available in Zend Framework 2. We install it, create a basic ZF2 application and more.
Level: Beginner
Duration: 20 mins
Welcome to another tutorial. Today, I will be giving you a walk through of zftool, which provides basic tooling support in Zend Framework 2. If you’re new to Zend Framework, or have been reading the introductory series here, it can come in quite handy.
But unlike other frameworks, such as Yii (through yiic) and Symfony (via the Command Line tool), the tooling support in Zend Framework 2 is rather light on.
These respective tools provide rather robust support for automatically generating models from database connections, checking logs and a host of other much required functionality.
I understand from some tweets with Enrico Zimuel new additions are planned for zftool. But for right now, Zend Framework is definitely the junior. However, that aside, I like to take the adage of a glass half full and see zftool as a good start. Today we’re going to use it to carry out the following tasks:
By the end of today’s tutorial, you will have a good understanding of how to get started with it and to be able to use it in your projects. Firstly, let’s install zftool and get started.
There are a number of ways in which zftool can be installed, including using Composer and downloading the Phar tool.
During the research for this article, I tried to install it via Composer, but continuously met with permission related errors. As a result, I’ve chosen to focus on the Phar tool approach, which works, almost, seamlessly.
If you’d like to go down the Composer route, run the following command in your Terminal or console and you’ll have it available.
$ composer require zendframework/zftool:dev-master
Otherwise, download the phar file. Once it’s downloaded, run the following commands. These make it accessible universally on your system:
sudo cp -v zftool.phar /bin/ cd /bin/ sudo ln -s zftool.phar zftool sudo chmod +x zftool.phar
If you’re not familiar with the Linux command line, what we’ve done here is to copy zftool.phar to one of the directories automatically in a users PATH.
Then we’ve created a symlink to it, giving it a simpler name and finally set the executable bit on it - now it’s ready to run.
Now that we have the Phar file available, let’s have a look at the options available. Running the following command will display a help screen, showing all of the options supported:
zftool.phar
It will result in output similar to that below:
--------------------------------------------------------------------------------
ZFTool
--------------------------------------------------------------------------------
Basic information:
zftool.phar modules [list] show loaded modules
zftool.phar version | --version display current Zend Framework version
Diagnostics
zftool.phar diag [options] [module name] run diagnostics
[module name] (Optional) name of module to test
-v --verbose Display detailed information.
-b --break Stop testing on first failure
-q --quiet Do not display any output unless an error occurs.
--debug Display raw debug info from tests.
Application configuration:
zftool.phar config [list] list all configuration options
zftool.phar config get <name> display a single config value, i.e. "config get db.host"
zftool.phar config set <name> <value> set a single config value (use only to change scalar values)
Project creation:
zftool.phar create project <path> create a skeleton application
<path> The path of the project to be created
Module creation:
zftool.phar create module <name> [<path>] create a module
<name> The name of the module to be created
<path> The root path of a ZF2 application where to create the module
Classmap generator:
zftool.phar classmap generate <directory> <classmap file> [--append|-a] [--overwrite|-w]
<directory> The directory to scan for PHP classes (use "." to use current directory)
<classmap file> File name for generated class map file or - for standard output.If not supplied, defaults to
autoload_classmap.php inside <directory>.
--append | -a Append to classmap file if it exists
--overwrite | -w Whether or not to overwrite existing classmap file
Zend Framework 2 installation:
zftool.phar install zf <path> [<version>]
<path> The directory where to install the ZF2 library
<version> The version to install, if not specified uses the last available
Ok, with the tool ready to go, let’s set about using some of it’s functionality to creating and managing a Zend Framework 2 project, as outlined above.
Firstly, we’ll create a raw project, called &‘simple project’. To do so, run the following command:
$ php zftool.phar create project ./simpleproject
This will create the core project files in a directory in the current directory, called &‘simpleproject’. It will give you output similar to that below:
ZF2 skeleton application installed in ./simpleproject. In order to execute the skeleton application you need to install the ZF2 library. Execute: "composer.phar install" in ./simpleproject For more info in ./simpleproject/README.md
Assuming there were no permission issues, the project directory should look as follows:
$ ls -l ./simpleproject/ -rw-rw-r-- 1 maltblue maltblue 342 Jun 12 06:34 composer.json -rwxr-xr-x 1 maltblue maltblue 709565 Jun 12 06:34 composer.phar drwxrwxr-x 3 maltblue maltblue 4096 Jun 12 06:34 config drwxrwxr-x 3 maltblue maltblue 4096 Jun 12 06:34 data -rw-rw-r-- 1 maltblue maltblue 1807 Jun 12 06:34 init_autoloader.php -rw-rw-r-- 1 maltblue maltblue 1548 Jun 12 06:34 LICENSE.txt drwxrwxr-x 3 maltblue maltblue 4096 Jun 12 06:34 module drwxrwxr-x 5 maltblue maltblue 4096 Jun 12 06:34 public -rw-rw-r-- 1 maltblue maltblue 1759 Jun 12 06:34 README.md drwxrwxr-x 3 maltblue maltblue 4096 Jun 12 06:34 vendor
Looking in the project directory, we see a new composer.json file, which has the basic configuration and requirements for a Zend Framework 2 project. If you’d like to go further, feel free to alter it as suits your needs, running composer update afterwards.
{
"name": "zendframework/skeleton-application",
"description": "Skeleton Application for ZF2",
"license": "BSD-3-Clause",
"keywords": [
"framework",
"zf2"
],
"homepage": "http://framework.zend.com/",
"require": {
"php": ">=5.3.3",
"zendframework/zendframework": ">2.2.0rc1"
}
}
With the basic files in place, unless you have the Zend Framework libraries on your path, the application won’t run. So, in the project directory, run composer.phar install to bring in the required libraries and dependencies.
The output will look similar to that below. I’ve trimmed it for sakes of readability.
$ composer.phar install
Loading composer repositories with package information
Installing dependencies (including require-dev)
- Installing zendframework/zendframework (2.2.0)
Downloading: 100%
Writing lock file
Generating autoload files
Now we’ve got the base project and dependencies, let’s create a module. We’ll call it “application”.
NB: I believe case is not important; so Application = application.
To create it, run the following command, from your project directory:
$ zftool.phar create module application</p>
Running it, however, returns output listing a series of mkdir errors. I believe this came about as the Application module was already there. If so, it would be helpful to print out a simple message indicating this, instead of attempting to proceed with creating an existing module.
Ok, now let’s create a module which doesn’t already exist; we’ll call it Generic. As before, we create the module via the command below:
zftool.phar create module Generic
You should see output similar to that below, indicating there were no problems.
The module Generic has been created
Looking in the Generic module directory, we see the following structure:
$ ls -l module/Generic/ total 16 drwxrwxr-x 2 maltblue maltblue 4096 Jun 12 06:47 config -rw-rw-r-- 1 maltblue maltblue 437 Jun 12 06:47 Module.php drwxrwxr-x 3 maltblue maltblue 4096 Jun 12 06:47 src drwxrwxr-x 2 maltblue maltblue 4096 Jun 12 06:47 view
Under config is a module.config.php file. So, we now have the basic structure of a ZF2 module.
But what if we want to see the list of modules? Well, here’s where I hit an issue. I believe the following command will show us that list.
$ php zftool.phar modules
But no matter what I tried, it always resulted in the following error:
No modules installed. Are you in the root folder of a ZF2 application?
At this stage, I’m not sure if it’s a bug or a user (me) problem. However, as I get more information, I’ll update the post about this issue.
Ok, we’re just about done. If you’re familiar with Zend Framework 2, you’ll know that performance can be increased through a classmap file.
A class map file stores a map of files which the application may require, saving it from performing a file location resolution. Effectively, it’s a class file location cache.
Let’s assume we have a series of classes in the module directory. Let’s create a classmap file for it. To do so, we run the following command:
$ zftool classmap generate module/ autoadclassmap.php
This looks for all class files in the module directory and then writes it out to autoadclassmap.php in the current directory. It will have output similar to that below:
Creating classmap file for library in /home/parallels/zftool/vendor/simpleproject/module Scanning for files containing PHP classes .... DONE Found 4 PHP classes Creating classmap code ... DONE Writing classmap to autoload_classmap.php... DONE Wrote classmap to /home/parallels/zftool/vendor/simpleproject/autoload_classmap.php
If you've not seen a classmap file before, here's what the one we just created looks like (formatted for better readability):
$ cat autoload_classmap.php
<?php
// Generated by Zend Framework 2
return array(
'Generic\Module' => DIR . '/module/Generic/Module.php',
'Application\Controller\IndexController' => DIR .
'/module/Application/src/Application/Controller/IndexController.php',
'Application\Module' => DIR . '/module/Application/Module.php',
'Users\Module' => DIR . '/module/Users/Module.php',</p>
Now on to the last command we're going to run, module diagnostics. I'm going to run diagnostics on the new, Generic, module we've created in this tutorial. From the project root, run the following command:
$ zftool diag --debug Generic
This will run diagnostics, showing debug information. In this case, just re-iterating the running version of PHP.
Starting diagnostics: OK ZF: PHP Version: Current PHP version is 5.4.6-1ubuntu1.2 -------------------------------------------------------------------- '5.4.6-1ubuntu1.2' ------------------------------------------------------------------------ OK (1 diagnostic tests)
Running it again, with the verbose flag set, show's approximately the same information, just less detailed. We can see here there were no issues with the module. So there was nothing to report.
$ php ../zftool.phar diag -v Application Starting diagnostics: OK ZF: PHP Version: Current PHP version is 5.4.6-1ubuntu1.2</p> OK (1 diagnostic tests)
I must admit I'm not quite sure of the intent of the diagnostic tool. I've renamed Module.php in Generic, renamed the Generic module directory, yet still the tool reports everything is ok.
I'll be doing so more research into this and updating the article with what is found.
And this brings us to the end of our walkthrough of zftool in Zend Framework 2. Now that we've finished the walk through, I hope you now have a good understanding of how to use it in your projects, to alleviate some of the manual work required in setting them up as well as creating modules.
I'm looking forward to it having a larger array of features, as time goes on. But for now, unfortunately, zftool is rather limited.
If you'd like to contribute to the project and help get the features reader sooner, clone a copy of the code and get involved. I'm sure your contribution will be well received.
What do you think of zftool? Good enough to use in your projects? Do you have home-made tools that already do what it provides (and more)? If so, share your thoughts in the comments.
In part 3 of this series on \Zend\Db\Sql\Select in Zend Framework 2 We cover the constructor, columns function, aliases and expressions, finishing up with limit and order functions. Come wind up the series in style.
Do you need to use different elements of a Zend Form, in multiple locations? Are you keen to reuse the same form class and avoid code duplication but don’t know how? Come learn about validation groups.
In today’s tutorial we look at a simple way of rendering CSV output in Zend Framework 2, using only a View Template and Controller Action. We see just how easy it is to generate content and send it to the browser, instead of rendering a standard .pthml template.
In today’s post, we look at more HTML5 Form fields in Zend Framework 2: Month, Range, Color, Week and Number, as well as element properties and attributes. Come look around more of the great new elements available.
Please consider buying me a coffee. It really helps me to keep producing new tutorials.
Join the discussion
comments powered by Disqus