Introduction

In this tutorial, a tiny demo application will be constructed to highlight key features of the Zend Framework and demonstrate how its components could be integrated and used together. Although the demo application is not intended for production use, the working application provides a simple skeleton for building Zend Framework applications. Even advanced PHP developers may find some parts of the demo enlightening to see how the Zend Framework might differ from other frameworks in its use and application of design patterns and components providing popular functionality.

For those less familiar with MVC and frameworks, an ultra-light example is presented, before we begin building the forum demo application in order to avoid introducing too much complexity too fast.

1 Introduction

1.1 What is the Zend Framework?
1.2 Why the ZF?
1.3 Who?
1.4 Requirements
1.5 Installation of the ZF Demo Source

1.5.1 Avoiding white screens
1.5.2 Ultra-Quick Install
1.5.3 Quick install using SVN
1.5.4 Installing the Zend Framework without SVN
1.5.5 Optional: Installation of ZF Library in Alternative Location

1.6 Loading the Demo SQL Schema

1.6.1 Check MySQL Connection
1.6.2 Verify access to database instance
1.6.3 Installing the ZFDemo SQL Schema

1.7 Testing Your Installation

1.7.1 Testing the Installed ZF
1.7.2 Installing the ZFDemo Test Script
1.7.3 Testing the ZFDemo Install Test Script

What is the Zend Framework?

The Zend Framework (ZF) is a simple, straightforward, open-source software framework for PHP 5, and beyond, designed to eliminate the tedious details of coding and let you focus on the big picture. A large open-source community lead by Zend has invested enormous efforts to make the ZF a robust framework, suitable for both large and small tasks. A central goal emphasizing "extremely simple to use" is evident throughout the ZF, and has become one of the Zend Framework's key strengths. Similarly, the ZF gives preference to popularly recognized "best practices" through the use of many design patterns.

Why the ZF?

Several specific components in the ZF offer potential users true "gems" to enjoy and work with, including search, PDF, i18n/l10n, MVC, and more. Each offers "extras" and special features combined with ease-of-use making the ZF attractive for large team development efforts as well as individuals who have little time to spare and "just need to get the job done". The ZF adds new meaning to "done is beautiful" for projects completed using the elegantly architected ZF components.

Who?

For more information about the ongoing development and enhancements, please see the ZF Developers Website. The extraordinary ZF development community contains dozens of members from around the world, giving the ZF a wonderful internationalized "flavor". With the strong, continual backing of resources and support from Zend, the makers of PHP, the ZF's evolution continues at a reliable, solid, sustainable pace.

The Zend Framework is divided into [categorical groups] with [project teams] and mailing lists assigned to each of these groups.

Requirements

Another defining characteristic of the ZF arises from its ability to work without requiring unusual or non-standard PHP extensions. However, the forum demo in this tutorial is based on MySQL. Patches to support other databases are welcomed, but should completely replace code for MySQL, instead of adding code, since streamlined examples are easier to understand and follow by those reading this tutorial.

PHP 5.1.4 or newer is required, but PHP 5.2.1+ is recommended, especially for production systems.
MySQL 5 or newer is required for the forum demo, but not the introductory example in the next section.
Web server like IIS, Apache, or Lighttpd and shell access with or without mod_rewrite
Zend Framework 0.8 Official Release (not Subversion or snapshot versions) - Note: Until ZF 1.0 is released, this demo requires the latest subversion update of the ZF.
Web browser that correctly supports both UTF-8 and XHTML (i.e. any recent version of the popular browsers).

Hint: For a speedy, less painful install of PHP, MySQL, and a web server see this list of Alternative Ways to Install a PHP Platform for ZF.

Installation of the ZF Demo Source

Make sure your web server has enabled the equivalent of Apache's AcceptPathInfo. This feature causes the web server to pass trailing URI parts to PHP for URLs like, "http://www.yourserver.com/index.php/trailing/URI/parts".

Make sure your system meets the minimum requirements shown above for this demo, and the Zend Framework requirements.

Download the Zend Framework stable release for this demo.

For more information about the ZF Lab, see "http://framework.zend.com/wiki/display/ZFPROP/Home". For those familiar with older versions of the ZF, you won't find the familiar "Zend.php" file. After approximately 2007-03-12, ZF 0.8dev and later replaces "Zend.php" with multiple classes, each containing logically related functions. This change simplifies organization of the ZF and checkout by containing all source files under "library/Zend".

Avoiding white screens

For development, blank white screens can be frustrating. Try enabling display_errors in your "php.ini" file. Also make sure to disable any caching software or output buffering on your server or in your application so that errors are not captured and hidden.

Ultra-Quick Install

For experts, and the impatient:

Obtain the ZF library, the ZF Demo, and the ZF incubator.
Configure your PHP include_path in php.ini, and enable AcceptPathInfo in Apache's httpd.conf
Tweak "section1_install/config.ini" (and */config.ini for other sections you want to test)
Create a MySQL database instance named zfdemo, username admin, password demo
Copy "section1_install/index.php" to your website and test.
Make backup copies of tweaked config files (e.g. config/config.ini.bak).
Try accessing the copied index.php from your web browser.
Install the "config/zfdemo.sql" into a MySQL instance, if the script above was unable to automatically install the ZF Demo tables and data.

Resume reading with "Testing Your Installation" below, or "Optional: Installation of ZF Library in Alternative Location" if you want to install the ZF library in a different location than described above.

Quick install using SVN

The ZFDemo comes in many, standalone parts named "sections" in this tutorial. Initial installation consists of downloading all the needed files, and organizing them for use by your web server and PHP. Afterward, installation of individual sections requires very little effort, since copying a single file to your web server's directory will "install" a chosen section of the demo.

The method below downloads and installs both the ZFDemo and the Zend Framework, but you need Subversion. For more information about using Subversion (and installing it on Windoze), see ZF Subversion Help.

Next, download the latest copy of the ZFDemo into your home directory:

cd # to your home directory
svn checkout http://framework.zend.com/svn/laboratory/zfdemo
cd zfdemo
svn checkout http://framework.zend.com/svn/framework/trunk/library/Zend
// The following is needed, until Zend_Environment has been moved to the ZF core library
cd Zend
svn export http://framework.zend.com/svn/framework/trunk/incubator/library/Zend/
mv Zend/Environment* .

Now, updating to the latest version of the demo is easy!

cd # to your home directory
cd zfdemo
svn update

Resume reading with "Loading the Demo SQL Schema" below. Also see "Optional: Installation of ZF Library in Alternative Location", if you want to install the ZF library in a different location than described above.

Installing the Zend Framework without SVN

Not supported yet, since there is no download available without using SVN.

If you are not using Subversion (see above) to install the ZF, then after downloading, decide where to install the ZF. For the ZFDemo, the ZF can be installed by simply moving the "library/Zend" directory into the topmost directory in the ZFDemo (i.e. "zfdemo/Zend").

Resume reading with "Loading the Demo SQL Schema" below. Also see "Optional: Installation of ZF Library in Alternative Location", if you want to install the ZF library in a different location than described above.

Optional: Installation of ZF Library in Alternative Location

Alternatively, the ZF library could be installed in a location more convenient for sharing with multiple ZF applications. Use the PHP include_path to share a single copy of the ZF with multiple applications by listing the full path to the ZF "library" directory first. For example, install the Zend Framework library into your directory containing other libraries of PHP code:

mkdir ~/library
mv Zend ~/library

Next, make sure PHP's include path lists "~/library" (or equivalent). Sometimes the "php.ini" file used by your web server is different than the one used by php on the command line:

$ php -i | grep "php.ini|include_path"

// Cygwin
include_path = "/cygdrive/c/yourname/home/zftrunk/tests:/cygdrive/c/yourname/home/zftrunk/library/:.:/usr/local/lib/php/:/php/includes"

// ZF Community Dev Server
include_path = ".:/home/yourname/mainwebsite_html/zftrunk/tests:/home/yourname/mainwebsite_html/zftrunk/library:/php/includes:/usr/share/php"

Loading the Demo SQL Schema

In order to load the demo SQL schema into your database instance, first make sure you have an instance. Many web hosters provide a GUI administration web interface for this purpose. Use the name 'zfdemo' if possible, since the section*_*/config/config.ini files already have "database.name = zfdemo". If you need to use a different name, remember to change all these configuration files to the correct database instance name.

Hopefully most ZFDemo users will find simply copying section1_install/index.php to their web server provides a means for automatic setup of the needed ZFDemo tables by accessing that web page from their browser. If your browser shows you a dump of the tables, then skip to "Testing Your Installation" below. If not, then continue on with this section.

In the following section, various methods of using the mysql command are explored to help with loading the ZFDemo SQL schema into your database instance. Variations of the following will be presented and explained:

$ mysql --host=127.0.0.1 -uroot -pgsandbox zfdemo < section4_mvc/config/zfdemo.sql

Check MySQL Connection

Next, try to connect manually to your database instance:

$ mysql -u<username> -p<password> <database instance name>

$ mysql -uadmin -pdemo --socket=  zfdemo

$ mysql -uadmin -pdemo --host=127.0.0.1  zfdemo

If the connection fails, check usernames, passwords, host names, and the database name. You may need to locate the "my.cnf" MySQL configuration file to determine how to properly connect.

$ grep sock /etc/my.cnf ~/.my.cnf /usr/local/mysql/etc/my.cnf

Other common locations for the UNIX socket:
    /var/run/mysqld/mysqld.sock
    /var/tmp/mysql.sock
    /var/run/mysql/mysql.sock
    /var/lib/mysql/mysql.sock
    /var/mysql/mysql.sock
    /usr/local/mysql/var/mysql.sock
    /Private/tmp/mysql.sock
    /tmp/mysql.sock

Make sure you can access your MySQL database, before proceeding with any tutorial section using the database. If you choose to use a different name than "zfdemo", please substitute your name choice with "zfdemo" below and in the file "zfdemo/config/config.ini".

Verify access to database instance

$ mysql -u<username> -p<password> <database instance name>
mysql> show databases;
+--------------------+
| Database           |
+--------------------+
| information_schema |
| mysql              |
| phpmyadmin         |
| test               |
| zfdemo             |  <===== MUST EXIST before proceeding
+--------------------+         (You can choose a different name.)
5 rows in set (0.00 sec)

mysql> use zfdemo;

Unless you have "root" or admin access to your MySQL database, please refer to your local system administrator or web hoster for instructions about creating a database instance or obtaining access to an existing instance. If possible, use a clean, empty database instance, so that all tables can be dropped and restored easily, without harming any important data already present.

If your database is configured to use a socket file, then replace "-~~host=127.0.0.1" with "~~-socket=<path>", where <path> is the socket file located and tested at the beginning of this section.

Installing the ZFDemo SQL Schema

If you have access to phpMyAdmin, then the SQL schema file "section4_mvc/config/zfdemo.sql" can be copied and directly pasted into the web page accessed via the "SQL" folder tab in phpMyAdmin.

Alternatively, the schema file can be loaded from the command line, as follows:

$ mysql --host=127.0.0.1 -uroot -pgsandbox zfdemo < section4_mvc/config/zfdemo.sql
$ mysql --host=127.0.0.1 -uroot -pgsandbox zfdemo
mysql> use zfdemo
Database changed
mysql> show tables;
+------------------+
| Tables_in_zfdemo |
+------------------+
| attachments      |  <=== If everything worked above,
| posts            |  <=== you will see these tables.
| topics           |  <===
| users            |  <===
+------------------+
4 rows in set (0.02 sec)

Replace "127.0.0.1" with the correct IP address or hostname for your database server. Also replace "zfdemo" with the name of your database instance above, and in any future example code snippets.

Testing Your Installation

The following tests help determine if the installation and configuration has succeeded.

Testing the Installed ZF

Now, make sure the following script outputs "Ready!".

$ php
<?php
require 'Zend/Version.php';

if (Zend_Version::compareVersion('0.9.2beta') > 0) {
    echo "Please upgrade to a newer version of ZF for this demo.\n";
} else {
    echo "Ready!\n";
}
?>

Then, create a directory (e.g. 'zfdemo') inside your web document root (often "www" or "public_html") and copy the index.php file from "zfdemo/section1_install/index.php" into the newly created directory. This file is not really the demo itself, but only a testing script to help diagnose any issues that will prevent the real demos from running correctly. Each of the "sectionN_*" directories has a copy of the ZFDemo. Later sections have the same code as the previous section, but with more code added relating to the subject of the current section.

Lastly, try accessing this "index.php" from your web browser:

http://www.your_website.com/zfdemo/index.php

Installing the ZFDemo Test Script

Do NOT install the demo on a security-sensitive website. The demo is in rapid development, and may or may not contain a XSS vulnerability as a result of design goals placing higher priorities on training and education. After the demo has stabilized, the code will be reviewed for potential security issues.

After completing the initial installation of files (see installation sections above), to install the code discussed in each section of the tutorial, copy the single "index.php" file from "section1_install/index.php" to your web server's document root directory (e.g. "www" or "public_html"). As with all of the demo examples in this tutorial, the "index.php" file can work from within a subdirectory/subfolder. If you want to install the demo sections without affecting the rest of your website, you may optionally create a subdirectory, like "www/zfdemo", and then copy the "index.php" to this subdirectory. Using a ".htacess" file can improve security by restricting access, if the web server is not completely isolated/private.

After copying the file onto your website, make sure the demo code tree (containing section#_* subdirectories) is in the directory containing your web server's document root directory, which might be a symbolic link. For example, my home directory contains:

/home/gavin
    .bashrc
    misc/
    www@          # use this if present in your directory
    public_html/  # use this if present in your directory
    zfdemo/   # demo source code, config files, data directories, etc.

The "www" entry is a symbolic link to another location containing:

index.php    # my website home page
many other files
zfdemo/
    index.php # a file I copied from one of the sections in /home/gavin/zfdemo/section*/

Testing the ZFDemo Install Test Script

To begin, the demo needs at least one piece of information - where to find the configuration information. The demo expects to find its source and configuration files in a subdirectory that is relative to the location of the "index.php" you copied as part of the installation instructions. There are many versions of this demo, with various features added. Each version is in a shared subdirectory. Thus, the demo looks in "../../zfdemo/$demoDir/". Hopefully, it won't be difficult to get the index file located correctly relative to the zfdemo subdirectory. You might have to adjust the first line of code in the "bootstrap" function in index.php:

$tmp = dirname(__FILE__) . DIRECTORY_SEPARATOR . '..' . DIRECTORY_SEPARATOR

If all works as expected, you should see:

Welcome to the ZF Demo Install Test

1. Continue Test
2. Online Tutorial

UTF-8 Rendering Test:

Umlauts and accented characters: many odd looking characters

more odd looking characters

Euro currency symbol
etc.

ZF Demo Debug Log

list of installed PHP extensions

various information helpful for debugging installation issues

Next Section: 2. Introduction to Model-View-Controller Architectural Pattern

Page Operations

Browse Space

1. Introduction

Labels