With a private alpha release due out soon, we’re gearing up to help developers take full advantage of the 3.0 platform. Our goal is to make it as easy as possible to build really advanced plugins, widgets, gateways, and modules. To facilitate that we’ve written some detailed interfaces and libraries, as well as put together a pretty in-depth developer manual. And while the v3 source is almost entirely open, I figured what the heck, how about some source code documentation? So I created Doctorate.

Doctorate is a simple plugin for minPHP that documents source code using Reflection. Being able to read the source documentation without actually having to open the source code is a huge advantage. But because the Blesta API is just a simple access wrapper for the Models it’s a huge time saver for us. It would take months to document every API request (there are hundreds and hundreds), but Doctorate does it automatically.

Here is a sneak peak of the source code documentation from Doctorate…

Here is a sneak peak at the developer manual…

So when can you expect to get your hands on the developer manual and source documentation? If you’ve made it onto our developer list you can take advantage of these resources as soon as alpha is released. When 3.0 goes into beta we’ll make the documentation public.

Tags: doctorate | documentation | minphp | v3 | version 3

As lead developer, my primary focus has been on designing an efficient system. Since our primary data store (where we make the most reads/writes) is the database, naturally this is where the smallest change can have the biggest impact. I’ve already discussed a number of changes we’ve made to the database system including switching to InnoDB and the use of PDO. The last is the use of unbuffered queries.

Buffered Queries

Buffered queries fetch (e.g. buffer) all records into memory from the database server and automatically close the cursor, allowing other queries to be executed. You might take this for granted. For example, you may have something like:

// What looks like 'nested' queries...
$statment = mysql_query($sql);
while ($data = mysql_fetch_assoc($statment)) {
    $statment2 = mysql_query($sql2);
    while ($data2 = mysql_fetch_assoc($statment2)) {
        ...
    }
}

This might be all fine and dandy, but assume that the first query finds 1,000,000 rows. If each row contained just 1 KB of data, that’s 976 MB of memory consumed! Keep in mind that the memory is consumed at mysql_query(), so it doesn’t matter how many rows you actually fetch (using mysql_fetch_*). Moreover, the memory isn’t freed until the program terminates or you explicitly invoke mysql_free_result().

Unbuffered Queries

Unbuffered queries, on the other hand, are not buffered into memory. Each row remains on the database server until fetched. This can drastically reduce memory consumption on the web server.

The only downside is that you can’t create what look like “nested” queries (as in my example above). But that really isn’t a downside at all, because it forces you to look at better methods for fetching or querying data. Like limiting your result set and fetching all results.

The Record component in Blesta, in conjunction with PDO, make unbuffered query support almost seamless. You really only need to be concerned about closing the cursor if you’re explicitly working with PDOStatement objects.

// Manually work with the statement...
$users = array();
$user_stmt = $this->Record->select()->from("users")->getStatement();
foreach ($user_stmt as $user) {
    $users[] = $user;
}
$user_stmt->closeCursor();
 
// Or just let the Record component to handle it all...
$users = $this->Record->select()->from("users")->fetchAll();

While the benefit of unbuffered queries may not be entirely evident on small data sets, there’s no doubting it improves efficiency. And that’s what creating an enterprise-level application is all about.

Tags: blesta 3.0 | database | minphp | queries | v3

A lot of effort has gone into designing and interfacing with the database in version 3, so I thought I’d share a little insight into some of the improvements we’ve made over version 2.

We’ve beefed up the database by making use of transactions, which allow us to add, edit, or remove items from the database with the ability to undo those changes should something go wrong. Because of this we’ve made the switch from a MyISAM storage engine to InnoDB (the default for MySQL as of version 5.5), making Blesta ACID-ic.

Another major improvement is the use of UTF8 collation, which will now allow users to more easily search the database in their native tongue as well as input and output data without conversion. This is a huge improvement for developers, and we are all about developers with version 3.

Speaking of developers, another great improvement is the introduction of the Record component. The record component is a database access object that creates queries using a series of method calls. Never again will you have to worry about which comes first, GROUP BY or ORDER BY.

In addition, the Record component uses the PDO library, making queries safe and secure. But that’s not the only benefit of PDO. Can we say “multi-database support”, as in MSSQL, PostgreSQL, and others? Well, no, not at the moment, but that’s definitely a possibility.

From the Developer Documentation:

Tags: blesta 3.0 | database | minphp | Record | v3

In this developer commentary, I give a behind the scenes look at the API in version 3.

What we’ve done is create a controller to make available all of the various models in a RESTful manner, using the four primary HTTP verbs (GET, POST, PUT, DELETE). All this controller needs to do is handle parameter passing and output formatting, which we’ve done here in just 342 lines. Available output formats are JSON, XML, and PHP serialization, but more may be added in the future.

The API supports an unlimited number of users, so you can delegate users for specific tasks. In addition, the API may be extended by plugins. The format for those requests is /api/pluginName.modelName/method.format.

Currently the API supports HTTP Basic authentication, but we’re looking to add Digest authentication in the future as well. In addition, we’ve added command line interface (CLI) support which is bound to make API development easier for you programmers out there.

Click the icon in the bottom right of the video player to go full screen.

Tags: api | behind the scenes | blesta 3.0 | cli | developer commentary | minphp | version 3

There are two prevailing factors that determine how well a software product can adapt, improve, and be extended without imploding in on itself. They are:

1. Coupling, and
2. Cohesion

Coupling represents how dependent a given module is on other modules within the system (I use the term “module” in this article in an abstract sense to describe an object or set of objects that are designed to accomplish some task). A loosely coupled module doesn’t rely or expose much of its inner workings to other modules. Conversely, a tightly coupled module relies heavily on other modules and may expose portions of its inner workings so that other modules may interact with it.

Version 3 of Blesta is built on top of an MVC (Model-View-Controller) framework, which, as the name suggests, separates control into three distinct areas. Building off of an MVC framework (in our case, minPHP) gives us the discipline needed to maintain a loosely coupled system. But it’s not without its challenges. For example, as I’ve mentioned in a previous article explaining data validation, error handling can be handled in a number of ways, but the best way is this through message passing. This allows the errors of a model to be accessed and interpreted without the controller having any direct knowledge of the model or how it works, and vice versa, thus maintaining a loosely coupled relationship.

Cohesion relates to how well the various functional elements of a module are related. High cohesion requires that the module be, in a sense, single-minded. In other words, a class may have high cohesion if all of its methods are closely related. Low cohesion means that a module attempts to accomplish too many tasks, or relates to multiple distinct sets of data.

When designing a modular system, we strive for high cohesion because it improves readability and comprehension of a particular module. If a module attempts too much it becomes bloated, disorganized, and difficult to maintain.

This works hand in hand with coupling. As each module becomes more refined it generally becomes more independent, or loosely coupled. A perfect example of this is the payment gateway system in version 3, which consists of four merchant gateway interfaces (Credit Card, ACH, off-site Credit Card, and off-site ACH). Each interface is designed to accomplish a distinct set of actions (high cohesion), and each payment gateway is thereby only associated with the rest of the system through the implemented interfaces (low coupling). This allows us to create a wide variety of payment gateways that can process credit cards only, or ACH payments only, or any other combination of interfaces without requiring any changes to any other parts of the system.

Tags: blesta 3.0 | cohesion | coupling | design | minphp | version 3

i18n, or internationalization, is the process of adapting software to be deployed around the world. Since version 1.0 we’ve dedicated a large portion of our time to making Blesta an international product. And in version 3 we’ve gone even further by enhancing our multi-language support.

To start, you’ll notice language definitions are now diffused across multiple files. This serves two purposes. First, it promotes congruency between objects and their associated language (each Controller and Model has its own language file). Secondly, it allows us to load only content that is relative to the resource being requested. This saves memory, speeds up load times, and makes development much easier.

Syntax support has also been greatly improved. Previous versions supported tag replacement, but many phrases and sentences were graphed or concatenated together. This meant that some translations were left with incorrect syntax or awkward phrasing. We were able to do away with that thanks to minPHP’s Language support.

Here’s an example, flashing a success message after having saved a staff group:

// Success
$this->flashMessage("message", Language::_("AdminSystemStaff.!success.group_updated", true, $this->post['name']));
$this->redirect($this->base_uri . "settings/system/staff/groups/");

Here’s the related language definition:

$lang['AdminSystemStaff.!success.group_updated'] = "The staff group, %1\$s, has been successfully updated!";

And the visual result:

In addition, version 3 offers automatic fall-back language support in the case of missing definitions.

And finally, we’re introducing translation support for modules, gateways, plugins, and widgets. Everything is translatable. Let’s see how long it takes the competition to catch on.

Tags: blesta 3.0 | i18n | internationalization | minphp | version 3

In this developer commentary, I give an in depth look at how AJAX events are handled in version 3 and how you can include them in your own widgets or plugins.

The technology employed here allows us to seamlessly update the state of the browser when performing AJAX requests. This permits the user to navigate using the browser’s back and forward buttons while at the same time offering backward compatibility with normal requests for the same resource.

The context of this video is technical in nature and best suited for viewers with a strong understanding of PHP, minPHP, javascript, and jQuery.

Click the icon in the bottom right of the video player to go full screen.

Tags: ajax | behind the scenes | blesta 3.0 | developer commentary | minphp | version 3

Blesta 3 offers a huge collection of programming tools for developers. From encryption to session handling, and everything in between. Today we’ll focus on the ins and outs of input validation using the Input component packaged with minPHP.

Input validation in version 3 is clear, concise, and modular. Rules reside within the business logic (the model). The benefit of this design is three fold:

1. No (or at least reduced) redundancy
2. Increased readability/writability
3. Reduced testing/less bugs

Some may argue the benefits of input validation from the first source (i.e. the controller). The folly of this design is its complexity and redundancy. Suppose a client can sign up through an order form, through a signup form, or be created by a staff member. Now you have three locations to test, update, and debug each time a business rule changes (for example, phone number is now required). Now suppose you need clients to be created through an API. Adding a fourth set of rules is just plain silly. A client is a client, regardless of where they originate, so why not consolidate all of this?

“Well, Cody,” you might say, “a phone number is only required when a client places an order so we need separate rules.” Hogwash! Add a parameter to your Clients::add() method to identify a signup via order to set the phone number rule as required.

Let’s look at a few examples.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

<?php
// /app/models/clients.php
class Clients extends AppModel {
	public function __construct() {
		Loader::loadComponents($this, array("Input"));
	}
 
	public function add(array $input) {
		// Input is coming straight from POST
		$rules = array(
			'first_name' => array(
				'empty' => array(
					'rule' => "isEmpty",
					'negate' => true,
					'message' => $this->_("Clients.!error.first_name.empty"),
					'post_format' => "trim"
				)
			),
			'last_name' => array(
				'empty' => array(
					'rule' => "isEmpty",
					'negate' => true,
					'message' => $this->_("Clients.!error.last_name.empty"),
					'post_format' => "trim"
				)
			),
			'email' => array(
				'format' => array(
					'rule' => "isEmail",
					'message' => $this->_("Client.!error.email.format"),
					'post_format' => "trim"
				)
			)
		);
 
		$this->Input->setRules($rules);
		if ($this->Input->validates($input)) {
			// Insert into the database, email, or do anything else needed when a client is added
		}
	}
}
?>

Let’s break this down.

• Line 5 loads the Input component (in reality this is already done in AppModel, but you ought to know how it happens)
• Lines 10 – 34 define our rules. For those who’ve worked with cakePHP this will look somewhat familiar.
• Lines 11, 19, and 27 are the indexes of the input data from our input array parameter. Evaluating arrays would look something like ‘addresses[]‘, or ‘addresses[][city]‘, etc.
• Lines 12, 20, and 28 begin individual rule sets. The labels here are superfluous (we could use numerically indexed elements instead), but these help us understand what’s expected of the rule. Any number of rule sets can be added.
• Each rule contains two necessary components:
  1. The ‘rule’ index, and
  2. The ‘message’ index
• The first defines how the input is evaluated. If the rule returns true the validation passes, if false, the validation fails. The message is what’s set for the error upon failure. In this example, and throughout Blesta, messages are language definitions which are translated before being set ($this->_() maps to Language::_()).
• Lines 14 and 22 tell the “isEmpty” rule to negate the response. Obviously we don’t want to require first and last names to be empty. Instead we want to ensure non-emptiness.
• Lines 16, 24, and 31 perform a formatting action on data after the rule is evaluated. Conversely, there’s a ‘pre_format’ action that formats the data before the rule is evaluated. Both ‘pre_action’ and ‘post_action’ work just like ‘rule’.
• Line 36 prepares the rules for evaluation
• Line 37 runs the validation, setting any errors that are encountered into the Input object, accessed via Input::errors(). AppModel defines a public method called “errors” to grant access to these errors from our controllers. As you’ve probably deduced, Input::validates() returns boolean true if validation was a success and false otherwise.

In the above example, all of the rules are defined within the Input component, but rules can consist of PHP functions (as seen on line 16), callbacks, or even boolean values. In addition, a rule can also define parameters. In any case, however, the first parameter to the rule is always the input value.

Below we look at an example of a rule set where the phone number is conditionally dependent on a method parameter, with a more complex rule.

35
36
37
38
39
40
41
42
43
44

		if ($order_signup) {
			$rules['phone'] = array(
				'format' => array(
					'rule' => array(array($this, "isPhone"), $input['country']),
					'if_set' => true,
					'message' => $this->_("Client.!error.phone.format"),
					'final' => true
				)
			);
		}

Notice we now have a couple new actions. The ‘if_set’ action allows the rule to be executed if and only if the field is set. The ‘final’ action tells us that if this rule does not pass evaluation then there’s no point in evaluating any other rules. Similarly, there’s another action called ‘last’ that will cease evaluating rules within a particular rule set (that is, for a single field).

Our rule is to execute a public class method and pass an additional parameter which will help us determine the correct format for the phone number based on the country. The signature of Clients::isPhone would look something like this:

public function isPhone($number, $country)

As you’ve seen, the Input component allows us to reuse code (one of the main goals behind object oriented programming), reduce redundancy, and create readable rules quickly and easily.

Tags: blesta 3.0 | data validation | input | minphp | version 3

Browsers have come a long way in preventing malicious scripts from compromising a user’s system, but XSS (Cross Site Scripting) still poses a security threat for developers. In version 3, we make use of a couple libraries packaged with the minPHP framework and recommend you do the same with your plugins, modules, or gateways. They are the Html and Form helpers.

In the previous article I showed how to eliminate SQL inection, but what do you do when a user submits some XSS code through a web form? Obviously parameter binding won’t help you there, so what do you do? Nothing. Well, at least for now, and here’s why:

1. Sanitizing input for XSS is expensive (both computationally, and economically). Web technologies change very frequently. What if W3C decides to add an “ontrippleclick” event?
2. Not all form data will end up in an HTML document. Some data is destined for emails or 3rd party APIs.
3. Sanitizing may make the data less or unsearchable by the database engine.

So when do we deal with this potentially hazardous data? Why, when we render it of course. And here’s how that’s done:

<div>Name: <?php $this->Html->_($name);?></div>

In the above example, Html::_() both sanitizes and prints the data, but we can force it to return the sanitized output by setting the 2nd parameter to false. Neat-o.

When used in a form, the Form helper will take care of drawing the form field and sanitizing the data.

<div>Name: <?php echo $this->Form->fieldText($name);?></div>

One thing to note is that we’re not destroying the XSS, we’re simply treating it as plain-text within an HTML document. While this takes care of most scenarios, there are some instances the Html helper can’t help you with. One such case is in dealing with the href attribute of an anchor tag. As a programmer you simply need to be aware of such pitfalls and address them accordingly.

Tags: blesta 3.0 | minphp | version 3 | xss

SQL injection is a serious concern for developers, and there are a number of ways of dealing with it; however the best, and most proven method, is through parameter binding. What parameter binding does is substitute variable data within a query with parameters, which are then replaced by the database driver during query execution. Since the database driver is intimately aware of which parts of the query are parameters it can parse the query and then execute it with the bound parameters safely set.

The framework that Blesta 3 is built on, minPHP, handles parameter binding through use of the PDO extension. But because writing queries is tedious and prone to typos, minPHP offers a database access object to interface with PDO in the Record class.

A query that would otherwise looks like this…

 
$this->query("SELECT `users`.`first_name`, `users`.`last_name` FROM `users` WHERE `id`=?", 3);

becomes…

 
$this->Record->select(array("users.first_name","users.last_name"))->from("users")->where("id", "=", 3);

No need to worry about syntax, semantics, escaping data, or back-ticks. That’s all handled by the computer, which loves performing tedious operations over and over.

We’ll look at how to overcome cross site scripting (XSS) vulnerabilities next week.

Tags: blesta 3.0 | minphp | security | sql injection

This is the first article, in what will be a series for Blesta 3.0, our next major release.

When we sat down to discuss the primary goals of Blesta 3.0, one of the first topics to come up was API design.  The two major issues we discovered with the original API design (of 1.0) were that:

1. It was limited in its capabilities
2. It was difficult and cumbersome to update

By implementing Blesta on top of an MVC framework (minPHP) we were able to create an automatic API, which eliminated both of these issues entirely.  Within an MVC application the model contains all of the business logic, so the only thing required to complete the API is a controller to handle access to the various models.  Since models are objects, the API controller can instantiate and access all of the public methods within a requested model.  This facilitates requests on logical objects that may perform specific actions.

In addition, the API controller could now fulfill requests in any number of various formats (e.g. json, xml, etc.).  The syntax was simple: /api/model/method.format.

The only thing necessary to complete the RESTful design were HTTP status codes, and the API controller easily handled those.  The result is an automatic RESTful API system, that not only grants access to the Blesta core, but to the back end of any plugins installed within that copy of Blesta as well.

In case you missed it, this means that ALL public model methods will be accessible through the API. We’re really excited about the new API and how much support it lends to developers.

Blesta 3.0 is currently in active development. A release date has not yet been determined.

Tags: api | blesta 3.0 | minphp | MVC | REST

           _       _____  _    _ _____
          (_)     |  __ \| |  | |  __ \
 _ __ ___  _ _ __ | |__) | |__| | |__) |
| '_ ` _ \| | '_ \|  ___/|  __  |  ___/
| | | | | | | | | | |    | |  | | |
|_| |_| |_|_|_| |_|_|    |_|  |_|_|
framework

minPHP is an extremely lightweight, object oriented MVC PHP framework brought to you by the same people who developed Blesta. minPHP is free, open source software released under the MIT license.

Download it at minphp.org.

One of the most awesome things about minPHP, aside from the fact that it’s awesome in itself, is that it’s being used as the framework for Blesta 3.0. Blesta 3.0 is in active development, with a release expected in the early part of next year.

We’re excited to be able to offer something to the open source community, and if you’re a developer we hope you give minPHP a try. As an added benefit, if you’re familiar with minPHP you’ll be a Blesta 3.0 development rockstar right out of the box.

Ooh, my spider-sense is tingling.

Tags: blesta 3.0 | minphp | php framework