Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.

UncleCheese
28th November 2014

In this introductory lesson, we cover installing a local webserver (e.g. MAMP), installing and using Composer, and configuring an _ss_environment.php file. Having a finely tuned local environment for your projects will help you work faster and with less redundancy.

Up and Running: Setting up a local SilverStripe dev environment

Level: Beginner

Duration: 14:08

In this lesson:

Installing a local web server

SilverStripe is a PHP-based application that connects to a database, so in order to run it, you'll need a webserver. You won't want to be doing all of your development on a remote environment, so setting up a local webserver is highly recommended. If you're running OSX or Linux, you probably have all the tools you need already installed on your system, but if you're just starting out, you might find it easier to get a pre-configured package that just gets everything going for you in a single click.

There are a few local webservers out there to choose from. If you're using a Mac, you probably want MAMP. Windows users may prefer WAMP. Both of these tools are free. Just for clarity, the AMP in both of these acronyms stands for Apache, MySQL, PHP, in case you didn't know what you were getting into.

This tutorial will focus on using MAMP, but be aware that all of these bundled web servers operate and install very similarly.

On the MAMP web page, just click the Download link and install it. They'll try to talk you into the pro version, which comes at a cost. If you're just starting out, the free version will serve you just fine.

MAMP installs to our Applications folder, not as an application, but rather as another folder. If we take a peek inside, we'll find all the modules, libraries, and configuration files that create the server we'll be running. We just click on the MAMP package, and it pulls up a panel.

Notice in the upper right corner that the Apache server and MySQL server are off. We can turn these on simply by clicking Start servers.

When the servers turn on MAMP lets us know that it was successful by rendering a web page in the browser. Take a close note of the host name for this web page, http://localhost:8888. This is where all of your projects will run when using MAMP.

MAMP is fairly configurable. The Pro version is more so. You can see that we can tweak things, like the port that runs our sites and the version of PHP. Most importantly, take note of the document root that MAMP is using. By default it runs in the Applications/MAMP/htdocs folder. This is where all the sites are going to run.

So let's just jump into that folder in the terminal and see if we can create a working PHP file. I'll make a script that renders some text to the browser.

/Applications/MAMP/htdocs/test.php

die('hello, world');

If we go to http://localhost:8888/test.php, you'll see that it is executing the script properly, and we now have a working local web server.

Introducing Composer

Before we get into installing Composer, we should probably go over what exactly Composer is and how it works.

What is Composer, and why do I need it?

Composer is a package manager for PHP. Package managers are increasingly popular these days, especially for front-end libraries. You may have heard of NPM or Bower. At their most fundamental level, package managers are simply abstractions of a source code repository. They obscure all the minute details about where the projects live and what branches are available, and they allow you to simply refer to packages semantically by name and by version number.

A key feature of Composer is that it resolves dependencies. When one module requires one or more other modules in order to work properly, Composer will sort all that out and pull down everything you need. Further, Composer applies version constraints. So if a package requires a module that doesn't work with something you already have installed, it will apprise you of that conflict and halt the installation so that your project doesn't break.

You might be wondering, "Why can't I just go and download the modules and install them manually?" Well, let's use an example SilverStripe project without Composer to illustrate why that isn't always a good choice.

Let's say you want to get a gallery module for your website. You go out to some web page, download it, and drop it into your project. When you try to run the application, the module complains that it's missing the slideshow module, which is integral to the gallery module.

Now your project is hosed. You go and find the slideshow module. After some digging, you're able to track it down. You drop it in, hoping this will make your gallery module happy.

Now we have a new problem. The slideshow module is incompatible with the version of SilverStripe that we're running. You can see where this is going. All the players in your project don't get along, and your website blows up.

Installing packages with Composer solves all these issues because you simply execute a nice, declarative command, asking to install a package and a specific version, and it handles all the orchestration for you.

composer require example/some-module

This is by no means a magic bullet. You will still have to resolve conflicts, but it will tell you what those conflicts are, and it won't let your project exist in a state with incompatibilities.

Installing Composer

Installing Composer is just a matter of running two commands:

$ curl -s https://getcomposer.org/installer | php
$ sudo mv composer.phar /usr/local/bin/composer

These commands might look a little foreign to you if you're new to the terminal. If you need more information, SilverStripe documentation about Composer.

Let's run the first command, which installs Composer. It doesn't matter where in the file system we run this command.

The second command will move the Composer executable to a place where it's globally accessible, so we can just run Composer anywhere.

Creating a SilverStripe project

Let's create a SilverStripe project using Composer. Because this is a new project, we'll use the create-project command and point Composer at the silverstripe/installer. We'll specify a project name of example.

$ composer create-project silverstripe/installer example

Composer will now go out and read the SilverStripe installer package. Then, it's going to pull down all the dependencies, including SilverStripe Framework, and the CMS on top of that. Lastly, it's going to install the default theme that comes with the SilverStripe installer.

Now, if we go to the URL http://localhost:8888/example, we see an install page. It's full of red errors that are telling us that the install isn't going to work, so let's go through this and see if we can sort it out.

Configuring the installer

One thing that it's complaining about is that there isn't enough information to connect to the database. So let's fill out the database username and password. If you're using MAMP, the default user for MySQL is username root with password root.

Let's just change the database name to something a little bit more meaningful. We'll call it SS_example, because this is the project example.

Lastly, we can create an admin account. Let's specify a password. That'll be the account we use to connect to the CMS. We'll recheck the requirements and install SilverStripe.

Now that the installation is complete, SilverStripe is going to prompt you to delete the install files, as they are a security risk. Click on that, and it will authenticate you before moving forward. Provide that admin password you chose earlier.

Refining your development environment

Now that we've installed SilverStripe, let's finely tune our development environment so we can get things working a little bit faster.

_ss_environment.php

The main ingredient in environment management in SilverStripe is the _ss_environment.php file. This file provides a shared configuration across all your projects. It should contain information such as database credentials, as those are most likely to be shared across all your projects.

It can also include other application settings. You might have API keys or email addresses in there that you want to specify as globally accessible by all projects.

Because _ss_environment.php is an executable PHP file, it can follow logic. So you can actually create a dynamic configuration by looking at something like the HTTP host that's coming in or the remote IP, and make decisions on the fly about how you want to configure the project.

Most importantly, the _ss_environment.php file does not have to ship with the project. It can live outside the web root, outside of source control. When you deploy this project from your local environment to somewhere else, that remote environment might have its own configuration, so having the file outside the project means you don't have to worry about overriding settings.

How _ss_environment.php works

Let's take a look at an example directory structure, where we have an htdocs folder, and three example projects underneath it.

We'll put the _ss_environment.php file in htdocs. It will cascade its settings down to project A, B, and C.

You can place an SS environment file in, say project B, and it will override the parent _ss_environment.php file.

There is a way to merge the settings so that you get some from the project level, and others are inherited, but that requires some custom coding, and it's probably something for another tutorial.

Some common configurations

In a typical _ss_environment.php file, you definitely want to define the database server, database username and database password. Everything is defined in constants.

/Applications/MAMP/htdocs

define('SS_DATABASE_SERVER','localhost');
define('SS_DATABASE_USERNAME','root');
define('SS_DATABASE_PASSWORD','root');

Lastly, you'll probably want to define the SS environment type as dev, so you can take advantage of all the debugging tools and get some verbose errors.

/Applications/MAMP/htdocs

define('SS_DATABASE_SERVER','localhost');
define('SS_DATABASE_USERNAME','root');
define('SS_DATABASE_PASSWORD','root');
define('SS_ENVIRONMENT_TYPE','dev');

Let's create a second SilverStripe project. We'll call it example2.

$ composer create-project silverstripe/installer example2

So let's go to that example2 URL (http://localhost:8888/example2). The install page comes up again, but it looks slightly different.

Some of the fields have been populated for you, such as the database username and password, but you still have to provide a database name. Let's use SS_example2. Also, provide that admin password again.

Click "Install SilverStripe," and once again, clear out those install files.

Let's now take this a step further. There are some more things we want to throw into our _ss_environment.php file. We can use SS_DATABASE_CHOOSE_NAME to tell SilverStripe to intelligently determine a database name so that you don't have to. It will look at the filesystem, see where the project is installed, and choose a database name based on that.

Also, you can specify the default admin username and password. For local development, you're probably not too concerned about security. So having something easy to remember, like root/root, is just fine.

/Applications/MAMP/htdocs

define('SS_DATABASE_SERVER','localhost');
define('SS_DATABASE_USERNAME','root');
define('SS_DATABASE_PASSWORD','root');
define('SS_ENVIRONMENT_TYPE','dev');
define('SS_DATABASE_CHOOSE_NAME', true);
define('SS_DEFAULT_ADMIN_USERNAME','root');
define('SS_DEFAULT_ADMIN_PASSWORD','root');

Another setting you might want to turn on is SS_SEND_ALL_EMAILS_TO. If you provide your email address here it will force all emails to go to you, instead of to the places that your application might be sending them, which could include a client or anyone else who you don't want getting your tests. By applying this setting, it will force email to go to you, no matter what to address you've specified, so that's very useful in development mode.

For a full list of settings you can go to the docs and just look up environment management There are probably a dozen or so other settings you can throw in here. Some are more useful than others. Have a quick look through there because you might find something that's really useful to you.

Let's save the changes to _ss_environment.php, and apply those new settings.

When we go to the http://localhost:8888/example3 URL, you'll notice that we bypass the install page. That's because SilverStripe has learned everything it needed to know about this project from _ss_environment.php.

This is a really quick way is to light up a project and do some testing. You can just throw this project away when you're done and do it again, and you don't have to go through that install process every single time. _ss_environment.php comes in really useful here, as it applies all the settings you want for every single project.

We're now off and running with a local development environment for SilverStripe development.

Get started building your first SilverStripe website with our series of lessons.

Questions and Feedback

If you're hosting the SilverStripe site live, where do you put the _ss_environment.php file or would you specify these setting elsewhere? Thanks

by Dave at 08:01am, 29 August 2015

Author

Hi, Dave,

The _ss_environment.php file can be placed in the web root, or up to three directories above it. So if your project is in /var/www/myproject.com/public_html, a good place to put it might be /var/www. That way, if you ever have to override the settings for a specific project, you can put an override file in /var/www/customproject.com/.

by UncleCheese at 02:14pm, 6 October 2015

Hello,

I am stuck on installing the composer. I am trying to install on my Mac. When I try to move the composer.phar to /usr/local/bin/ it says there is no directory for the file to be moved to. I tried moving it manually but it still does not work. I also tried making a folder "composer" and moving the composer.phar and a renamed version just "composer" to the folder and just to /usr/local/bin/ but neither of those work.

I would greatly appreciate any help, I need to be able to install silverstripe for a school project.

by Angelo at 11:57pm, 2 October 2015

Author

Hi, Angelo,

Strange that your /usr/local/bin directory doesn't exist, but feel free to create it if you need to.

mkdir /usr/local/bin

by UncleCheese at 02:15pm, 6 October 2015

When doing example 2 and 3, I am still prompted in the same way as previously. I am given a checkbox called "Use _ss_environment.php for settings" or something along those lines, which is located just below the db part. This immediately grays out practically every field. Feeling confident and hitting install, I am dragged to the top of the screen, supposedly because the admin info is missing. However, following code lines:

define('SS_DEFAULT_ADMIN_USERNAME', 'admin'); define('SS_DEFAULT_ADMIN_PASSWORD', 'admin');

are put in _ss_environment.php, which is in the www folder (I'm running WAMP, Windows), alongside the projects. For some reason this does not seem to affect the installation though.

I also get some different errors/suggestions than in the video. Is the video possibly a bit outdated or am I missing something fundamental?

by Joel at 07:16am, 6 October 2015

Author

I think one thing that is missing from the tutorial is that "use _ss_environment for configuration" should be unchecked. I believe that option puts a _ss_environment.php file in your webroot, which would override the one in the parent directory.

by UncleCheese at 02:12pm, 6 October 2015

Hello UncleCheese, I think you are awesome, is there a tutorial for installing silverstripe on plesk?

P.S. Also want to ask one more question:

I wanted to add some fields into cms, when there are only two fields ("Five","Six") and others are deleted - everything is okay, they work. When I add more (+ "Seven","Eight") at first additional fields just didn't save. Now it drops and error:

Line 55 in /Applications/MAMP/htdocs/appleStore/framework/model/connect/DBConnector.php

my code:

Thank you very much! It means a lot to me.

class ProductPage extends Page { private static $db = array( 'Five' => 'Text', 'Six' => 'Text', 'Seven' => 'Text', 'Eight' => 'Text', ); public function getCMSFields() { $fields = parent::getCMSFields(); $fields->addFieldToTab('Root.Main', TextField::create('Five', 'iPhone 5'),'Content'); $fields->addFieldToTab('Root.Main', TextField::create('Six', 'iPhone 6'),'Content'); $fields->addFieldToTab('Root.Main', TextField::create('Seven', 'iPhone 7'),'Content'); $fields->addFieldToTab('Root.Main', TextField::create('Eight', 'iPhone 8'),'Content'); return $fields; } } class ProductPage_Controller extends Page_Controller { }

by Larry at 07:22pm, 26 October 2015

Figured out that have to flush everything in /admin/dev/?flush=1 directory in order to refresh my code. The tutorial of how to install SS on plesk would still help tho.

by Larry at 07:51pm, 26 October 2015

Hello, I followed all of the steps in the tutorial and I am trying to instal SilverStrip within MAMP. I get as far as starting the installation page. After making sure all requirements are correct and hitting instal, I get the following error;

[User Error] Uncaught Error: Function name must be a string GET /setup1/dev/build?returnURL=%2Fsetup1%2F Line 582 in /Users/jacobnolan/Google Drive/Portfolio site/cms/setup1/framework/model/connect/DBSchemaManager.php

It also highlights this line in the if stament starting on line 578

if (!is_string($spec)) { $spec['parts']['name'] = $field; $specorig['parts']['name'] = $field; //Convert the $spec array into a database-specific string $spec = $this->$spec['type']($spec['parts'], true);_ }

I have tried the instal on a live MySQL server as a test before and it installed just fine. I wanted to create the entire CMS locally before deploying it live. Any help you can provide me is much appreciated. Thank you.

by Jacob Nolan at 05:18pm, 8 March 2016

Newby here - I installed WAMP on Win10 but cannot install Composer as I'm unable to find where in WIn10 to type in the commands:

$ curl -s https://getcomposer.org/installer | php $ sudo mv composer.phar /usr/local/bin/composer

Where do I enter these commands? Maybe it's how do I set up Win10 for these commands?

Pls help!

by fusu at 05:15am, 5 July 2016

Thanks for the feedback Uncle Cheese, I actually was at this page before.

Composer is now installed, but command does not understand the $ sign. I now want to install ss.


C:\Users\mac>$ composer create-project silverstripe/installer example '$' is not recognized as an internal or external command, operable program or batch file.

C:\Users\mac>

by fusu at 11:59am, 5 July 2016

I got an error while I was trying to install SilverStripe in a local web server. ext-dom is missing, what's that and how do I install it.

To enable extensions, verify that they are enabled in those .ini files:

I am new to PHP, so I don't understand that and don't know how to fix that. Below is the complete error message.

$ composer create-project silverstripe/installer example Installing silverstripe/installer (3.4.1)

  • Installing silverstripe/installer (3.4.1) Loading from cache

Created project in example Loading composer repositories with package information Updating dependencies (including require-dev) Your requirements could not be resolved to an installable set of packages.

Problem 1

  • phpunit/phpunit 3.7.9 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.8 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.7 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.6 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.5 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.4 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.38 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.37 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.36 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.35 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.34 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.33 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.32 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.31 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.30 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.3 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.29 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.28 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.27 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.26 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.25 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.24 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.23 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.22 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.21 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.20 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.2 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.19 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.18 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.17 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.16 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.15 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.14 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.13 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.12 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.11 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.10 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.1 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • phpunit/phpunit 3.7.0 requires ext-dom * -> the requested PHP extension dom is missing from your system.
  • Installation request for phpunit/phpunit [email protected] -> satisfiable by phpunit/phpunit[3.7.0, 3.7.1, 3.7.10, 3.7.11, 3.7.12, 3.7.13, 3.7.14, 3.7.15, 3.7.16, 3.7.17, 3.7.18, 3.7.19, 3.7.2, 3.7.20, 3.7.21, 3.7.22, 3.7.23, 3.7.24, 3.7.25, 3.7.26, 3.7.27, 3.7.28, 3.7.29, 3.7.3, 3.7.30, 3.7.31, 3.7.32, 3.7.33, 3.7.34, 3.7.35, 3.7.36, 3.7.37, 3.7.38, 3.7.4, 3.7.5, 3.7.6, 3.7.7, 3.7.8, 3.7.9].

    To enable extensions, verify that they are enabled in those .ini files:

  • /etc/php/5.6/cli/php.ini
  • /etc/php/5.6/cli/conf.d/10-opcache.ini
  • /etc/php/5.6/cli/conf.d/10-pdo.ini
  • /etc/php/5.6/cli/conf.d/20-calendar.ini
  • /etc/php/5.6/cli/conf.d/20-ctype.ini
  • /etc/php/5.6/cli/conf.d/20-exif.ini
  • /etc/php/5.6/cli/conf.d/20-fileinfo.ini
  • /etc/php/5.6/cli/conf.d/20-ftp.ini
  • /etc/php/5.6/cli/conf.d/20-gettext.ini
  • /etc/php/5.6/cli/conf.d/20-iconv.ini
  • /etc/php/5.6/cli/conf.d/20-json.ini
  • /etc/php/5.6/cli/conf.d/20-phar.ini
  • /etc/php/5.6/cli/conf.d/20-posix.ini
  • /etc/php/5.6/cli/conf.d/20-readline.ini
  • /etc/php/5.6/cli/conf.d/20-shmop.ini
  • /etc/php/5.6/cli/conf.d/20-sockets.ini
  • /etc/php/5.6/cli/conf.d/20-sysvmsg.ini
  • /etc/php/5.6/cli/conf.d/20-sysvsem.ini
  • /etc/php/5.6/cli/conf.d/20-sysvshm.ini
  • /etc/php/5.6/cli/conf.d/20-tokenizer.ini You can also run php --ini inside terminal to see which files are used by PHP in CLI mode.

by Jorge at 08:21am, 21 September 2016

Hello UncleCheese,

I've installed SilverStripe on my web host space and though the admin succeeded to clear compatibility issues from the server end, I still have this poppin up. Thank you for guidance to solve it... can't wait:

[Warning] is_readable(): open_basedir restriction in effect. File(/usr/local/php/inst/php-5.5.17/pear/php//Zend/Translate/Adapter/I18nRailsYamlAdapter.php) is not within the allowed path(s): (/home/vhosts/hituse.com/:/tmp/) GET /wcicOS/ Line 198 in /home/vhosts/hituse.com/wciccameroun.org/wcicOS/framework/thirdparty/Zend/Loader.php Source

189 190 foreach (self::explodeIncludePath() as $path) { 191 if ($path == '.') { 192 if (is_readable($filename)) { 193 return true; 194 } 195 continue; 196 } 197 $file = $path . '/' . $filename; 198 if (is_readable($file)) { 199 return true; 200 } 201 } 202 return false; 203 } 204

Trace is_readable(/usr/local/php/inst/php-5.5.17/pear/php//Zend/Translate/Adapter/I18nRailsYamlAdapter.php) Loader.php:198 Zend_Loader::isReadable(Zend/Translate/Adapter/I18nRailsYamlAdapter.php) Translate.php:126 Zend_Translate->setAdapter(Array) Translate.php:93 Zend_Translate->__construct(Array) i18n.php:2155 i18n::get_translators() i18n.php:2062 i18n::_t(SecurityAdmin.NEWGROUP,New Group,,) Core.php:172 _t(SecurityAdmin.NEWGROUP,New Group) Group.php:54 Group->populateDefaults() DataObject.php:497 DataObject->__construct() ReflectionClass->newInstance() InjectionCreator.php:20 InjectionCreator->create(Group,Array) Injector.php:555 Injector->instantiate(Array,Group) Injector.php:861 Injector->get(Group) Core.php:160 singleton(Group) Security.php:1010 Security::database_is_ready() Controller.php:80 Controller->init() RootURLController.php:119 RootURLController->handleRequest(SS_HTTPRequest,DataModel) Director.php:385 Director::handleRequest(SS_HTTPRequest,Session,DataModel) Director.php:149 Director::direct(/,DataModel) main.php:188

by Roland Y. at 06:05pm, 28 September 2016

Stuck on something? Have something to share? Don't be shy!