Big Bang with Solar – Part 1

September 25th, 2008 by Ray in Cookbook, Solar | Tags: Cookbook, Solar | No Comments

So you have read the manual and browsed the Solar wiki. Now you want to get your hands dirty with setting up your own project. Good news, you’ve found the right place. In this series, I plan to show you, step-by-step, how to set up your very own project using Solar.

To make sure we stay on track, here is the scope for part 1 of the series.

Download and Install Solar
Determine our project guidelines
Configure Apache using Virtual Hosts
Set up our bootstrap and configuration file
Create a “Hello World” example application

Required before starting

There are a few prerequisites that must be addressed before we can begin. At a minimum, you must have PHP and MySQL installed on a Linux based system for this tutorial.

The system I am working with consists of the following:

Fedora 9
Apache 2.2
MySQL 5.x
PHP 5.2.6

My directory structure for Apache is as follows:

/var/www/ – Apache directory
/var/www/html/ – Apache docroot (viewable on the web)
/etc/httpd/conf.d/ – Apache’s configuration directory

If your structure does not look similar, you may be running a different OS or version of Apache. Please refer to your distribution’s manual for more information.

Solar system install

I will be working with Solar “system”, an all-in-one Solar package if you will, which includes Solar “core”, also known as the Solar framework. The main difference between “core” and “system” is that “core” is the standalone Solar framework whereas “system” contains “core” but also sets up your environment for development (directory structure). For more information, please refer to the Solar download page and the manual page on Skeleton System. Remember, we are working with Solar “system”.

For the install, download solar-system-1.0.0alpha2.tgz to /var/www. Once the download is complete do the following:

$ cd /var/www
$ tar -zxvf solar-system-1.0.0alpha2.tgz

Solar is now installed at /var/www/solar. Now we want to set some folder permissions.

$ chmod -R 777 /var/www/solar/tmp
$ chmod -R 777 /var/www/solar/sqlite

The directory “tmp” includes a place to store cached files, PHP sessions, and log files. The directory “sqlite” only needs permissions to be set if you plan on using SQLite. For our project I will be using MySQL.

Congrats! You have just installed Solar!

Project guidelines

Before we jump into setting up our project, let’s first start by figuring out what we want develop. My vote goes to something simple and practical. A blog!

Next, let’s outline our basic blog. What functions will our blog have? In this case, I want to keep things simple, so our blog will have the following functionality.

Blog posts
Categories for posts
Tags for posts
Comments submitted by users
Users that can submit posts

Lastly, we need a project name. I’m going to opt for “Bloggo.” Not very elegant or original, but you get the idea (Pardon me if I am infringing on any name brand sites out there…eek!).

Setting up Apache

We are getting closer to creating our first app, trust me! Before we get there though, we need to setup our Apache configuration and bootstrap file to coincide with our project.

Let’s get to it! First, let’s create the configuration file and edit it.

Note that I am using “su” to become root. This is because my normal user account does not have access to edit this file. You will see this throughout the tutorial. However, your credentials may differ and you need to be aware of this.

$ su
Password:
# touch /etc/httpd/conf.d/bloggo.conf
# nano /etc/httpd/conf.d/bloggo.conf

We want to add the following into our bloggo.conf file. As you can see here we are using Name-based Virtual Hosts. Since my server does not have a top level domain name, I am using localhost as the host name. Please see Apache’s Virtual Host documentation for more information.

NameVirtualHost *:80
<virtualHost *:80>
    ServerName localhost
    DocumentRoot /var/www/solar/docroot
    <directory />
        AllowOverride All
    </directory>
</virtualHost>

Save and close our bloggo.conf file.

Let’s restart Apache.

/etc/init.d/httpd restart

If Apache did not throw any errors then we can move on. If you did receive errors, please review your .conf file.

Basic configuration file

Moving right along to our configuration file. Solar comes with a default configuration file so there isn’t much we need to do. However, some of the info contained in the default configuration file will need to be removed for our project. Go ahead and open up the default configuration file:

$ cd /var/www/solar
$ nano ./config/Solar.config.php

We will be editing the configuration file a bit as the project grows. For now, let’s specify the minimum parameters needed. You will need to edit your configuration file so it looks like the code below:

For more information on Solar’s configuration file syntax and use, see the Solar Manual on Config File.

<?php
/**
 * all config values go in this array, which
 * will be returned at the end of this script
 */
$config = array();
/**
 * system and autoload-include directories
 */
$system = dirname(dirname(__FILE__));
$config['Solar']['system'] = $system;
/**
 * ini_set values
 */
$config['Solar']['ini_set'] = array(
    'error_reporting' => (E_ALL | E_STRICT),
    'display_errors'  => true,
    'html_errors'     => true,
    'session.save_path' => "$system/tmp/session/",
    'date.timezone'   => 'UTC',
);
/**
 * base action href
 */
$config['Solar_Uri_Action']['path'] = '/';
/**
 * base public directory href
 */
$config['Solar_Uri_Public']['path'] = '/public';
/**
 * front controller
 */
$config['Solar_Controller_Front'] = array(
    'classes' => array('Bloggo_App'),
    'disable' => array('base'),
    'default' => 'hello',
    'routing' => array(),
);
/**
 * done!
 */
return $config;

As you can see we are going to display PHP and HTML errors to the web browser. We only want to do this in a development environment. Once the project migrates to a production environment we would set these values to false.

Creating a new project

Ok, now that we got that out of the way, let’s create our project’s workspace, or vendor space, by using Solar’s built in CLI (command line interface).

$ ./script/solar make-vendor Bloggo

This will create all of the directories and symlinks needed for the most basic project. Your project’s structure is held under /var/www/solar/source/bloggo. You will also notice that we now have a “bloggo” executable under /var/www/solar/script. This is here in case you want to create your own CLI scripts.

Creating CLI scripts will not be covered in this series. For more information please see the Solar documentation on CLI or examples under /var/www/solar/source/solar/Solar/Cli.

Creating our first application – Hello

Although this is somewhat covered in the manual under Getting Started – Skeleton App, what isn’t covered is using the CLI to generate an application. What we about to do here is create the most basic application ever – “Hello World.”

The “Hello World” application will not be in our final project. I just want you to become a bit more familiar with the CLI and what files and directories are generated when making an application.

To create our application, let’s do the following from the terminal.

$ ./script/solar make-app Bloggo_App_Hello --extends=Solar_Controller_Page

You can also get a list of available commands from Solar by typing:

$ ./script/solar help

And you can see what available parameters there are for a specific command by typing:

$ ./script/solar help <command>

Let’s go take a look at what Solar generated. All applications for our project are housed under /var/www/solar/source/bloggo/Bloggo/App

You should have the following directory structure:

/Hello/
/Hello/Helper/
/Hello/Layout/
/Hello/Locale/
/Hello/Locale/en_US.php
/Hello/View/
/Hello/View/index.php
/Hello.php

For more information on the directory structure and what each directory is for, please see the App Directory Setup section under the Minimal Application Skeleton page in the manual.

You will also see the directory /Public/ at the same level as our /Base/ directory. Note that this was not created when we created our “Hello World” application but rather when we created our Bloggo project.

Go ahead and open up Hello.php…go on…do it. You will see the following:

<?php
/**
 *
 * Generic application.
 *
 */
class Bloggo_App_Hello extends Solar_Controller_Page {
   /**
    *
    * The default action when no action is specified.
    *
    * @var string
    *
    */
   protected $_action_default = 'index';
   /**
    *
    * Generic index action.
    *
    * @return void
    *
    */
   public function actionIndex()
   {
   }
}

Pretty slick, huh? Now if you browse to http://localhost you should see a page with the text “Welcome to your new app.”

You can also access the Hello application by browsing to http://localhost/hello.

Now let’s go ahead and remove our “Hello World” application.

$ rm -Rf /var/www/solar/source/bloggo/Bloggo/App/Hello*

The next part of this series will jump into creating our first model and application (posts).

Until then, I urge you to join the Solar mailing list and/or IRC channel and start getting involved.

Raymond Kolbe

Code, cars, and beer…

Big Bang with Solar – Part 1

Required before starting

Solar system install

Project guidelines

Setting up Apache

Basic configuration file

Creating a new project

Creating our first application – Hello

Leave a Reply

Recent Posts

Categories

Archives