Installing the Stratos Framework

Download the Framework

To install Stratos, you must first get a copy of the source code. There are two ways to get the source code. You can either download the tarball or check it out from the Subversion repository.

Method 1: Downloading the Tarball

If you downloaded the tarball, you must first unpack it to a directory on your server. I own the domain liteware.org, so I uploaded the Stratos tarball to my server and unpacked it like so:

larry@liteware.org:~$ tar xzvf stratos-xx.tar.gz

Since I like the directory to just be called stratos, I usually change it:

larry@liteware.org:~$ mv stratos-xx stratos

Method 2: Checking out the source code from the Subversion repository

The Stratos source code can be checked out from Subversion using the following command:

svn co https://stratos-php.svn.sourceforge.net/svnroot/stratos-php/trunk stratos

If you don't know what Subversion is, more details on the tool and its use can be found at the Stratos Subversion page on SourceForge.

Developing Your First Stratos Application

If you have done everything correctly, you should now have a directory containing all of the Stratos source code. Now you can start developing your application. There are two ways to start creating a new Stratos application. You can either put your code directly in the controllers/ and views/ directories where you installed Stratos, or you can develop your application in a separate directory and set an environment variable to tell the application where Stratos is installed. The first method is easier because you can simply upload the entire Stratos Framework code to a web accessible directory and begin coding. The second method is beneficial because you can have the Stratos Framework installed in one location, and have many applications share a single copy of the framework.

Method 1: Developing in the same directory as your Stratos Installation

If you will be developing your application in the same directory where you installed Stratos, you can simply copy the entire framework directory to a new directory that is accessible from the web. To develop a Hello World application, you can simply create a directory in the public_html directory on your server and copy the contents of the Stratos installation to that directory like so:

larry@liteware.org:~/public_html$ cp -r ~/stratos/ HelloWorldApp
larry@liteware.org:~/public_html/HelloWorldApp$ cd HelloWorldApp
larry@liteware.org:~/public_html/HelloWorldApp$ ls -a1p
./
../
cache/
conf/
controllers/
.htaccess
includes/
index.php
models/
plugins/
stratos/
Stratos-LICENSE.txt
stratos-skel/
views/
larry@liteware.org:~/public_html/HelloWorldApp$

Once this is done, you can start creating scripts in the controllers/ and views/ directory, and that's it. I will show you how to start creating controllers and views very soon.

Method 2: Use the "Skeleton" Application and set STRATOS_HOME

The stratos-skel directory contains a "skeleton" Stratos application. One way to start a new Stratos application is to simply copy the contents of this directory to the location where you want to begin development. To demonstrate this, we will create a simple Hello World application. First, copy the contents of stratos-skel to a new web accessible directory:

larry@liteware.org:~/public_html$ cp -r ~/stratos/stratos-skel/ HelloWorldApp
larry@liteware.org:~/public_html$ cd HelloWorldApp
larry@liteware.org:~/public_html/HelloWorldApp$ ls -a1p
./
../
cache/
conf/
controllers/
.htaccess
includes/
index.php
models/
stratos/
views/
larry@liteware.org:~/public_html/HelloWorldApp$

The last step is to tell the application where you installed Stratos by setting the STRATOS_HOME environment variable. This can be done a number of different ways, but let's look at a couple that work on any system.

One option is to edit the index.php file in your application and use PHP's putenv() function. If you are running PHP as a CGI with suExec, this may be your only option. Locate the following lines in your index.php:

<?php

// Add the path to the global Stratos root, if it is present in the STRATOS_HOME
// environment variable
// Note: If you are running suExec, you will probably need to uncomment the
// following line
//putenv('STRATOS_HOME=/path/to/stratos');

?>

Uncomment the putenv() line and point STRATOS_HOME to the location where you installed the Stratos Framework:

<?php

// Add the path to the global Stratos root, if it is present in the STRATOS_HOME
// environment variable
// Note: If you are running suExec, you will probably need to uncomment the
// following line
putenv('STRATOS_HOME=/path/to/stratos');

?>

If you are running PHP as an Apache module, you can set STRATOS_HOME in your .htaccess file, like so:

SetEnv STRATOS_HOME /path/to/stratos

System-wide options, such as adding a system variable on Windows, will also work.

Now that your application knows where to find the framework, simply point your web browser to the application at http://www.yourdomain.com/HelloWorldApp. If all went well, then you should be prompted for a username and password. By default, these are both admin. After logging in, you will see the Stratos Control Panel:

Stratos Control Panel

Piece of cake, right? Now let's create a controller and a view. In the HelloWorld/controllers directory, create a new script called HelloWorldController.php. Enter in the following code:

HelloWorld/controllers/HelloWorldController.php

Error: Macro Include(source:trunk/examples/HelloWorld/controllers/HelloWorldController.php) failed

Unsupported version control system "svn". Check that the Python bindings for "svn" are correctly installed.

In the views/ directory of your application, create a script named HelloWorldController.index.php, and put in some simple HTML along with the variable $message:

HelloWorld/views/HelloWorldController.index.php

Error: Macro Include(source:trunk/examples/HelloWorld/views/HelloWorldController.index.php) failed

Unsupported version control system "svn". Check that the Python bindings for "svn" are correctly installed.

That's all there is to it. Now you simply point your web browser to the URL that maps to the controller:

http://www.yourdomain.com/HelloWorld/index.php/HelloWorld

Of course, you should adjust the domain and URL to point to wherever you developed your application. When you load the page you should see "Hello World!". That's all there is to it!

Learn More

Since this is only an installation tutorial, I didn't explain much about how controllers and views work, or how you would access a database. For a more thorough tutorial, I suggest reading the tutorial on Creating a Message Board with the Stratos PHP Framework.