PT Commons

h1. Development environment

h2. Goals

One Drupal installation can support many separate sites through Drupal's multi-site functionality. We want you to use this multi-site set up because it imposes some constraints on your development environment that will ensure that your work will migrate to other environments without a hitch.

Developing in a multi-site environment immediately shakes out a common class of problems related to paths and URLs. If the site you're developing is hosted in sites/mysite but in other environments it's hosted in sites/myhost.com, you'll have to use url() and drupal_get_path() functions to reliably load PHP include files or theme assets across all of your environments.

Drupal-specific deployment systems (AEgir) rely on sites' ability to deploy into a multi-site environment.

Finally, the development environment you build will be one that suits your skills and needs. There are minimums you need to accomplish, but we will indicate when you can stop if you're satisfied for now. If you want to build a more sophisticated, complex and automated development environment, keep following along.

h3. Hacking core

Relying on a multisite-oriented environment enforces another good Drupal developer practice: don't hack core. If your Drupal projects share a common Drupal core, any core hacks you make will also be shared by all of these other projects. If a core hack is good enough for multiple sites, it's good enough to submit as a patch to core!

At the same time, it's justified to make some patches to core just for your development environment. For example, see the section about Xdebug.

Even though Devel module will override core's minified version of jQuery with an uncompressed copy, serious jQuery debugging will require that all of your scripts be uncompressed, which means you will need to replace jQuery UI with an uncompressed version.

Multisite : Each Drupal platform (core and any install profiles) will support

Uniformity : We explain how to set up a development environment which is uniform regardless of your preferred operating system. Only installation and upgrades are different depending on your operating system. Configuration and usage are consistent regardless of whether you use Windows, Mac OS X or Linux.

Maintenance : The development environment will be set up so that all of your web development projects are stored in the same part of your file system: a directory named workspace.

TODO: Create a directory inside your home directory named “workspace”

h3. Credit

This development environment is directly inspired by the “sandbox” design used by CivicActions. This was developed by Owen Barton, Fen Labalme and the staff of OpenWall. The same principles for organizing the development environment are used for easily deploying sites in staging, testing and production environments by CivicActions.

Drubuntu also inherits from this design, and it's highly recommended for users who are already using Ubuntu 10.10.

You need to create a LAMP stack on your computer. LAMP is an acronym for Linux, Apache HTTP Server, MySQL and Perl/PHP/Python. Most Drupal sites are deployed on this software.

Drupal can run in other server environments and other platforms. Obviously, we are not going to insist that you switch your personal operating system to Linux just to develop Drupal sites, so Windows and Mac can be substituted for Linux. Solaris and FreeBSD are also suitable platforms for Drupal, but if you are developing sites in this environment, you will need to translate the Linux instructions using your own know-how. On Windows, IIS is supported, but it's not recommended. Drupal 7 supports MySQL, PostgreSQL and SQLite, but most Drupal sites use MySQL and there's a tremendous amount of documentation, GUI client software and support for MySQL. We're going to omit Perl and Python, because Drupal only needs PHP. You will still be able to install Perl or Python if you need it.

h2. Platform specific

The main differences about configuring your development environment are the location of configuration files and the default settings in those configuration files. Use the table to identify the configuration files you may need to edit. If your files are located in another spot, note this because you'll need this information in the future.

| | MAMP | Homebrew | Windows | Ubuntu Linux |

| http.conf | /Applications/MAMP/conf/apache/httpd.conf | /private/etc/apache2/httpd.conf | | /etc/apache2/httpd.conf |

| my.cnf | /Applications/MAMP/db/mysql/my.cnf | /usr/local/var/mysql | | /var/lib/db/mysql |

| php.ini | /Applications/MAMP/conf/php5.3/php.inii | /opt/local/etc/php5/php.ini | | /etc/php5/conf.d/php.ini |

Some of us use version control to track changes and maintain a backup history for our configuration files

h3. Windows

For Windows, we will use WampServer. http://www.wampserver.com/en/

WampServer 2.1 meets all the requirements for Drupal 7. For earlier versions of Drupal, you will need to also download an older version of PHP to install.

http://en.wikipedia.org/wiki/Comparison_of_WAMPs

WAMP's default httpd.conf needs to have mod rewrite enabled.

Wrap paths in quotation marks.

WAMP already loads configuration files from an aliases directory, so instead of including the file in httpd.conf, copy it to the directory named in the include.

Vhost_alias_module needed.

h3. Mac

For Mac, there are two strategies for maintaining a Drupal development environment with their own strengths and weaknesses. Mac OS X could support Drupal on a the default system distributed by Apple Inc. It has Apache HTTPD Server and PHP already installed, and each user has a home directory named “Sites” which is Apache's user home directory. However, it does not have MySQL.

The Macintosh software community has provided two kinds of LAMP stacks: binary application packages and package managers. MAMP is an application package, which you download and install by copying. It is by far the quickest and easiest way to set up a development environment. However, it requires configuration after it has been installed. When you upgrade MAMP, you will need to remember to revisit these instructions so that your development environment does not break.

The alternative and more complicated method relies on a package manager. All package managers require that you install the Mac OS X Developer Tools. These developer tools are distributed on Mac OS X Install DVDs and also downloadable from http://developer.apple.com. We encourage you to customize the installation so that you can exclude documentation or extras you don't want, because the developer tools are very large. The documentation does include UNIX manual pages and Apple Developer documentation for Safari and Mobile Safari and a useful amount of web standards documentation. Likewise, XCode could be an IDE for your Drupal sites, but it's missing some simple features available in free and better tools.

As you improve in your web development skills in Drupal, you will confront the need to compile any number of new tools or servers for your environment. People in the Drupal community use more than just Drupal, and we will introduce you to new things like Compass, Solr, Memcached, Cucumber or a PECL add-ons. We urge you to use a package manager for these other tools because otherwise you risk destroying or disabling your development environment whenever you upgrade Mac OS X. Not every piece of useful web development software is distributed as a compiled binary for Mac OS X.

h4. MAMP

MAMP from http://www.mamp.info/ is an application that you will copy into your Applications folder. Although it is running system services, it's attaching them to high-number, non-standard ports. MAMP's preferences are user specific, but MAMP may not run correctly if multiple users on the same computer want to use MAMP. It can run concurrently with Mac OS X's own Apache server (the “Web server” controlled by the Sharing preference pane), though you hopefully do not need to run both at the same time. !MAMP.png(MAMP.png)!

After copying MAMP to your Applications folder, run it. You will be greeted by the MAMP application window and the MAMP start page in your default web browser as served by MAMP. The start page for MAMP gives you access to phpMyAdmin, various PHP info pages and some documentation. It also shows the default MYSQL credentials.

MAMP runs as the logged in user, and any files it creates (MySQL database files, log files, files uploaded through your Drupal development sites, Imagecache generated files) will be owned by the logged in users. This makes backup very simple and reliable, but it could lead to problems if two users on the same computer want to use MAMP for their own projects.

The MAMP application window allows you to turn on and off the servers, open the start page, and set preferences. By default, MAMP will start and stop all of its services whenever the MAMP application is opened or closed. We like these preferences for MAMP. MAMP currently is distributed with PHP 5.2 and 5.3, and you may need to switch between these PHP versions if you're supporting Drupal 6 or other PHP applications. For Drupal 7, all of MAMP's default settings are appropriate.

h4. Homebrew

Homebrew is a Mac OS X package manager that compiles from source and leverages software already installed as part of Mac OS X. Apache HTTPD Server and PHP 5.3 are already installed on Mac OS X Snow Leopard. Mac OS X Leopard uses PHP 5.2, which is also supported in Drupal 7. The only piece missing is MySQL.

You must install the Mac OS X Developer Tools before attempting to set up a development environment with Homebrew. If you are already suing MacPorts or Fink, you should avoid running both Homebrew and another package manager.

Install Homebrew from http://mxcl.github.com/homebrew/

In the terminal, run “brew install mysql.”

h3. Ubuntu Linux

Users of Ubuntu Linux are fortunate to have access to a high-quality LAMP from within their package manager (usually Synaptic). Using the package manager, install these packages and their dependencies:

* Apache2

** apache2

** apache2-mpm-prefork

* MySQL

** mysql-server

* PHP

** curl

** libapache2-mod-php5

** php5-cli

** php5-common

** php5-curl

** php5-dev

** php5-gd

** php5-mcrypt

** php5-mysql

** php5-sqlite

** php5-xdebug

** php5-xsl

** php-apc

** php-pear

<pre>

apt-get install apache2 apache2-mpm-prefork mysql-server curl

libapache2-mod-php5 php5-cli php5-common php5-curl php5-dev php5-mcrypt

php5-mysql php5-sqlite php5-xdebug php5-xsl php-apc php-pear

</pre>

h2. Apache

Drupal prefers Apache HTTPD Server. Core Drupal features like clean URLs are usually supported with no additional configuration.

Because Apache sometimes runs as a system user (usually www, www-data, apache or httpd), you may need to edit a few configuration files as the superuser or Administrator.

For your environment, Apache virtual host configurations will define at least one Drupal platform in which individual sites will be developed. A Drupal platform is the set of files that constitute Drupal core, any installation profiles, and any shared modules, themes or libraries located in sites/all.

In your workspace, create a new directory named conf.d.

In this directory, create these files. These configuration files define virtual hosts for each Drupal platform in your workspace.

"https://github.com/bangpound/webdev-workspace/blob/master/workspace/conf.d/000-default.conf":https://github.com/bangpound/webdev-workspace/blob/master/workspace/conf.d/000-default.conf

This sets up some blanket options that apply to every project in your workspace, so that essential URL rewriting and access permissions are set correctly.

"https://github.com/bangpound/webdev-workspace/blob/master/workspace/conf.d/drupal-7.conf":https://github.com/bangpound/webdev-workspace/blob/master/workspace/conf.d/drupal-7.conf

This tells Apache about Drupal 7. When you access your development environment's sites through your web browser, you will be navigating a URL that only your computer can access, for example http://new-site.7/. This configuration file tells Apache that any request it receives for a URL where the host name ends with .7, it should serve files from your Drupal 7 site directory.

"https://github.com/bangpound/webdev-workspace/blob/master/workspace/conf.d/localhost.conf":https://github.com/bangpound/webdev-workspace/blob/master/workspace/conf.d/localhost.conf

This file gives you some flexibility to break out of the rigid structure of this development environment. If you need to engineer on new Drupal platform or maintain a site that for whatever reason does not function in a multisite environment, you can add that project to your workspace. For example, if you want to set up Tattler http://tattlerapp.com/, you can put its directory in your workspace as tattlerapp, and it will be accessed as http://tattlerapp.localhost/.

Typical, current Apache HTTPD installations use a modular configuration file arrangement. This allows us to modify httpd.conf as little as possible, because this may be rewritten in a software upgrade. In your Apache configuration directory /etc/apache2, there is httpd.conf and an extra directory.

In your Apache's httpd.conf, add the following:

bc. #

# Include workspace configurations

#

Include /PATH/TO/extra/webdev-workspace.conf

Then create the webdev-workspace.conf file in your extra directory. This simply loads the configuration files from your workspace.

<pre>

#

# Include workspace configurations

#

Include /PATH/TO/YOUR/workspace/conf.d/*.conf

</pre>

h2. Hosts

The hosts file exists on every operating system http://en.wikipedia.org/wiki/Hosts_(file), and it's usually the last place your computer looks to resolve a domain name. The hosts file is what gives your system the name “localhost,” and it's very important that you never remove entries from the file that you didn't put there yourself.

Each project in your development environment needs to be accessible at the root of a unique host name, because this is how your project will likely be deployed. If your project will be deployed in a subdirectory of a larger site or in a user's home directory, you will want to recreate this too so you can catch any path name errors.

Edit /etc/hosts

Add a block comment to indicate where your changes begin and add the first hostname.

bc. #

# Webdev-workspace project

#

127.0.0.1   d7

h2. PHP

Usually when PHP is installed, it's set up for a development environment. Certain settings are unsuitable for a production environment, so you should make sure you have the right php.ini file installed.

Often, two configuration files come with PHP. php.ini-dist contains settings appropriate for your development environment. php.ini-recommended contains a few changes that hide error messages. The files have only a handful of differences to address the security and performance requirements of development and production environments.

Your development environment exists to show you how bad your work might be, and this is a better plan than letting your production environment show everyone in the world how bad your code actually is!

Verify that your php.ini file is configured with these settings:

bc. display_errors = On

PHP has a customizable error system, which Drupal 7 takes advantage of, which allows applications to handle non-fatal errors themselves and to change settings that affect output and thresholds.

Prior to Drupal 7, release versions of Drupal would not display PHP notice errors (E_NOTICE) and you either had to hack core or use a development release to display these error messages. Notices are useful because they reveal simple but hard to spot mistakes such as using variables that you've not assigned or using ambiguous syntax. http://drupal.org/node/34341

Error reporting may be annoying when the error has no apparent impact on the site's functionality, but notices often appear because of mistakes that are not going to cause fatal errors but which lead to buggy behavior.

h2. MySQL

MySQL really has no special problems for setting up. Recommendations are to install from a package or build from source using a package manager.

Editing your server's my.conf file to enable "innodb_file_per_table":http://dev.mysql.com/doc/refman/5.0/en/innodb-multiple-tablespaces.html to make the InnoDB files smaller and fragmented, which is friendlier to a development environment.