10 min read

 

SilverStripe 2.4 Module Extension, Themes, and Widgets: Beginner’s Guide

SilverStripe 2.4 Module Extension, Themes, and Widgets: Beginner's Guide

Create smashing SilverStripe applications by extending modules, creating themes, and adding widgets

        Read more about this book      

(For more resources on SilverStripe, see here.)

Setting up the environment

There are many possible scenarios and environments you might require, depending on the complexity of your project. However, we’ll keep this short and simple:

  • We’ll set up a development environment, which is based on Windows (Windows XP or newer) as it is the most common operating system on desktops and laptops.
  • We’ll also set up one live or deployment environment, which is based on Linux as it is the most common operating system for web servers. We’ll use Ubuntu in our example as it is freely available and widely used. If you prefer a different distribution some paths and commands will vary, but the general approach should be very similar.
  • In case you want to use a testing or staging environment as well, we’ll assume that you simply reuse the previous setup—so we don’t need to configure another system.

Now that we’ve decided on the general purpose of the systems and their operating systems, we’ll need to choose between different implementations for setting up the web server and database. Specifically, whether to use prebuilt packages or select the components ourselves.

To demonstrate both approaches we’ll use a prebuilt package on our development machine (as we want to get up and running quickly) and handpick the components on our live site, where we want to have maximum control. To keep our development and live environments closely related, we’ll use the same applications for both—disqualifying Windows-only solutions:

On Windows there’s also Microsoft’s Web Platform Installer (http://www.microsoft.com/web/downloads/platform.aspx). It doesn’t only include the web server, database and PHP, but also SilverStripe itself (http://www.microsoft.com/web/gallery/silverstripecms.aspx)—which can be downloaded on demand among many other web applications. However, as this is very different to our live site, we won’t cover it. If you’re looking for a, Windows-only solution this is nevertheless an interesting option as it is very easy to set up.

The Windows development system

Let’s start off by setting up our development system, based on the freely available XAMPP package.

Time for action – installing XAMPP

We’ll assume that the operating system is Windows XP or newer—for Linux, Mac OS X, and Solaris you should only need to get a different download file and do some minor variations of the steps described:

  1. Download the XAMPP package at http://www.apachefriends.org/en/xampp-windows.html. We’re using the 7zip package as it doesn’t require an installation, is compact to download and also portable: you can copy it to a USB drive and use the environment on any Windows computer.
  2. Extract the archive to a top-level folder on your internal drive (C: for example), or your portable external drive (U: for example). To do this, you’ll need the free 7zip archive utility, which you can download at http://www.7-zip.org.
  3. Open up the file xampp/mysql/bin/my.ini and add the following line in the [mysqld] section:

    lower_case_table_names=2

    This setting is important for exchanging database dumps between Windows and Linux systems. As Windows paths are case insensitive, MySQL lowercases database and table names by default (as they are internally stored as folders and files), but only on Windows. On Linux proper cases are preserved, which leads to problems when using dumps on different platforms. The previous statement forces MySQL on Windows to behave like on Linux.

  4. Inside the XAMPP folder, start the file xampp-control.exe and use it to Start Apache, MySql and Mercury. XAMPP’s control panel should look like this after starting the three applications:

    Installation of SilverStripe 2.4

  5. If a service doesn’t start, check that its port is not already in use—this is the main reason for problems. To do this, open the command line tool and enter netstat-ao. This will show you the ports currently in use and the process IDs (PIDs) of the processes using them. Using Window’s Task-Manager you can then find out the name of the process causing the problem, and stop or reconfigure it. The following screenshot illustrates this scenario—the web server cannot be started as Skype is already using port 80:

  6. After successfully starting all three services, navigate to http://localhost in your browser. This should redirect you to XAMPP’s welcome page.

  7. In case you need to send e-mails for testing purposes, you’ll need to perform two additional steps to configure your SMTP server:
    • Enable SMTP relaying of non-local mail. However, ensure that no one can access your mail server from outside or you might be abused as a spam relay (your router or firewall will protect you). In XAMPP’s control panel, click on Admin… next to the Mercury label. Next go to Configuration, MercuryS SMTP Server and on the Connection control tab uncheck Do not permit SMTP relaying of non-local mail.
    • Provide a DNS server so domain names can be looked up: Under Configuration, MercuryE SMTP Client fill in the field Name server with your provider’s DNS server.
  8. That’s it for our general purpose development machine. In case you want to run automatic tests or generate translation files, you’ll also need to install PHPUnit through PEAR:
    • While XAMPP includes PEAR and PHPUnit, the bundled versions are hopelessly outdated. Furthermore the update process doesn’t work reliably, so we’ll better start anew.
    • First remove xampp/php/PEAR/, xampp/php/pear.bat, xampp/php/pear.ini, xampp/php/peardev.bat and xampp/php/pear-update.bat.
    • Next enable PHP’s cURL extension: Open xampp/php/php.ini, find the line ;extension=php_curl.dll and remove the leading semicolon.
    • Then download http://pear.php.net/go-pear.phar into xampp/php/.
    • Next install PEAR on the command line (start it as an admin user). Note that you must be in the folder xampp/php/ for the following commands to work:

      php go-pear.phar

    • Now we can use PEAR to update its channels and upgrade all packages:

      pear update-channels

      pear upgrade --alldeps

    • Finally you can install PHPUnit and all of its dependencies:

      pear channel-discover pear.phpunit.de

      pear channel-discover components.ez.no

      pear channel-discover pear.symfony-project.com

      pear install phpunit/PHPUnit

    • That’s it, you’ve successfully installed PHPUnit!

The Linux live system

Next we’ll set up our live system. Thanks to package managers this isn’t much harder—you just shouldn’t be afraid of the shell.

Time for action – installing the requirements by hand

In our example we’re using Ubuntu, so we’ll rely on its package manager Apt, abbreviation of Advanced Package Tool. Note that we won’t only install the bare necessities, but also some more tools to make our system ready for production.

  1. Open the terminal and install the Apache HTTP Server together with PHP and PHP’s GD library (needed for image manipulation) through the following commands. Note that all required dependencies are added automatically, though you may need to manually accept them:

    sudo apt-get install apache2 php5 php5-gd

  2. Next we’ll install MySQL and its binding to PHP, again through the terminal. You’ll be prompted for a password, which we’ll need again later on.

    sudo apt-get install mysql-server php5-mysql

  3. Enable Apache’s rewrite module, which SilverStripe requires to use pretty URLs:

    sudo a2enmod rewrite

  4. Edit the file /etc/apache/sites-available/default and replace the line AllowOverride None with AllowOverride All inside the block. This enables the rewrite module inside the /var/www/ folder.
  5. Install Alternative PHP Cache (APC), which will accelerate PHP programs—SilverStripe benefits a lot from this. While there are some alternatives, it is currently planned that APC will be included in PHP 6, which makes it sound like a future-proof decision for our installation:

    sudo apt-get install php-apc

    If you want to see APC in action, you’ll need its management tool. By default it is located in the file /usr/share/doc/php-apc/apc.php.gz. Unpack and copy it to your web-root to see detailed statistics on how well it’s working for you, but protect it against unauthorized access (you can set credentials inside the file).

  6. Edit the file /etc/php5/apache2/php.ini, using whatever text-editor you prefer (this can be quite a sensitive topic with programmers). Replace the line ;date.timezone = with date.timezone = US/New_York or your current location. See http://php.net/manual/en/timezones.php for all possible values. Note that removing the semicolon at the beginning is important, otherwise the line will be considered a comment.
  7. Restart the web server to apply all the settings we’ve just made:

    sudo /etc/init.d/apache2 reload

  8. Now it’s time to test our installation. Go to the directory /var/www/ which is the default web-root directory:

    cd /var/www/

  9. It should already contain a file index.html, which you can view if you visit http://127.0.0.1 in your browser (or whichever IP address you can access your server under).
  10. However, this is only a static HTML file. To see if PHP is also working, first set the file permissions, assuming our current user is ubuntu (which we’ll use to edit files) and the web server is run as www-data (which is the default). So we’ll make our user the owner of the files with full permissions, and set the group to the one of the web server with read and execute permissions only:

    sudo chown ubuntu:www-data -R /var/www/

    sudo chmod 0755 -R /var/www/

    After adding new files, you’ll need to rerun these two commands.

  11. Next create a file index.php in /var/www/:

    touch index.php

  12. Add the following code to it:

    phpinfo();
    ?>

  13. In your browser load the page http://127.0.0.1/index.php (again use your specific IP address). The output should look something like this:

    Installation of SilverStripe 2.4

  14. This shows that PHP is working. Also check that you can find mod_rewrite and a full section on APC in the output to be sure they are enabled.
  15. That’s it, our live system is now ready for action. We haven’t installed PEAR as we’ll assume that testing and translating is done in the development environment, not on the live server.

We’ve also left out how to install and configure an SMTP server. Unfortunately this is pretty complicated and beyond the scope of this article—especially since you don’t want to become a spam relay. If your provider or distribution hasn’t already set this up for you, take a look at a specific SMTP server how-to and documentation—Postfix (http://www.postfix.org) is widely used for example.


Subscribe to the weekly Packt Hub newsletter

* indicates required

LEAVE A REPLY

Please enter your comment!
Please enter your name here