Most Popular
Recently Added
Recently Updated

Setting up a Cerb5 local development environment

Introduction

We recommend that each developer maintains a local web environment on their development machine with a self-contained webserver, database, and dummy mail server. This article will explain how to accomplish this using the same toolset as the official developers.

Installing Eclipse as your Integrated Development Environment (IDE)

We recommend using Eclipse as your IDE, along with the PHP Development Tools (PDT) plugin.

There was no PDT package for the latest Eclipse 3.7 (Indigo) release, so you'll need to download Eclipse Classic and then install the PDT plugin manually.

Installing Eclipse

  1. Download Eclipse Classic for your platform.
  2. Extract it.
  3. Run it.

You'll be prompted to create a new workspace directory (e.g. "php5-workspaces"). Choose a location that is convenient for you; it does not need to be in the same place where your web-accessible files are located.

Installing PDT

  1. Open the Help menu and select Install New Software.
  2. In the Work With: dropdown, select "Indigo - http://download.eclipse.org/releases/indigo"
  3. In the filter box, type "pdt" and hit ENTER.
  4. Check "PHP Development Tools" under Programming Languages
  5. Click the Next button twice.
  6. Accept the software terms and click the Finish button.
  7. When prompted to restart Eclipse, select Restart Now.

Installing a web environment with Apache, MySQL, and PHP

Your local development machine should have the following services available:

  • Webserver (e.g. Apache, Nginx, lighttpd, IIS)
  • MySQL Server 5.x+
  • PHP 5.2+
    • Extensions: curl, imap, mailparse, mbstring

There are countless ways to install and maintain a local server:

XAMPP

One of the easiest ways to install a local webserver for PHP development is to use XAMPP. This will provide Apache, MySQL, and PHP. Installers are available for Linux, Mac OS X, Solaris, and Windows.

MacPorts

If you're using a Mac, you can use MacPorts to install these applications in /opt.

sudo port install apache2 php5 mysql5-server

Unix

If you're using a Unix-based operating system, use your distribution's package manager (e.g. apt-get, yum) to install these applications.

In Debian/Ubuntu:

apt-get install apache2 mysql-server php5

Installing a dummy mail server

Your development machine can use an existing mailserver, although you often want to remove the possibility of accidentally sending test messages to real recipients; especially if you're developing using a copy of your live data. This is best accomplished with a dummy SMTP server on a non-standard port (e.g. 2525).

There are a couple different options for a fake mail server:

  • Install Postfix using your package manager and set up a null transport.
  • If you're using a Mac, install our FakeSMTP project. This will listen for SMTP connections on an arbitrary port (2525 by default) and provide an easy way to inspect outgoing mail without actually delivering anything.
  • Python provides a dummy SMTP server by default:
    sudo python -m smtpd -n -c DebuggingServer localhost:2525

Installing Git

We use Git for distributed source control and versioning. You can test if Git is currently installed by running the command:

git --version

If Git is not installed, you can download the latest version for your platform from: http://git-scm.com/download

Pulling the project files from GitHub

Our project and plugins repositories are hosted on GitHub. You don't need a GitHub account to simply download our project files, but we recommend creating one so you can take advantage of the collaborative tools.

  1. Navigate to the web-accessible directory for the appropriate virtual host (or default) of your local webserver. For example, if you're using Apache this path is usually something like /var/www/. In Windows Server with IIS it may be C:\Inetpub\.

Selecting a repository

We have two main repositories for the project. The wgm/cerb5.git repository is a fork of jstanden/cerb5.git. The jstanden repository is where development and integration actually take place. During a stable release, the progress from jstanden is pushed to the wgm repository for public consumption. Most people will only need to use the latter.

If you're only developing third-party plugins...

If you only intend to work on your own custom plugins then you can anonymously use our repositories.

For access to stable releases, issue the following command at the console:
git clone https://github.com/wgm/cerb5.git

Otherwise, for access to development builds, issue the following command instead:
git clone https://github.com/jstanden/cerb5.git

If you plan to contribute to Cerb5, and work on plugins...

If you plan to contribute patches (e.g. bug fixes) to the Cerb5 project, in addition to working on custom plugins, we recommend that you fork the project on GitHub. This will create your own copy of our official repository that you can commit (save) your changes to. It also makes it easier for us to view and integrate those changes.

  1. Create a free account at GitHub if you don't already have one.
  2. Once logged in, browse to https://github.com/jstanden/cerb5
  3. Click the Fork button in the top right. This will create your own personal repository for making modifications to Cerb5.

When your repository is created, use the credentials from the SSH section on your page at GitHub to download your files.

For example (replace <you> with your account at GitHub):

git clone git@github.com:<you>/cerb5.git

Git graphical user interfaces

You can also use a graphical Git client like TortoiseGit for Windows or Tower.app for Mac; however, it is worth becoming proficient with the command line interface to Git since it will always provide you with full functionality. Git also comes with a simple GUI for managing your repository which can be accessed with the git gui command.

At WebGroup Media (WGM), we develop on Macs and use GitX to make it easy to visually audit changes before staging and committing them. Everything else is accomplished from the command line.

Importing the Cerb5 project in Eclipse

At this point, you will have a copy of the project in a web-accessible path.

  1. Open Eclipse.
  2. Open the File menu and select Import.
  3. Expand General and select Existing Projects into Workspace.
  4. Click the Next button.
  5. Click the Browse button next to Select root directory: and select the cerb5 directory from your webserver's web-accessible path. Click the Open button.
  6. The Cerb5 project should automatically be detected by Eclipse. Click the Finish button at the bottom of the popup window.

It may take a few minutes to index the project the first time you open it. This process will enable many useful features like API autocompletion.

Configuring Eclipse for PHP development

Perspective

If you see something other than PHP for the perspective in the top right, open the Window menu, select Open Perspective->Other... and double-click PHP.

*.tpl files

Our Smarty-based template files use the *.tpl file extension, which is not associated with the HTML editor in Eclipse by default.

  1. Open Eclipse's preferences.
  2. Expand General from the tree on the left and select Content Types.
  3. Expand Text on the right and select HTML. Click the Add button below, enter *.tpl and click the OK button.
  4. Click the OK button at the bottom of the popup window.

Validation

HTML

By default, Eclipse PDT will output several HTML validation warnings. To suppress these:

  1. Open up Eclipse's Properties.
  2. Select Validation from the tree on the left of the popup.
  3. Click the "..." button to the right of _HTML Syntax Validator`.
    1. Click the Add Exclude Group button to the right of the popup.
    2. Highlight Exclude Group on the left and click the Add Rule... button.
    3. Select File Extension and click the Next button.
    4. Enter the extension tpl and click the Finish button.
    5. Click the OK button.
  4. Click the "..." button to the right of _HTML Syntax Validator (for PHP Files)`.
    1. Click the Add Exclude Group button to the right of the popup.
    2. Highlight Exclude Group on the left and click the Add Rule... button.
    3. Select Folder or File Name and click the Next button.
    4. Enter the filename devblocks-dao.php and click the Finish button.
    5. Click the OK button.
  5. Click the OK button at the bottom of the popup and let Eclipse refresh validation.

XML

There will also be a few XML validation errors from cerb5_lang_*.xml translation files due to missing schemas. To suppress these:

  1. Open Eclipse's preferences.
  2. Expand XML->XML Files in the tree on the left and select Validation.
  3. On the No grammar specified option change Warning to Ignore.
  4. Click the OK button and let Eclipse refresh validation.

Properties ID: 000066   Views: 8751   Updated: 2 years ago
Filed under: