Programmer's Reference Guide

Programmer's Reference Guide

Overview

Introduction to Zend FrameworkTable of Contents Overview Installation

Introduction to Zend Framework

Introduction to Zend Framework

Installation

OverviewZend Framework is an open source framework for developing web applications and services with PHP 5. Zend Framework is implemented using 100% object-oriented code. The component structure of Zend Framework is somewhat unique; each component is designed with few dependencies on other components. This loosely coupled architecture allows developers to use components individually. We often call this a "use-at-will" design. While they can be used separately, Zend Framework components in the standard library form a powerful and extensible web application framework when combined. Zend Framework offers a robust, high performance MVC implementation, a database abstraction that is simple to use, and a forms component that implements HTML form rendering, validation, and filtering so that developers can consolidate all of these operations using one easy-to-use, object oriented interface. Other components, such as Zend_Auth and Zend_Acl, provide user authentication and authorization against all common credential stores. Still others implement client libraries to simply access to the most popular web services available. Whatever your application needs are, you're likely to find a Zend Framework component that can be used to dramatically reduce development time with a thoroughly tested foundation. The principal sponsor of the project 'Zend Framework' is Zend Technologies, but many companies have contributed components or significant features to the framework. Companies such as Google, Microsoft, and StrikeIron have partnered with Zend to provide interfaces to web services and other technologies that they wish to make available to Zend Framework developers. Zend Framework could not deliver and support all of these features without the help of the vibrant Zend Framework community. Community members, including contributors, make themselves available on mailing lists, IRC channels, and other forums. Whatever question you have about Zend Framework, the community is always available to address it.

Introduction to Zend Framework

Overview

Introduction to Zend Framework

Learning Zend Framework

InstallationSee the requirements appendix for a detailed list of requirements for Zend Framework. Installing Zend Framework is extremely simple. Once you have downloaded and extracted the framework, you should add the /library folder in the distribution to the beginning of your include path. You may also want to move the library folder to another possibly shared location on your file system. Download the latest stable release. This version, available in both .zip and .tar.gz formats, is a good choice for those who are new to Zend Framework. Download the latest nightly snapshot. For those who would brave the cutting edge, the nightly snapshots represent the latest progress of Zend Framework development. Snapshots are bundled with documentation either in English only or in all available languages. If you anticipate working with the latest Zend Framework developments, consider using a Subversion (SVN) client. Using a Subversion (SVN) client. Zend Framework is open source software, and the Subversion repository used for its development is publicly available. Consider using SVN to get Zend Framework if you already use SVN for your application development, want to contribute back to the framework, or need to upgrade your framework version more often than releases occur. Exporting is useful if you want to get a particular framework revision without the .svn directories as created in a working copy. Check out a working copy if you want contribute to Zend Framework, a working copy can be updated any time with svn update and changes can be commited to our SVN repository with the svn commit command. An externals definition is quite convenient for developers already using SVN to manage their application's working copies. The URL for the trunk of Zend Framework's SVN repository is: http://framework.zend.com/svn/framework/standard/trunk Once you have a copy of Zend Framework available, your application needs to be able to access the framework classes. Though there are several ways to achieve this, your PHP include_path needs to contain the path to Zend Framework's library. Zend provides a QuickStart to get you up and running as quickly as possible. This is an excellent way to begin learning about the framework with an emphasis on real world examples that you can build upon. Since Zend Framework components are loosely coupled, you may use a somewhat unique combination of them in your own applications. The following chapters provide a comprehensive reference to Zend Framework on a component-by-component basis.

Installation

Programmer's Reference Guide

Zend Framework Quick Start

Learning Zend FrameworkTable of Contents Zend Framework Quick Start Zend Framework & MVC Introduction Create Your Project Create A Layout Create a Model and Database Table Create A Form Congratulations! Autoloading in Zend Framework Introduction Goals and Design Basic Autoloader Usage Resource Autoloading Conclusion Plugins in Zend Framework Introduction Using Plugins Conclusion Getting Started with Zend_Layout Introduction Using Zend_Layout Zend_Layout: Conclusions Getting Started Zend_View Placeholders Introduction Basic Placeholder Usage Standard Placeholders View Placeholders: Conclusion Understanding and Using Zend Form Decorators Introduction Decorator Basics Layering Decorators Rendering Individual Decorators Creating and Rendering Composite Elements Conclusion Getting Started with Zend_Session, Zend_Auth, and Zend_Acl Building Multi-User Applications With Zend Framework Managing User Sessions In ZF Authenticating Users in Zend Framework Building an Authorization System in Zend Framework Getting Started with Zend_Search_Lucene Zend_Search_Lucene Introduction

Lucene Index Structure Index Opening and Creation Indexing Searching Supported queries Search result pagination Getting Started with Zend_Paginator Introduction Simple Examples Pagination Control and ScrollingStyles Putting it all Together

ZendX_JQuery Form Elements and Decorators

Programmer's Reference Guide

Introduction

Zend Framework RequirementsTable of Contents Introduction

Learning Zend Framework

Learning Zend Framework

Zend Framework & MVC Introduction

Zend Framework Quick StartTable of Contents Zend Framework & MVC Introduction Create Your Project Create A Layout Create a Model and Database Table Create A Form Congratulations!

Zend Framework Quick Start

Zend Framework Quick Start

Create Your Project

Zend Framework & MVC Introduction Zend FrameworkZend Framework is an open source, object oriented web application framework for PHP 5. Zend Framework is often called a 'component library', because it has many loosely coupled components that you can use more or less independently. But Zend Framework also provides an advanced Model-View-Controller (MVC) implementation that can be used to establish a basic structure for your Zend Framework applications. A full list of Zend Framework components along with short descriptions may be found in the components overview. This QuickStart will introduce you to some of Zend Framework's most commonly used components, including Zend_Controller, Zend_Layout, Zend_Config, Zend_Db, Zend_Db_Table, Zend_Registry, along with a few view helpers. Using these components, we will build a simple database-driven guest book application within minutes. The complete source code for this application is available in the following archives: zip tar.gz

Model-View-ControllerSo what exactly is this MVC pattern everyone keeps talking about, and why should you care? MVC is much more than just a three-letter acronym (TLA) that you can whip out anytime you want to sound smart; it has become something of a standard in the design of modern web applications. And for good reason. Most web application code falls under one of the following three categories: presentation, business logic, and data access. The MVC pattern models this separation of concerns well. The end result is that your presentation code can be consolidated in one part of your application with your business logic in another and your data access code in yet another. Many developers have found this well-defined separation indispensable for keeping their code organized, especially when more than one developer is working on the same application. Note: More Information Let's break down the pattern and take a look at the individual pieces:

Model - This is the part of your application that defines its basic functionality behind a set of abstractions. Data access routines and some business logic can be defined in the model. View - Views define exactly what is presented to the user. Usually controllers pass data to each view to render in some format. Views will often collect data from the user, as well. This is where you're likely to find HTML markup in your MVC applications. Controller - Controllers bind the whole pattern together. They manipulate models, decide which view to display based on the user's request and other factors, pass along the data that each view will need, or hand off control to another controller entirely. Most MVC experts recommend keeping controllers as skinny as possible.Of course there is more to be said about this critical pattern, but this should give you enough background to understand the guestbook application we'll be building.

Zend Framework & MVC Introduction

Zend Framework Quick Start

Create A Layout

Create Your ProjectIn order to create your project, you must first download and extract Zend Framework.

Install Zend FrameworkThe easiest way to get Zend Framework along with a complete PHP stack is by installing Zend Server. Zend Server has native installers for Mac OSX, Windows, Fedora Core, and Ubuntu, as well as a universal installation package compatible with most Linux distributions. After you have installed Zend Server, the Framework files may be found under /usr/local/zend/share/ZendFramework on Mac OSX and Linux, and C:\Program Files\Zend\ZendServer\share\ZendFramework on Windows. The include_path will already be configured to include Zend Framework. Alternately, you can Download the latest version of Zend Framework and extract the contents; make a note of where you have done so. Optionally, you can add the path to the library/ subdirectory of the archive to your php.ini 's include_path setting. That's it! Zend Framework is now installed and ready to use.

Create Your ProjectNote: zf Command Line Tool In your Zend Framework installation is a bin/ subdirectory, containing the scripts zf.sh and zf.bat for Unix-based and Windows-based users, respectively. Make a note of the absolute path to this script. Wherever you see references to the command zf, please substitute the absolute path to the script. On Unix-like systems, you may want to use your shell's alias functionality: alias zf.sh=path/to/ZendFramework/bin/zf.sh. If you have problems setting up the zf command-line tool, please refer to the manual. Open a terminal (in Windows, Start -> Run, and then use cmd). Navigate to a directory where you would like to start a project. Then, use the path to the appropriate script, and execute one of the following:1. % zf create project quickstart

Running this command will create your basic site structure, including your initial controllers and views. The tree looks like the following:1. 2. 3. 4. 5. quickstart |-- application | |-- Bootstrap.php | |-- configs | | `-- application.ini

6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26.

| | | | | | | | | | | |-|-| | `--

|-| | |-`--

controllers |-- ErrorController.php `-- IndexController.php models views |-- helpers `-- scripts |-- error | `-- error.phtml `-- index `-- index.phtml library public |-- .htaccess `-- index.php tests |-- application | `-- bootstrap.php |-- library | `-- bootstrap.php `-- phpunit.xml

At this point, if you haven't added Zend Framework to your include_path, we recommend either copying or symlinking it into your library/ directory. In either case, you'll want to either recursively copy or symlink the library/Zend/ directory of your Zend Framework installation into the library/ directory of your project. On unix-like systems, that would look like one of the following:1. 2. 3. 4. 5. # Symlink: % cd library; ln -s path/to/ZendFramework/library/Zend . # Copy: % cd library; cp -r path/to/ZendFramework/library/Zend .

On Windows systems, it may be easiest to do this from the Explorer. Now that the project is created, the main artifacts to begin understanding are the bootstrap, configuration, action controllers, and views.

The BootstrapYour Bootstrap class defines what resources and components to initialize. By default, Zend Framework's Front Controller is initialized, and it uses the application/controllers/ as the default directory in which to look for action controllers (more on that later). The class looks like the following:1. 2. 3. 4. 5. // application/Bootstrap.php class Bootstrap extends Zend_Application_Bootstrap_Bootstrap { }

As you can see, not much is necessary to begin with.

ConfigurationWhile Zend Framework is itself configurationless, you often need to configure your application. The default configuration is placed in application/configs/application.ini, and contains some basic directives for setting your PHP environment (for instance, turning error reporting on and off), indicating the path to your bootstrap class (as well as its class name), and the path to

your action controllers. It looks as follows:1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. ; application/configs/application.ini [production] phpSettings.display_startup_errors = 0 phpSettings.display_errors = 0 includePaths.library = APPLICATION_PATH "/../library" bootstrap.path = APPLICATION_PATH "/Bootstrap.php" bootstrap.class = "Bootstrap" appnamespace = "Application" resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers" resources.frontController.params.displayExceptions = 0 [staging : production] [testing : production] phpSettings.display_startup_errors = 1 phpSettings.display_errors = 1 [development : production] phpSettings.display_startup_errors = 1 phpSettings.display_errors = 1

Several things about this file should be noted. First, when using INI-style configuration, you can reference constants directly and expand them; APPLICATION_PATH is actually a constant. Additionally note that there are several sections defined: production, staging, testing, and development. The latter three inherit settings from the "production" environment. This is a useful way to organize configuration to ensure that appropriate settings are available in each stage of application development.

Action ControllersYour application's action controllers contain your application workflow, and do the work of mapping your requests to the appropriate models and views. An action controller should have one or more methods ending in "Action"; these methods may then be requested via the web. By default, Zend Framework URLs follow the schema /controller/action , where "controller" maps to the action controller name (minus the "Controller" suffix) and "action" maps to an action method (minus the "Action" suffix). Typically, you always need an IndexController, which is a fallback controller and which also serves the home page of the site, and an ErrorController, which is used to indicate things such as HTTP 404 errors (controller or action not found) and HTTP 500 errors (application errors). The default IndexController is as follows:1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. // application/controllers/IndexController.php class IndexController extends Zend_Controller_Action { public function init() { /* Initialize action controller here */ } public function indexAction() { // action body } }

And the default ErrorController is as follows:1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. // application/controllers/ErrorController.php class ErrorController extends Zend_Controller_Action { public function errorAction() { $errors = $this->_getParam('error_handler'); switch ($errors->type) { case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE: case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER: case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION: // 404 error -- controller or action not found $this->getResponse()->setHttpResponseCode(404); $this->view->message = 'Page not found'; break; default: // application error $this->getResponse()->setHttpResponseCode(500); $this->view->message = 'Application error'; break; } $this->view->exception = $errors->exception; $this->view->request = $errors->request; } }

You'll note that (1) the IndexController contains no real code, and (2) the ErrorController makes reference to a "view" property. That leads nicely into our next subject.

ViewsViews in Zend Framework are written in plain old PHP. View scripts are placed in application/views/scripts/, where they are further categorized using the controller names. In our case, we have an IndexController and an ErrorController, and thus we have corresponding index/ and error/ subdirectories within our view scripts directory. Within these subdirectories, you will then find and create view scripts that correspond to each controller action exposed; in the default case, we thus have the view scripts index/index.phtml and error/error.phtml. View scripts may contain any markup you want, and use the closing tag to insert PHP directives. The following is what we install by default for the index/index.phtml view script:1. 2. 3. 4. a:link, 5. a:visited 6. { 7. color: #0398CA; 8. } 9. 10. span#zf-name 11. { 12. color: #91BE3F; 13. } 14. 15. div#welcome 16. { 17. color: #FFFFFF; 18. background-image: url(http://framework.zend.com/images/bkg_header.jpg); 19. width: 600px; 20. height: 400px; 21. border: 2px solid #444444;

22. overflow: hidden; 23. text-align: center; 24. } 25. 26. div#more-information 27. { 28. background-image: url(http://framework.zend.com/images/bkg_body-bottom.gif); 29. height: 100%; 30. } 31. 32. 33. 34. Welcome to the Zend Framework! 35. This is your project's main page 36. 37. 38. 39. 40. 41. 42. Helpful Links:
43. Zend Framework Website | 44. Zend Framework 45. Manual 46. 47. 48. 49.

The error/error.phtml view script is slightly more interesting as it uses some PHP conditionals:1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30.