Partial Content

Working with eZ Publish 5 - Setup

About The Project

This tutorial started because I wanted to start a blog - and one of the first things I wanted to blog about was building a site with eZ Publish 5. So it seemed natural to use building a blog as an example in the tutorial. So throughout this code we'll be building is the early version of the very blog you're reading. While I wrote the tutorial and the blog, I saved branches in the code to make it easier to follow along.

Requirements

I'm assuming that you already have a decent Apache, Mysql, and PHP setup running and configured for setting up virtual hosts. You'll want to have at least PHP 5.3.8 and MySQL 5.0.51, and some version of ImageMagick. On a Mac, Homebrew is a quick way to get most of this up and running. Vagrant is also a great way to provide a performant virtual environment to use as a development sandbox. You'll also need to have git installed to retrieve the tutorial code.

The tutorial assumes that you're running Mysql locally, and that the site is in a directory called /Sites/ez5tutorial. If you're placing it somewhere else, you'll need to make some adjustments, and I'll try to point those out.

My goal in the tutorial is to teach you how to develop with eZ, not how to install it, so the repository we're using is focused on just getting everything up and running quickly. eZ Systems provides a detailed installation guide, so look there when you start a real project.

Installing the site

To retrieve the code for the tutorial, create a '/Sites' directory, 'cd' to it in your terminal, and pull a copy of the repository from github:

git clone git://github.com/blendinteractive/ez5tutorial.git

Then, 'cd' to 'ez5tutorial' and check out the initial tutorial branch:

git checkout -b tutorial-1 origin/tutorial-1 

In the /Sites/ez5tutorial directory, you'll now have a few new subdirectories. The notable ones: 

  • apache - Apache configuration
  • ez - Here's where eZ Publish is set up
  • sql - A set of sql files for working with the tutorial
  • logs - the apache config points here to save its logs

Hosts File

Modify your computer's hosts file ('/etc/hosts' on most Linux/Mac machines) and add lines for 'ez5tutorial.local' and 'admin.ez5tutorial.local' to point at your localhost: 

127.0.0.1 ez5tutorial.local admin.ez5tutorial.local 

Apache Config

Include the Apache virtual host config stored in conf/local.conf in your Apache configuration. Edit the paths if your site isn't at /Sites/ez5tutorial. Make sure you restart Apache.

MySQL

Create a new database and user in your MySQL server:

CREATE DATABASE ez5tutorial CHARSET utf8;
GRANT ALL ON ez5tutorial.* TO ez5tutorial@localhost identified by 'ez5tutorialpassword';
FLUSH PRIVILEGES;

Load the provided sample data in the SQL folder. We'll start with 'initial.sql', which is a clean install containing demo content. 

cat sql/initial.sql | mysql -u ez5tutorial -p ez5tutorial 

Make sure to enter the password for your ez5tutorial user ('ez5tutorialpassword') at the prompt.

Symfony

First, make sure that the following folders and all their contents are writable by the web server:

  • ez/ezpublish/cache
  • ez/ezpublish/logs
  • ez/ezpublish/config
  • ez/ezpublish_legacy/design
  • ez/ezpublish_legacy/extension
  • ez/ezpublish_legacy/settings
  • ez/ezpublish_legacy/var

During development, most of these directories will need to be writable by both you and the web server. So while I don't recommend it for production installs, for this tutorial it's easiest to either set these directories as writable by everyone (777) or to run the apache user under the same user that you use in the terminal.

Next, we need to make sure all of the static assets needed by the system (javascript, css, images, etc) are available under the 'web' folder. Fortunately, eZ provides Symfony console commands to take care of this for us. Go to the root of your project in your console (the directory that contains 'ezpublish', 'ezpublish_legacy', 'web', etc) and run this command: 

php ezpublish/console 

What you'll see is a help text and a list of available commands. The ones we're looking for are the ones to install assets. Go ahead and run these two:

php ezpublish/console assets:install --symlink
php ezpublish/console ezpublish:legacy:assets_install --symlink

There are a lot more things that the console can do for us, but we'll come back to it later. For now, go ahead and access the site in your web browser.

If you played your cards right, you should have something like this running at http://ez5tutorial.local :

eZ5 Tutorial Site

 

Organization

Default eZ 5 File Structure

Go ahead and go in to the 'ez' folder. There are a lot of directories there. So what are we looking at? Let's talk about a couple of these pieces: 

  • composer.* - These are files for using the composer PHP dependency management system. It's very handy for maintaining projects with a lot of third-party libraries, but we'll ignore it for this tutorial so we're all using the same version of everything.
  • ezpublish - This is where the config, cache, and some logging components of eZ Publish live (this directory is called 'app' in most Symfony installs)
  • ezpublish_legacy - Take a peek in here - Look, it's our old friend eZ Publish 4! This is a full eZ 4 install, slightly updated.
  • src- This is where we'll be building out our code, in structures called bundles. There's a bundle already there, the EzSystemsDemoBundle, that implements a basic surround in symfony.
  • vendor - This is where most of the supporting third-party frameworks live, including components of Symfony and eZ Publish.
  • web - This is where you'll point Apache to as a web root. We'll set up Rewrite rules shortly to send most of our traffic to index.php, which is the endpoint that handles all requests to Symfony.

In your browser, you have two URLs available:

  • ez5tutorial.local, the public-facing web site
  • admin.ez5tutorial.local, the administrative site (user: admin, password: ez5tutorialpassword)

Our Plan

The goal of this project is to create a blog. This of course means that we have a series of posts displayed in reverse chronological order. The blog will be able to be divided into categories, so multiple topics can be covered. And there needs to be some way to combine multiple posts into a series of related posts. 

To accomplish all this, we'll be working with three content types: Blog, Blog Post, and Series. A Blog will contain either Blog Posts or Series, and will display all of the posts beneath it, even if those posts are themselves contained by Blog or Series objects. In this way, we can bring posts from more and more topic categories into a single stream by nesting the Blog objects. 

So our data model looks like this: 

  • Blog
    • Name
    • Tagline
    • Description (WYSIWYG)
    • URL Slug (for customizing the URL)
  • Blog Post
    • Title
    • Summary (WYSIWYG)
    • Body
    • Publication Date (Date/Time Field)
    • Comments (Comments Field)
  • Series
    • Title
    • Description (WYSIWYG)
    • Posts (Object Relation List)
    • URL Slug (for customizing the URL)

You can build this structure out manually, and enter some sample content, but to get things started I've included a SQL file with the content already configured. Note that this will break the front end view of your eZ Publish installation. That's OK! We're going to bring things in line with our new content in a moment.

You can load your installation with it by running the following command in a terminal: 

cat sql/ez5tutorial.sql | mysql -u ez5tutorial -p ez5tutorial 

(Enter the password for your 'ez5tutorial' user when prompted)

You'll need to log back in to your admin. Have a look at the 'Content Structure' to see what's there. The sample posts are the contents of this tutorial.

Now that we've got our site set up and sample content loaded, we can start developing by creating a bundle and building our layout templates.