Step 1: Download and extract the sample application files

• Click here to download the files.  
• For an explanation of the code used in this application, see Behind the Code.

Step 2: Copy the extracted directory to your Zend Server’s document root

• What is a Document Root?
• Where is my Document Root?

Step 3: Enable write permissions for the data/ directory

Note: When running Apache on Windows, write permissions are set by default and you can therefore skip this step.

This application will need to write data to the file system. You must therefore give your Web server user write permissions for the ‘data/’ directory of your sample application:

On Linux/Mac:  Run the command chown <web_server_user> <path_to_data_directory>.
Replace <web_server_user> with the name of your Web server user and replace <path_to_data_directory> with the location of the data/ directory (located in your extracted application directory).

E.g. run the following command: # chown www-data /var/www/jukebox/data

What is my Web server user?

On Windows/IIS: Right-click the data/ directory (located in your extracted application directory) and select Properties | Security. Ensure that your Web server user has write permissions for this folder. If necessary, click Add to add the Web server user and mark the ‘Write’ checkbox in the Permissions list. 

What is my Web server user?

Step 4: Run your application

Open a Web browser and browse to the main page of the application, located at  http://localhost:<port_number>/jukebox/index.php.

• Replace <port_number> with the port number on which your Web server listens.
• What is my port number?

Congratulations -  you can now use your application!

What next?

• See Behind the Code, below, to learn about the PHP code you have just run
• To access more sample applications which can be run on the Zend Server server, click here
• To learn more about PHP basics, visit PHP 101

Behind the code

The “jukebox” sample application is a simple PHP-based music library management application. It demonstrates using multiple PHP files in one application, and usage of the PDO interface to connect to and work with a database.
To view the code behind the application, open the application files in a text editor or in an IDE such as  Zend Studio for Eclipse.

Note: To import the files into Zend Studio for Eclipse, create a PHP project called ‘jukebox’ and import the application files into it by going to File menu | Import | General | File Sytem and browsing to the extracted ‘jukebox’ directory.

Let's get an overview of the purpose of the different files in our application:

jukebox/index.php
This is the application’s main page. It renders a list of the items currently stored in the database. Using the require_once() statement, this file loads other files which handle common functions such as querying the database, filtering entries or rendering the HTML header and footer.

jukebox/edit.php
This file renders the Add/Edit song page.  The operations performed by the file will vary depending on the the submitted HTTP request parameters ($_GET, $_POST and $_SERVER). This is determined by the action selected by the user:

• If a user clicks Add on the main page, a GET request will be submitted and the Add Song form will be displayed.
• If  a user clicks Edit next to one of the songs on the main page, a GET request will be submitted for the song details to be retrieved from the database, and the Edit Song form will be displayed.
• If  a user clicks Save on the Add/Edit Song form,  a POST request will be submitted, the new/edited entries will be saved in the database, and the user will be redirected to the homepage.

jukebox/common (html-bottom.php and html-top.php)
This directory contains PHP files that render HTML template elements (header and footer) that are common to all pages in the application.

jukebox/config/jukebox-config.php
This is the application’s configuration file which is read by all pages in the application. In this application  it only stores  the credentials for connecting to the database.

jukebox/data (jukebox.sq3 and schema.sql)
This directory contains the SQLite database files.  By default, the jukebox application connects to an embedded SQLite database, but can be configured to use other Relational Database Management Systems (RDBMS) supported by PDO. 

Note: For simplicity we have included the database files under the document root directory structure. However, for security reasons it is recommended to place database related files outside of the document root. In most production applications, a server based RDBM (Relational Database Management System), such as MySQL or Oracle, is used.

jukebox/library (JukeboxDb.php, JukeboxSong.php and JukeboxDataException.php)
This directory contains library files which are used by other parts of the application to access data stored in the database:

• JukeboxDb.php – This file defines the JukeboxDb class, which is used throughout the application to connect to and query the database. The class ‘wraps’ the PDO classes and provides a simplified database access interface.
• JukeboxSong.php – This file defines the JukeboxSong class, which is used throughout the application to represent a song. Each song is represented by an instance of this class. All song properties (e.g. artist, name etc.) are stored as properties within objects of this class. When song data is retrieved from the database, it is populated into instances of this class.
• JukeboxDataException.php – This file defines the JukeboxDataException class, which extends PHP’s built-in Exception class. It is used to represent errors related to data access in the application.

jukebox/style/jukebox.css
This is the application’s style sheet which defines the visual properties of the application.  This file is not parsed by PHP. Instead, it is parsed by the browser when pages are rendered.