To use this helper, just do the following in your views/layouts:

echo $this->email('someuser@somehost.com', 'Ray');

Here is the helper code:

<?php
/**
 * Generates an encoded mailto href to stop spammers from scrapping email
 * addresses from your web pages.  This code is based on the PHP example
 * from http://rumkin.com/tools/mailto_encoder/
 *
 * @category Whitebox
 * @package Whitebox_View
 * @author Raymond J. Kolbe <rkolbe@gmail.com>
 */
class Whitebox_View_Helper_Email extends Solar_View_Helper {
    /**
     * The encoded email address.
     *
     * @var string
     */
    protected $_encoded_string = '';
    /**
     * The encoded index used to decode $_encoded_string/
     *
     * @var string
     */
    protected $_encoded_indexes = '';
    /**
     * Generates an encoded mailto href to stop spammers from
     * scrapping email addresses off your web pages.  Returns
     * an inline javascript code block that allows web browser
     * to read the mailto href.
     *
     * If javascript is disabled in the web browser, only the
     * link text is shown to the user.
     *
     * @param string $spec The email address (e.g. rkolbe@gmail.com)
     * @param string $text Href
     * @param array $attribs An array of href attributes
     * @return string An inline string of javascript to handle the
     * encoded mailto href
     */
    public function email($spec, $text = null, $attribs = null) {
        // escape the email address
        $spec = $this->_view->escape($spec);
        // build attribs, after dropping any 'href' attrib
        $attribs = (array) $attribs;
        unset($attribs['href']);
        $attribs = $this->_view->attribs($attribs);
        $this->_obfuscate("<a href=\"mailto:$spec\"$attribs>$text</a>");
        $script = $this->_getScript();
        $script .= '<noscript>'.$text.'</noscript>';
        return $script;
    }
    /**
     * Takes a given href and obfuscates it.
     *
     * @param string $link A full mailto href
     * @return void
     */
    protected function _obfuscate($link) {
        $scrambled_chars = str_shuffle($link);
        $this->_encoded_string = $this->_escapeString($scrambled_chars);
        $string_indexes = '';
        for ($i = 0; $i < strlen($link); $i++) {
            $index = strpos($scrambled_chars, substr($link, $i, 1)) + 48;
            $string_indexes .= chr($index);
        }
        $this->_encoded_indexes = $this->_escapeString($string_indexes);
    }
    /**
     * Returns a block of javascript used to decode the mailto href.
     * This only allows web browsers to see the mailto address.
     *
     * @param void
     * @return string An inline block of javascript
     */
    protected function _getScript() {
        return $this->_view->scriptInline('<!--
            chars = "'.$this->_encoded_string.'";
            indexes = "'.$this->_encoded_indexes.'";
            href = "";
            for(j = 0; j < indexes.length; j++){
                href += chars.charAt(indexes.charCodeAt(j) - 48);
            }
            document.write(href);
            // -->');
    }
    /**
     * Prepares (escapes) a string for javascript.
     *
     * @param string $string The string to escape
     * @return string The escaped string
     */
    protected function _escapeString($string) {
        $string = str_replace("\\", "\\\\", $string);
        $string = str_replace("\"", "\\\"", $string);
        return $string;
    }
}

The default behavior of Solar_View_Helper_Form will output error messages like this:

However, I had two things I needed to accomplish, 1) create form field hints that are displayed only when a text field is clicked, and 2) move all error messages to the top of the page.

Displaying the field hints was the easy part. The form helper automatically adds in a class named ‘descr’ to each field. I decided to use this class name with a little jQuery (focus and blur) to accomplish my form hint behavior.

The issue I ran into was when the form had errors and a field containing a hint was displayed.

You can see that the hint should be aligned with the first text field, Username. A little bit of Javascript and CSS manipulation could solve this problem but I wanted to consolidate the error messages to an eye catching location anyway, which in turn would solve my alignment issue.

Before I provide you with my solution, let me show you what the finished product looks like:

You can see I have an eye catching error div at the top followed by the hint box being properly aligned. I still need to implement either a) a red asterisk next to each invalid field or b) change the label colors to red. I also need to update my error messages so they read proper. Both of these minor changes are not solve in this blog post. I’ll save that for a rainy day

So, how did I do this? I simply copied down Solar_View_Helper_Form from the Solar project to my working directory (Fahwebmon/View/Helper/Form.php) and renamed the class to Fahwebmon_View_Helper_Form. Note that you don’t have to copy down the whole file. You can create your own class and extend Solar_View_Helper_Form since we are only modifying the fetch() method on this class.

Here is the modified code. Note that I have only tested this with text fields.

public function fetch($with_form_tag = true)
{
// stack of output elements
$form = array();
$feedback = array();
// the form tag itself?
if ($with_form_tag) {
$form[] = '<form' . $this->_view->attribs($this->_attribs) . '>';
}
// what status class should we use?
if ($this->_status === true) {
$class = $this->_css_class['success'];
$feedback = $this->_feedback;
} elseif ($this->_status === false) {
$class = $this->_css_class['failure'];
} else {
$feedback = null;
$class = null;
}
// the hidden elements
if ($this->_hidden) {
// wrap in a hidden fieldset for XHTML-Strict compliance
$form[] = '    <fieldset style="display: none;">';
foreach ($this->_hidden as $info) {
$form[] = '        ' . $this->_view->formHidden($info);
}
$form[] = '    </fieldset>';
$form[] = '    ';
}
// loop through the stack
$in_dl       = false;
$in_fieldset = false;
$in_group    = false;
foreach ($this->_stack as $key => $val) {
$type = $val[0];
$info = $val[1];
if ($type == 'element') {
// be sure we're in a <dl> block
if (! $in_dl) {
$form[] = '        <dl>';
$in_dl = true;
}
// setup
$label    = $this->_view->getText($info['label']);
$id       = $this->_view->escape($info['attribs']['id']);
$method   = 'form' . ucfirst($info['type']);
try {
// look for the requested element helper
$helper = $this->_view->getHelper($method);
} catch (Solar_Class_Stack_Exception_ClassNotFound $e) {
// use 'text' helper as a fallback
$method = 'formText';
$helper = $this->_view->getHelper($method);
}
// SPECIAL CASE:
// checkboxes that are not in groups don't get an "extra" label.
if (strtolower($info['type']) == 'checkbox' && ! $in_group) {
$info['label'] = null;
}
// get the element output
$element = $helper->$method($info);
// get the element description
$dt_descr = '';
$dd_descr = '';
// only build a description if it's non-empty, and isn't a
// DESCR_* "empty" locale value.
if ($info['descr'] && substr($info['descr'], 0, 6) != 'DESCR_') {
// build the base description.
// open the tag ...
$descr = "<" . $this->_view->escape($this->_descr_tag);
// ... add a CSS class ...
if ($this->_descr_class) {
$descr .= ' class="'
. $this->_view->escape($this->_descr_class)
. '"';
}
// ... add the raw descr XHTML, and close the tag.
$descr .= '>' . $info['descr']
. '</' . $this->_view->escape($this->_descr_tag) . '>';
// build both the <dt> and <dd> forms so we can use
// them in the right place.
if ($this->_descr_elem == 'dt') {
// using <dt>
$dt_descr = $descr;
} else {
// using <dd>
$dd_descr = $descr;
}
}
// add the element;
// handle differently if we're in a group.
if ($in_group) {
// add the element itself
$form[] = "                $element";
} else {
$require = '';
// is the element required?
if ($info['require']) {
$require = ' class="' . $this->_css_class['require'] . '"';
}
// add the form element with all parts in place
$form[] = "            <dt$require><label$require for=\"$id\">$label</label>$dt_descr</dt>";
$form[] = "            <dd$require>$element$dd_descr</dd>";
$form[] = '';
}
// handle element feedback
if (!empty($info['invalid'])) {
foreach ($info['invalid'] as $invalid) {
$feedback[] = $label . ' ' . strtolower(substr($invalid, 0, 1) . substr($invalid, 1));
}
}
} elseif ($type == 'group') {
// be sure we're in a <dl> block
if (! $in_dl) {
$form[] = '        <dl>';
$in_dl = true;
}
$flag = $info[0];
$label = $info[1];
if ($flag) {
$in_group = true;
$form[] = "            <dt><label>$label</label></dt>";
$form[] = "            <dd>";
} else {
$in_group = false;
$form[] = "            </dd>";
$form[] = '';
}
} elseif ($type == 'fieldset') {
$flag = $info[0];
$legend = $this->_view->getText($info[1]);
if ($flag) {
$form[] = "    <fieldset><legend>$legend</legend>";
$form[] = "        <dl>";
$in_fieldset = true;
$in_dl = true;
} else {
$form[] = "        </dl>";
$form[] = "    </fieldset>";
$form[] = '';
$in_dl = false;
$in_fieldset = false;
}
}
}
if ($in_group) {
$form[] = '            </dd>';
}
if ($in_dl) {
$form[] = '        </dl>';
}
if ($in_fieldset) {
$form[] = '    </fieldset>';
}
// add a closing form tag? This also determins where feedback should be.
if ($with_form_tag) {
// temporarily grab the open form tag and remove it from the array
$openFormTag = array_shift($form);
// add the form open tag and feedback
array_unshift($form, $openFormTag, $this->listFeedback($feedback, $class));
// finally add the closing form tag
$form[] = '</form>';
} else {
// inject feedback as first element
array_unshift($form, $this->listFeedback($feedback, $class));
}
// reset for the next pass
$this->reset();
// done, return the output!
return implode("\n", $form);
}

Being lazy and using regex (I love it!), I came up with the following solution:

// test text w/embedded code
$text = "This is a sample text string with PHP style tags. [PHP] echo 'Hello'; [/PHP]
// and I made sure to make this case insensitive.
$pattern = "/\[PHP\](.*)\[\/PHP\]/Uis";
// the magic!
$matchCount = preg_match_all($pattern, $text, $matches, PREG_SET_ORDER);
if ($matchCount !== false && $matchCount > 0) {
    foreach ($matches as $match) {
        // highlight_string forces us to start with at least the php opening tag
        $highlightedCode = highlight_string('<?php'.$match[1].'?>', true);
        // finally, replace the original non-highlighted text with the highlighted text
        $text = preg_replace($pattern, $highlightedCode, $text, 1);
    }
}
echo $text;

Just FYI, this was a quick one-off and wasn’t intended to scale with other bbcode style tags. Also, in my real code, the [PHP] tags are lowercase. The only reason they are uppercase is because the syntax highlighter in Wordpress isn’t smart enough to distinguish the tags in my code and tags to signify syntax highlighting.

One of the nice things Solar has to offer is its CLI (Command Line Interface), which can be used to accomplish tasks that would otherwise eat up valuable time, such as creating applications, models, tests, documentation, and unit tests. In this entry, I will be showing you how to use the current (Solar v1.0.0 alpha2) CLI, detailing commands, available options, parameters, and usage examples. So make sure that you have a fresh pot of coffee and let’s get to it!

First Glance

Under a Solar system you will find an executable called solar, located in the script directory. For our example, let’s assume our Solar system is installed under /var/www/solar/. You will find the executable under the directory /var/www/solar/script/.

From the terminal, change directories to /var/www/solar/. Let’s go ahead and run the solar executable and examine what is returned.

$ ./script/solar
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
Solar command-line tool.
Usage: solar <command> <options> <params>
Try 'solar help' for a list of commands.

Here we can see what our include paths are, as well as the configuration file we are using. In a Solar system, Solar defaults to using Solar.config.php, the default configuration file.

You will also notice that the Solar CLI gives you the proper syntax to use, solar <command> <options> <params>. This is important so keep it in mind as we go along For now, let’s jump to the most basic command and the most helpful, help.

Help command

We can learn more about any command in the CLI by using the help command. The syntax for this is solar help <command> where command is the command we want to know more about. We can also get a list of available commands by typing solar help. Let’s give that a try, shall we?

$ ./script/solar help
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
Solar command-line tool.
Usage: solar <command> <options> <params>
Try 'solar help <command>' for help on a specific command.
Available commands are:
    base
    help
    make-app
    make-docs
    make-model
    make-tests
    make-vendor
    run-tests

Here are all of our available commands. You can ignore the base command since this is just the command in which all other commands extend and is of no value to us here.

Here is a quick break down of each command.

• base – Base class in which all commands extend. Not usable from the CLI!
• help – Returns command usage or a list of available commands.
• make-app – Generates a basic application or an application with BREAD functionality.
• make-docs – Generates package and API documentation files.
• make-model – Generates a model class from an SQL table.
• make-tests – Generates a test class (or set of classes) from a given class.
• make-vendor – Creates the appropriate directories and symlinks for a new project (also referred to as a vendor space).
• run-tests – Runs a series of tests or a single test.

Please note that all commands have the following available options:

• –config – Allows you to use a specific configuration file. Default is Solar.config.php.
• -V | –version – Returns version information.
• -v | –verbose – Displays verbose output when available.

Now that we have a general idea of the available commands and proper syntax, let’s talk about each one in depth.

Make-app

Make-app allows you to rapidly generate a simple generic application or a more complex application that supports BREAD functionality on the fly.

Help information

$ ./script/solar help make-app
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--config
:  Use this configuration file when starting Solar.
--extends
:  Extends from this class name.
--model
:  Add this model class automatically.
--target
:  The target directory, typically the PEAR directory.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

Extends
The name of the class that we want to extend. This is handy if you are using a base class in which all applications extend. Currently defaults to Solar_App_Base.

Model
Solar can auto generate an application with BREAD functionality when you specify a model to use. This adds functionality for browsing, reading, editing, adding, and deleting records from the database.

Target
Allows you to specify the target directory to generate the given application. Not needed if you are using a Solar system.

Available params

Class
The class name. This is required. An example would be Vendor_App_Blog.

Usage examples

Let’s say we want to create a simple application that will extend our page controller (Solar_Controller_Page). For the examples that follow, our project will be named “Vendor.”

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

This generates a basic application named Hello. If you change your working directory to /var/www/solar/source/Vendor/App/Hello/ you should have the following structure:

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

Now, let’s kick it up a notch and generate an application that uses an existing model. In this case, we want an application called Blog, for blog posts. The model we are using is called Posts since blogs usually contain posts. In this example I am assuming that the model Posts has already been created.

$ ./script/solar make-app --extend=Solar_Controller_Page --model=Vendor_Model_Posts Vendor_App_Blog

This will create all of the actions and views for browsing, reading, editing, adding, and deleting blog posts from the database.

Here are the generated files and directories, found under /var/www/solar/source/Vendor/App/Blog/.

• /Blog/Helper/
• /Blog/Layout/
• /Blog/Locale/
• /Blog/Locale/en_US.php
• /Blog/View/
• /Blog/View/add.php
• /Blog/View/browse.php
• /Blog/View/delete.php
• /Blog/View/edit.php
• /Blog/View/read.php
• /Blog/View/_record.php
• /Blog.php

Make-docs

Make-docs allows you to quickly turn your inline comments into solid documentation, like phpDocumentor.

Help information

$ ./script/solar help make-docs
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--class-dir
:  Write class API docs to this directory.
--config
:  Use this configuration file when starting Solar.
--package-dir
:  Write package docs to this directory.
--source
:  The source directory, typically the PEAR directory.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

Class-dir
The directory where class API documentation will be written to.

Package-dir
The directory where package documentation will be written to.

Source-dir
The directory where your project lives. Given the example we have been working with, this would be /var/www/solar/source/vendor/.

Available params

Class
The class name. This is required. An example would be Vendor_App_Blog.

Usage examples

Let’s say we have an application called Blog and we wanted to generate documentation for it. It is as easy as doing the following.

$ ./script/solar make-docs --class-dir=/var/www/solar/source/vendor/docs/ --package-dir=/var/www/solar/source/vendor/docs/ --source=/var/www/solar/source/vendor/ Vendor_App_Blog

If you take a look at the docs directory, /var/www/solar/source/vendor/docs/, you will see a file and a folder with the same name, Vendor_App_Blog. The file in this directory contains the package information and the directory contains many files, each file containing information about each relevant method for our application.

Make-model

Make-model reduces the time it takes to set up models, which can be very time consuming to setup by hand. Make-model streamlines this process by reading your existing SQL table and creating the model based off of this information.

Help information

$ ./script/solar help make-model
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--adapter
:  The SQL adapter class to use.
--config
:  Use this configuration file when starting Solar.
--connect
:  Connect to the database and fetch cols for the model setup.
--extends
:  Extend the model class from this parent class name.
--host
:  The host for the database connection.
--name
:  The name of the database to connect to.
--pass
:  The password for the database connection.
--port
:  The port for the database connection.
--table
:  The table name for the model to use.
--target
:  Write files to this directory, typically the include directory.
--user
:  The username for the database connection.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

Adapter
The SQL adapter to use. Examples include Solar_Sql_Adapter_Mysql and Solar_Sql_Adapter_Sqlite.

Connect
If set to true, Solar connects to the SQL table to generate the model to reflect the columns in the table.

Extends
The name of the class that we want to extend. Defaults to Solar_Sql_Model.

Host
The host where the database resides (e.g. localhost).

Name
Name of the database to connect to.

Pass
Password to be used with user name.

Port
Port that our database is running on.

Table
Table name we want to create our model for and from.

User
User name that has access to the database table.

Available params

Class
The class name. This is required. An example would be Vendor_App_Blog.

Usage examples

Now, this is where using a configuration file makes life easy. First though, I am going to show you the (more time consuming) way to generate a model without changing your current (default) configuration file.

Just so I do not lose you, let me specify the basic settings I am using for my database.

• Database type: MySQL
• Database name: vendor
• Host: localhost
• User name: root
• Password: s3cr3tP@ssw0rd

Now let’s generate a model that controls blog posts. The name of this model will be posts. The table layout we will be using looks like this:

• id (primary key, auto increment)
• title (varchar(100))
• body (text)
• author (varchar(100))
• created (datetime)
• updated (datetime)

For the lazy people reading this, you can just run the following MySQL to generate the table.

CREATE TABLE posts(
id INT NOT NULL AUTO_INCREMENT,
PRIMARY KEY(id),
    title VARCHAR(100),
    body VARCHAR(100),
    author VARCHAR(100),
    created DATETIME,
    updated DATETIME
) engine=INNODB

Now on to generating our model for posts (the long way).

$ ./source/solar make-model --adapter=Solar_Sql_Adapter_Mysql --connect=true --host=localhost --name=vendor --pass=s3cr3tP@ssw0rd --table=posts --user=root Vendor_Model_Posts

That is all there is to it. You can see the files generated by changing directories to /var/www/solar/source/vendor/Vendor/Model/. Here you will see the following layout.

• /Posts.php
• /Posts/Collection.php
• /Posts/Record.php
• /Posts/Setup
• /Posts/Setup/table_cols.php
• /Posts/Setup/table_name.php

Now, the easy way to generate models is to save your database connection information to your configuration file. Go ahead and open up Solar.config.php, located under the directory /var/www/solar/config/.

Add the following to the configuration file.

$config['Solar_Sql']['adapter'] = 'Solar_Sql_Adapter_Mysql';
$config['Solar_Sql_Adapter_Mysql'] = array(
    'host' = 'localhost',
    'user' = 'root',
    'pass' = 's3cr3tP@ssw0rd',
    'name' = 'vendor',
);

Now, when we want to generate a model, we only need to do the following.

$ ./script/solar make-model --table=posts Vendor_Model_Posts

Make-tests

Make-tests is great for generating a single set or suite of tests that can (and should) be altered to test your classes.

Help information

$ ./script/solar help make-tests
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--config
:  Use this configuration file when starting Solar.
--only
:  Make tests only for the named class; do not descend into subdirectories.
--target
:  Where the tests will be written to.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

Only
Make tests only for the specified class (e.g. Vendor_App_Blog only).

Target
The directory where the test files will be saved to. Defaults to the tests directory, /var/www/solar/source/vendor/tests/ for our example(s).

Available params

Class
The class name. This is required. An example would be Vendor_App_Blog.

Usage examples

To generate a suite of tests for your classes, you need only to specify the target to save the tests to and the class in which you want to generate the tests for.

$ ./script/solar make-tests --target=/var/www/solar/source/vendor/tests/ Vendor_App_Blog

We are left with the the following directory structure under the tests directory, /var/www/solar/source/vendor/tests/.

• /Test/Vendor/
• /Test/Vendor/App/
• /Test/Vendor/App/Blog.php

At this point you will want to edit Blog.php to edit the predefined tests for your class.

If you only need to generate a test for a specific class and you do not want to recursively create tests, issue the only option.

$ ./script/solar make-tests --only=true --target=/var/www/solar/source/vendor/tests/ Vendor_App_Blog

Make-vendor

Make-vendor generates the most basic vendor space for a new project. Before any application, model, etc. can be created, a vendor must be created.

Help information

$ ./script/solar help make-vendor
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--config
:  Use this configuration file when starting Solar.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

None

Available params

Name
The vendor name. This is required. An example could be Vendor.

Usage examples

To create a new vendor, simply do the following.

$ ./script/solar make-vendor Vendor

The following directories are generated.

• /source/vendor/bin/
• /source/vendor/docs/
• /source/vendor/tests/
• /source/vendor/Vendor/App/
• /source/vendor/Vendor/App/Public/
• /source/vendor/Vendor/App/Public/images/
• /source/vendor/Vendor/App/Public/scripts/
• /source/vendor/Vendor/App/Public/styles/
• /source/vendor/Vendor/Model/
• /source/vendor/Vendor/Locale/
• /source/vendor/Vendor/View/
• /source/vendor/Vendor/View/Helper/

And the following symlinks (*nix only) are made.

• /source/vendor/Vendor/ to /include/Vendor
• /source/vendor/Vendor/App/Public/ to /docroot/public/Vendor/
• /source/solar/bin/solar to /script/vendor

Run-tests

Run-tests allows you to run the tests generated by make-tests.

Help information

$ ./script/solar help run-tests
Using include_path '.:..:/var/www/solar/include'.
Using config file '/var/www/solar/config/Solar.config.php'.
No help is available for this command.
Valid options for this command are...
--config
:  Use this configuration file when starting Solar.
--dir
:  The path to the tests directory.
--only
:  Run only the named test class; do not descend into subclass tests.
-V | --version
:  Display version information and exit.
-v | --verbose
:  Display verbose output when available.

Available options

Dir
The directory where the tests are held.

Only
Run a specific test class without descending into subclass tests.

Available params

None

Usage examples

In the usage example for make-tests shown above, we created a test class for our Blog application, Vendor_App_Blog. If we wanted to run this test all we would have to do is the following.

$ ./script/solar run-tests --dir=/var/www/solar/source/vendor/tests/

Note that if there are other tests in the tests directory those will be run as well. If we only want to run a specific test we would use the only option.

$ ./script/solar --dir=/var/www/solar/source/vendor/tests/Test/Vendor/App/Blog.php --only=true

For our example we will use the fictional web sites polygon-ex.com and square-ex.com. If these sites actually exist I apologize in advance for using the names without permission…please forgive me

Configuring Apache

Let’s start by creating two new configuration files for Apache. These configuration files will hold information pertaining to our virtual hosts.

$ cd /etc/httpd/conf.d/
$ touch polygon-ex.conf
$ touch square-ex.conf

Before we edit these files, let’s create the directories for each web site under /var/www.

$ cd /var/www
$ mkdir polygon-ex
$ mkdir square-ex

Now we can edit our configuration files. Let’s start with polygon-ex.com.

$ nano /etc/httpd/conf.d/polygon-ex.conf

To define the virtual host you will want something like the following.

<virtualHost *:80>
    ServerName polygon-ex.com
    DocumentRoot /var/www/polygon-ex/docroot
    <directory />
        AllowOverride All
    </directory>
</virtualHost>

Note that you need to have “NameVirtualHost *:80″ in your main httpd.conf file, most likely located at /etc/httpd/conf/httpd.conf, in order for virtual hosts to work. See Using Name-based Virtual Hosts in Apache’s documentation for more information regarding this.

Note that I have opted for name-based virtual hosting instead of IP-based.

Note the line AllowOverride All. I have set very loose access here for example purposes only. Please refer to Apache’s wonderful documentation on the AllowOverride Directive so you are not compromising the security of your server.

Now do the same for square-ex.conf but change the ServerName and DocumentRoot information to coincide with square-ex.com.

Last but not least, restart Apache.

$ /etc/init.d/httpd restart

Obtaining and extracting Solar

If you haven’t downloaded solar-system-1.0.0alpha2.tgz already, go do so now.

Change your working directory to where you saved solar-system-1.0.0alpha2.tgz and do the following.

$ tar -zxvf solar-system-1.0.0alpha2.tgz -C /var/www/polygon-ex
$ tar -zxvf solar-system-1.0.0alpha2.tgz -C /var/www/square-ex

Now if you change your working directory to /var/www/polygon-ex or /var/www/square-ex you will see a folder called “solar” under each. We do not want to keep the directory set up like this, since we want Solar to be installed at the root of our virtual host.

To correct this we just move some files around.

$ cd /var/www/polygon-ex/
$ mv ./solar/* ./
$ rm -Rf ./solar/

And for square-ex.

$ cd /var/www/square-ex/
$ mv ./solar/* ./
$ rm -Rf ./solar/

What we just did here, was move the contents of the “solar” directory up a level. We also removed the now empty “solar” directory that is no longer needed. Now our Apache configuration file will be able to find the directory “docroot.”

One last thing before we move on. We need to change the permissions of our /tmp folder within our project directories so that our pre-configured Solar project can read/write PHP sessions to our sessions folder (located at /var/www/polygon-ex/tmp/session and /var/www/square-ex/tmp/session).

$ cd /var/www/polygon-ex
$ chmod -R 777 ./tmp/
$ cd /var/www/square-ex
$ chmod -R 777 ./tmp/

Testing it all out

Now how do we know this all works? Well, let’s test it! First and foremost, since polygon-ex.com and square-ex.com are not real domains, we must enter them into our “hosts” file so we can resolve the domain name. Let’s do that now.

$ nano /etc/hosts

Your hosts file may look like the following.

127.0.0.1 localhost.localdomain localhost

We want to change it to look like this.

127.0.0.1 localhost.localdomain localhost polygon-ex.com square-ex.com

Go ahead and open up your web browser and point it to http://polygon-ex.com or http://square-ex.com. You should see “Hello World!” on each page.

If you are not convinced that each project is associated with its own domain then let’s step it up a bit and edit one of the Hello World examples.

$ nano /var/www/polygon-ex/source/solar/Solar/App/Hello/View/index.php

Change the text to read.

Hello World! - Welcome to polygon-ex.com!

Save and close that file and refresh http://polygon-ex.com in your web browser. You should now see the text we just entered. Now browse on over to http://square-ex.com and you will just see “Hello World!”

Ta da! You just setup two virtual hosts that use Solar. Now go explore Solar by visiting SolarPHP.com and don’t forget to join us on the mailing list and/or in the IRC channel.

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.

Resources related to this tutorial can be found on the last page.

Getting Started – Your configuration file

First, we want to setup our configuration file to tell Solar to use the MySQL adapter so we can establish a connection to the database. For more information on how to setup a configuration file please reference SolarPHP’s manual.

[PHP]
$config = array();

// Front controller HREF prefix
$config['Solar_Uri_Action']['path'] = '/index.php';

// Public directory HREF prefix
$config['Solar_Uri_Public']['path'] = '/public';

// Specify our SQL adapter
$config['Solar_Sql'] = array(
'adapter' => ‘Solar_Sql_Adapter_Mysql’,
);

/*
*
* SQL adapter information
*
* `host` : Host that houses our database.
* `user` : User name that has access to the database.
* `pass` : Associated password with the user name.
* `name` : Name of the database we are connecting to.
*
*/
$config['Solar_Sql_Adapter_Mysql'] = array(
‘host’ => ‘localhost’,
‘user’ => ‘root’,
‘pass’ => ‘myS3cR37p@ssw0rd’,
‘name’ => ‘MyProject’,
);

// Done!
return $config;
?>
[/PHP]

MySQL table creation

Next, we want to create the table that will hold our user information. At this point I am assuming that you have already created your database and the proper credentials associated with it. *Note the created and updated columns. I have thrown these in here for later use not covered in this post. You can leave these two columns out if you want.

[CODE]
#
# Basic user table layout
#
# name : Real name of our user.
# handle : User name used to login with.
# password : MD5 hash will be stored here.
# created : Timestamp when the row was added.
# updated: Timestamp when the row was modified.
#
CREATE TABLE users(
id INT NOT NULL AUTO_INCREMENT,
PRIMARY KEY(id),
name VARCHAR(255),
handle VARCHAR(255),
password VARCHAR(32),
created DATETIME,
updated DATETIME
)
[/CODE]

Back to the configuration file – Setting up the authentication

Now that we have our users table, we want to jump back into our configuration file and tell Solar to use the SQL adapter for authentication. This is what our final configuration file will look like.

[PHP]
$config = array();

// Front controller HREF prefix
$config['Solar_Uri_Action']['path'] = '/index.php';

// Public directory HREF prefix
$config['Solar_Uri_Public']['path'] = '/public';

// Specify our SQL adapter
$config['Solar_Sql'] = array(
'adapter' => ‘Solar_Sql_Adapter_Mysql’,
);

/*
*
* SQL adapter information
*
* `host` : Host that houses our database.
* `user` : User name that has access to the database.
* `pass` : Associated password with the user name.
* `name` : Name of the database we are connecting to.
*
*/
$config['Solar_Sql_Adapter_Mysql'] = array(
‘host’ => ‘localhost’,
‘user’ => ‘root’,
‘pass’ => ‘myS3cR37p@ssw0rd’,
‘name’ => ‘MyProject’,
);

// Specify our authentication adapter
$config['Solar_Auth'] = array(
‘adapter’ => ‘Solar_Auth_Adapter_Sql’,
);

/*
*
* Authentication adapter information
*
* `table` : MySQL table holding our user information.
* `handle_col` : Specify the column for the user’s handle.
* `passwd_col` : Specify the column for the user’s password.
*
*/
$config['Solar_Auth_Adapter_Sql'] = array(
‘table’ => ‘users’,
‘handle_col’ => ‘handle’,
‘passwd_col’ => ‘password’,
);

// Done!
return $config;
?>
[/PHP]

Done! – Conclusion and additional resources

That’s it! It really is that simple to change your authentication source from using a .htpasswd file to using MySQL. If any of you got lost in the process, please reference the materials below. If you are still stuck, please join the SolarPHP mailing list and/or IRC channel and post up

• Solar Manual – The official SolarPHP manual.
• Config File Help – Working with SolarPHP’s configuration file.
• Solar_Sql and Solar_Sql_Adapter_Mysql- API references