On January 1, 2010, the beta2 of the Solar MVC PHP framework was released. Additionally, a new “Beginner’s Guide” was posted, which will be a great help to anyone wanting to try out a great PHP Framework.
Happy new year!
Paul M. Jones has what I will call a “fun” post on is blog. There may be some “cheerleading”, but I welcome it. His post points to several areas where the Zend Framework (ZF) developers will be implementing approaches already available in Solar. This is by no means framework-bashing. It’s about letting people know that a top quality framework is available right now. So what are you waiting for? Get started.
After about a year, Solar has moved from version 1.0.0alpha2 to 1.0.0alpha3. Yes, it’s been a while, but when you realize that only one person really works on the project in his spare time, that’s a pretty good achievement. This whole spare time thing is also changing. Solar is about to get a whole lot more attention now that the developer’s employer (OmniTI) has agreed to let him use up to 40% of his paid work time to further develop Solar. Obviously, OmniTI knows a good thing when they see it.
As of writing this, Paul hasn’t had time to update the Solar site with the latest download, but that will likely happen tomorrow. Additionally, there will be a nice post about what has changed. I will add some links when they are available.
Anyone who has used a PHP web framework before, or those who just wants to try one out, should give Solar a whirl. It is the most well-thought-out framework I have had the pleasure of using. What’s next for me? Time to checkout the latest from SVN and give it a work out. The faster we test it and iron out bugs, the sooner there will be a beta release. On that note, a beta release is actually not far off and (hopefully) by the end of the year, the official stable release will be available.
Solar has a simple-to-use, role-based access control library. It is nicely integrated into the user object so getting it working is really just a matter of adding a few lines to your config file. Here is a quick rundown of how to get it working using the file adapter. This means your access control list and roles are stored in simple text files.
Create a file called acl.txt in your config folder
Create a file called roles.txt in your config folder
In the acl.txt file, add the following lines:
allow handle juser * *
allow handle jdoe Vendor_App_Example add
allow handle + Vendor_App_News browse
deny role banned * *
The file format is like this: 0:flag 1:type 2:name 3:class 4:action 5:process
Although I don’t believe that process is currently used.
allow handle juser * *
means allow user juser access to all classes and all actions.
allow handle jdoe Vendor_App_Example add
means allow user jdoe to the add action in Vendor_App_Example
Wildcards * and + can be used too. For example, a + symbol in the name field means any logged in user.
Now add the following line to your roles.txt
banned:gijoe
The format is role:userone,usertwo,userthree
Now add a few lines to your config, assuming you already have the Solar_Auth config previously set up.
$config['Solar_Role']['adapter'] = 'Solar_Role_Adapter_File'; $config['Solar_Role_Adapter_File']['file'] = "$system/config/roles.txt"; $config['Solar_Access']['adapter'] = 'Solar_Access_Adapter_File'; $config['Solar_Access_Adapter_File']['file'] = "$system/config/acl.txt"
In a controller, just add this to one of your actions (for example, actionBrowse()):
if (Solar_Registry::get('user')->access->isAllowed(get_class($this), 'browse')) { // browse logic } else { // access denied logic }
Or, better yet, follow the _preAction() method in Solar_Base.
protected function _preAction() { $allow = Solar_Registry::get('user')->access->isAllowed( get_class($this), $this->_action ); if (! $allow) { $this->errors[] = $this->locale('ERR_NOT_ALLOWED_ACCESS'); $this->_action = 'error'; } }
You can use the access control file to give object owners access to actions as well. If you want to use the isOwner() method, you will need to extend the Solar_Access_Adapter_File class and write your own isOwner() method.
Your acl.txt entry might look like this:
allow owner * Vendor_App_Example edit
This means allow the edit action to the owner of the object in question (like a record in from a database) within the Vendor_App_Example class.
You could extend the access adapter like this:
<?php class Vendor_Access_Adapter_File extends Solar_Access_Adapter_File { public function isOwner($content) { if ($content['owner'] == $content['user']) { return true; } return false; } } ?>
Then, to use this method, you can do the following:
$content = array( 'owner'=>'juser', 'user'=>Solar_Registry::get('user')->auth->handle ); if (Solar_Registry::get('user')->access->isAllowed(get_class($this), 'edit', $content)) { // edit logic here } // or just do (assuming they made it this far) if (Solar_Registry::get('user')->access->isOwner($content)) { // edit logic here }
Well, that’s the basics.
A layout is basically a view (or collection of views) that wrap around controller specific content. They typically include the repeating parts of a website, such as the header, footer and navigation elements. I’ve written about them briefly in a previous post, but in this post, I will elaborate slightly.
This is the general approach I take when using views and layouts in Solar. This isn’t a CSS framework. This is just an approach to laying out files in such a way that they can be easily shared between various Solar applications.
Let’s start with a basic 2 colum site design where I have my site-wide navigation on the left, a header up on top, and the footer below. In the main column is the controller-specific content. Based on that information, I am going to create 6 individual layout files. That seems like a lot, but it will make more sense shortly.
The layout files are as follows:
The main layout file is called 2col-navleft.php. It’s good to choose a descriptive name like this so you know what to expect from the layout. It has 2 columns and the navigation is on the left. This is also the name of the layout you specify in your Solar controllers. For example, your controller would have the following property:
protected $_layout_default = '2col-navleft';
Better yet, you might be using a “Base” controller that all your other controllers extend. In this way, all your child controllers will use the same layout by default. And, of course, you could change this at anytime. More about that later. For now, here is the contents of the main layout.
/**
* File: 2col-navleft.php
*/
<!DOCTYPE html PUBLIC "-W3CDTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<?php
// generate the <head>
include $this->template('_head.php');
// generate the <body>
include $this->template('_body.php')
?>
</html>Nice and simple. You’ve got the doctype and the html block. Within the html block, you can see how to include other layout pieces, such as _head.php and _body.php.
Here is what _head.php looks like. As you can see, its purpose is to create the <head> tags and all the stuff in between.
/** * File: _head.php */ <head> <?php // add meta tags foreach ((array) $this->layout_head['meta'] as $val) { $this->head()->addMeta($val); } // set the title $this->head()->setTitle($this->layout_head['title']); // set the uri base $this->head()->setBase($this->layout_head['base']); // add links foreach ((array) $this->layout_head['link'] as $val) { $this->head()->addLink($val); } // add baseline styles $this->head()->addStyleBase("Vendor/styles/2col-navleft.css"); // additional baseline styles foreach ((array) $this->layout_head['style'] as $val) { $this->head()->addStyleBase($val); } // additional baseline scripts foreach ((array) $this->layout_head['script'] as $val) { $this->head()->addScriptBase($val); } // done! echo $this->head()->fetch(); ?> </head>
This layout uses a nice view helper called Solar_View_Helper_Head ($this->head()…). This helper sets all the head elements and displays them in the correct order. A public property (layout_head) need to be set in order for this to work properly. The layout_head public property is an array.
The next file is _body.php. This file, as you can imagine, sets the content between the <body> tags. Here is what _body.php looks like:
/**
* File:_body.php
*/
<body>
<div id="wrap">
<div id="header">
<?php include $this->template('_header.php'); ?>
</div>
<div id="nav">
<?php include $this->template('_nav.php'); ?>
</div>
<div id="content">
<div id="main">
<?php echo $this->layout_content; ?>
</div>
</div>
<div id="footer">
<?php include $this->template('_footer.php'); ?>
</div>
</div>
</body>Here, you can see several other includes that point to more “sub layouts”.
Of course, these are just the basic layouts you can use. You could add more layouts as you see fit. Things like an _auth.php layout, a _topnav.php layout, etc.
So, why break them into such small pieces? Well, for one, you could easily alter the overall structure of your site by using a different main layout (2col-navright.php or 2col-navtop.php). Or, you could implement a CSS framework such as the Stenhouse CSS Framework. Also, Solar enables a nice heirachy of includes that you can easily have a different _header.php and _nav.php layout for each vendor or even each application. Have a look at the following directory structure to help understand how that works. Let’s start the “include” folder.
include/
Vendor/
App/
Base/
Helper/
Layout/
2col-navleft.php
_body.php
_footer.php
_head.php
_header.php
_nav.php
Locale/
View/
Index/
Helper/
Layout/
_nav.php
Locale/
View/
Solar/
In this example, let’s assume that our Vendor_App_Base class extends Solar_Controller_Page. That class specifies the default layout as 2col-navleft.
<?php class Vendo_App_Base extends Solar_Controller_Page { protected $_layout_default = 'main'; // The array needed in the _head.php layout public $layout_head = array( 'title' => null, 'base' => null, 'meta' => array(), 'link' => array(), 'style' => array(), 'script' => array(), 'object' => array(), ); . . . } ?>
Vendor_App_Index extends Vendor_App_Base.
<?php class Vendor_App_Index extends Vendor_App_Base { protected $_action_default = 'browse'; public function actionBrowse() { // layout_head defined in parent class $this->layout_head['title'] = "Here is my happy site"; } . . . } ?>
By default, any class that extends Vendor_App_Base will use the specified default layout (2col-navleft.php) and all sub layouts. However, In Vendor_App_Index_Helper, we have another _nav.php layout. Whenever you request the index application, this application-specific navigation layout will be used instead of that in the base application. Solar doesn’t need any explicit instructions to do this. It just knows.
As I have mentioned before, both Solar views and layouts have access to public properties in your controller (and those it extends). In the above example, $this->layout_head is a public property, therefore, the layouts and views have access to it via $this->layout_head. Knowing this should help the _head.php layout make even more sense.
Views and layouts aren’t too complex. The best way to learn them is to try it all out. The other really important thing you would be wise to learn about are view helpers.
View helpers are very useful for performing repetitive tasks and, more importantly, an essential way to keep domain logic out of your views. View helpers can be very simple, such as displaying a date in a particular format, or they can be quite complex, such as displaying a complete html form. Solar is packed with many very useful view helpers. Additionally, the way Solar applications are organized makes it easy to create your own view helpers and have them available to several applications.
To use a view helper, simply call it in your view. Take, for example, the title view helper bundled with Solar. This helper simply puts the <title> tags around whatever text you pass to it.
<html> <head> <?php // assume $pagetitle was set in the controller and is public ?> <?php echo $this->title($this->pagetitle); ?> </head>
Ok, so that is a very simple example that you might never use, but you never know. What is important in a helper like this is the automatic escaping of text.
One view helper that I use all the time is the action view helper (Solar_View_Helper_Action). This helper displays an escaped link with the properly formed <a> tags. It takes 3 parameters, the second and third are optional.
It works something like this:
<?php echo $this->action($spec, $text = null, $attribs = null); ?>
$spec is the link,
$text is the text (or a locale key for automatic translation),
$attribs is an array of option attributes to use in the link, such as class, style, or even onclick.
For example:
<?php // assume TEXT_BROWSE is a locale key and translates to 'Browse' ?> <?php echo $this->action('index/browse', 'TEXT_BROWSE'); ?>
This will output:
<a href="/docroot/index/browse">Browse</a>
The docroot part comes from the uri action path in your config file: $config['Solar_Uri_Action']['path'] = ‘/docroot’;
What’s interesting here is that, if you dive into the code, the action helper actually refers to other helpers, actionHref and escape via the $this->_view property. Now you can see how powerful view helpers can be! In fact, many of Solar’s view helpers utilize other Solar view helpers. It just makes sense.
Writing your own view helpers is a snap. You can make them as simple or as complex as you like. Each time you create an application using Solar’s Command Line Interface (CLI), a Helper sub folder is creating in your application’s namespace. For example, if your vendor is named Vendor and your application is named Example, then the Helper folder will exist in a folder structure similar to this.
Vendor/
App/
Example/
Helper/
Layout/
Locale/
View/
Example.php
So, here is an example of a very simple view helper that will take a Canadian postal code in this format A1B2C3 and convert it to the proper A1B 2C3 format.
The helper file is named PostalCode.php and is located in the Helper sub folder of your application.
Here is what it might look like:
<?php /** * View Helper to format a postal code from 6 alpha numeric * characters without a space * to 6 with a space. T9E5W7->T9E 5W7 */ class Vendor_App_Example_Helper_PostalCode extends Solar_View_Helper { public function postalCode($code) { // Get the first 3 chars (note the use of another // view helper called escape) $first_three = $this->_view->escape(strtoupper(substr($code, 0, 3))); // Get the last 3 chars $last_three = $this->_view->escape(strtoupper(substr($code, 3, 3))); // Return the newly formated code with a space return $first_three." ".$last_three; } } ?>
To use this view helper in your view it’s as simple as:
<?php echo $this->postalCode($code); ?>
Another nice feature of view helpers is that they ultimately extend Solar_Base. This means they handle the config files just like all the other Solar classes. If you don’t know about Solar’s config file, then you should definitely read about it.
If you want to create a view helper that has a property that can be customized, then just follow Solar’s standards for classes and objects. Here is an example taken from Solar’s date view helper. I have simplified this from the real file.
<?php class Solar_View_Helper_Date extends Solar_View_Helper { /** * * User-defined configuration values. * */ protected $_Solar_View_Helper_Date = array( 'format' => 'Y-m-d', ); public function __construct($config = null) { parent::__construct($config); } /** * * Outputs a formatted date. * */ public function date($spec, $format = null) { if (! $format) { $format = $this->_config['format']; } return date($format, strtotime($spec)); } } ?>
As you can see, the default format is ‘Y-m-d’. But, that can be changed in 2 ways.
First, you can pass whatever format you want to the helper, and second, you can set a $config value in your config file to override the default.
In a view it would look like this:
<?php echo $this->date('Yesterday', 'm jS, Y'); ?>
If you changed the default in your config file, the file would have an entry like this:
<?php $config['Solar_View_Helper_Date']['format'] = 'm jS, Y'; ?>
That is the basic idea behind view helpers. Remember, if you need to access the current view object from within the view helper, you do so using $this->_view.
What’s really important is that these keep unnecessary logic out of the view!
I wrote a web-based application for my dad recently using, you guessed it, Solar. He had been using a really old version of Quattro Pro for keeping track of all his receivables, invoices, etc. He finally got a new computer, which was 64-bit and Vista, and he couldn’t even load Quattro Pro onto it, so it was time to find a new solution. This, IMHO, was a bit of a blessing. (Holy crap! I haven’t done my taxes yet!!!). Anyway, I offered to create a database and a web-based application that would sever existing ties between the data and presentation. He’s pretty clever, so that seemed like a great idea to him.
So I created the DB, which consisted of about 8 tables and 3 views. This isn’t rocket science, but it’s a great case for a relational database. Next, I whipped up a Solar application to keep track of clients, invoices, products, receivables, etc. It’s not fancy, but it works pretty well for a version 1. One of the coolest things about it – thanks to Solar, I didn’t write a single SQL query! The Solar models worked so well for me, that with a single fetch, I can get every bit of data I need, quickly and efficiently. They also make it dead simple to create or update data, complete with Super Awesome (yes, that’s capitalized and bold) form validation.
The next steps for the application will be to make it more user-friendly. It will be pretty easy to sweeten it up using jQuery UI and custom Solar view helpers. Maybe even a touch of Ajax.
Solar definitely makes my job easier.
Oh, and one of the best things about the application – it has the Solar Powered logo on it 
Views and layouts are responsible for displaying content in the browser. Views are generally specific to a controller action. For example, an action method such as actionIndex() would display its output in a view called index.php. Layouts, on the other hand, are typically shared by the entire application and wrap around the view. A layout usually contains the header, footer, navigation, and the content area where the view’s output is displayed.
read more »
This is the second screen cast focussed on getting started with the Solar PHP web application framework. In this screen cast, I show you how to create a vendor namespace from the command line, create an application from the command line, and how to get data into your views.
Once you have the Solar PHP framework installed with a basic configuration, it’s time to create a simple application. Starting with something very simple is a great way to learn the framework. Also, you can build upon the simple application as you learn more of the features available.
This post is freakishly long for a blog post, so I paginated it. You will see some links to the pages at the bottom of each page.
read more »