What’s Google App Engine?

Google App Engine (GAE) is Google’s cloud computing Platform as a Service offering on which users deploy web applications that live in Google’s data centers. This means any application we deploy in the environment automatically inherits the stability, interoperability, and scalability of applications such as Gmail, Google+, and more.

While a full discussion of GAE is outside the scope of this article, suffice it to say that GAE is neither a private server nor a virtual private server – it’s a platform. As such, it has some limitations. You cannot simply install extensions in it, nor can you write to disk freely. You cannot alter resource limits on your own and you cannot install custom system tools. It isn’t your average Linux box; it’s a fully managed colossal environment for enterprise-level applications.

GAE has been steadily rising in popularity over the past few years, especially for deployment of Python 2 and JVM language (Java, Scala, Clojure) applications, but only recently at Google I/O was it announced that PHP support was added due to community interest.

GAE deployment is free up to a certain point. If your app exceeds the free usage quotas, you can request a paid upgrade. It’s a pay-as-you-use model which works best for large scale high-performance applications. As such, optimizing your application and reducing the number of requests is absolutely essential. Not only does it help performance, but it literally saves you money.

Transitioning to Google App Engine

GAE’s filesystem is read-only. The only way to write something to disk (such as file uploads, cache, custom logs, etc.) is to either use an external service like a read-write CDN or use a virtual filesystem like as gae-filestore (more information is available in the Google I/O video linked above and here) or Google Cloud Storage. Furthermore, there is no such thing as a local install of MySQL/MariaDB or PostgreSQL. Instead, you have the option of using Google Cloud SQL (which is similar to MySQL but with limitations and differences we won’t be covering here).

Needless to say, the PHP developer transitioning to a GAE environment has his work cut out for him. Thankfully the Google PHP team runs a blog (which is actually a WordPress installation on GAE) with helpful hints and tutorials, and the documentation for the still experimental PHP implementation is well done. For those interested in a simple overview, there’s also the quite clear Getting Started Guide.

I encourage you to check out all the linked resources to get as acquainted as much as possible with this new environment. GAE’s endorsement of PHP is a huge shift in the PHP community, and definitely has the potential to impact PHP development in the long run.

Essential PHP Extensions and Phalcon

People have already noted the huge downside of not being able to install extensions and have requested the addition of two essential ones: mbstring and iconv (which have since been installed), making GAE’s PHP runtime that much more usable. Seeing as how PHP support is still experimental and not ready for production, the GAE team is accepting and actively looking over suggestions for new installations and upgrades.

This is where Phalcon comes into play. Phalcon is a highly advanced PHP framework written in C and installed as a PHP extension. It offers all of the framework features you’re used to and much more, but with far greater performance (more speed, fewer resources) and robustness. Written in C, it executes natively and is loaded into memory when your server starts up, essentially enhancing PHP itself with some much needed missing features.

Phalcon is more PHP6 than PHP6 in itself in some ways, and enables you to write fast and secure applications in a fraction of the time it took to build them before. If you haven’t tried Phalcon out yet, I encourage you to do so – their documentation is very complete and thorough with examples for every API call.

The problem is the aforementioned inability to install custom extensions into GAE’s PHP, which means Phalcon is permanently unavailable to such environments. Due to Phalcon’s excellent performancef, it would be a shame if it weren’t implemented since it would undoubtedly reduce both Google’s server load and the cost app owners would be faced with. This is why I’ve opened a new feature request in GAE’s issue tracker which you can vote for. So far, it’s among the top 30 requested features.

Don’t take my word for it though – try out Phalcon and see how you like it. Chances are you’ll be voting for the issue moments later. Please vote exclusively by starring, however – not by commenting. Comments are there purely for the purpose of helping out with information and potential issues during installation. When a comment is made on Google Code, an email is sent to all people who starred the issue, which might result in some people un-starring if they feel like they’re being spammed ultimately hurting the effort.

Summary

GAE is a brand new opportunity for PHP. It has the potential to revolutionize the world of PHP development and the hosting options available to developers. To be part of this new age from the get-go, stay tuned for PHP-GAE tutorials and Phalcon guides on PHPMaster and follow the situations as they develop via the links in this article, in particular gaeforphp-blog.appspot.com. And don’t forget to check out Phalcon and vote for the issue to further the cause, and feel free to shoot me any questions via Google+ or in the comments below.

Most of us are familiar with “stacks” and “queues” in normal everyday usage. But, what do supermarket queues and vending machines have to do with data structures? Let’s find out. In this article, I will introduce you to two basic abstract data types – the Stack and the Queue – which have their conceptual origins in everyday usage.

Stacks

In common usage, a stack is a pile of objects which are typically arranged in layers – for example, a stack of books on your desk, or a stack of trays in the school cafeteria. In computer science parlance, a stack is a sequential collection with a particular property, in that, the last object placed on the stack, will be the first object removed. This property is commonly referred to as last in first out, or LIFO. Candy, chip, and cigarette vending machines operate on the same principle; the last item loaded in the rack is dispensed first.

In abstract terms, a stack is a linear list of items in which all additions to (a “push”) and deletions from (a “pop”) the list are restricted to one end – defined as the “top” (of the stack). The basic operations which define a stack are:

• init – create the stack.
• push – add an item to the top of the stack.
• pop – remove the last item added to the top of the stack.
• top – look at the item on the top of the stack without removing it.
• isEmpty – return whether the stack contains no more items.

A stack can also be implemented to have a maximum capacity. If the stack is full and does not contain enough slots to accept new entities, it is said to be an “overflow” – hence the phrase “stack overflow”. Likewise, if a pop operation is attempted on an empty stack, a “stack underflow” occurs.

Knowing that our stack is defined by the LIFO property and a number of basic operations, notably “push” and “pop”, we can easily implement a stack using arrays since arrays already provide push and pop operations.

Here’s what our simple stack looks like:

<?php
class ReadingList
{
    protected $stack;
    protected $limit;
    
    public function __construct($limit = 10) {
        // initialize the stack
        $this->stack = array();
        // stack can only contain this many items
        $this->limit = $limit;
    }

    public function push($item) {
        // trap for stack overflow
        if (count($this->stack) < self::$limit) {
            // prepend item to the start of the array
            array_unshift($this->stack, $item);
        } else {
            throw new RunTimeException('Stack is full!'); 
        }
    }

    public function pop() {
        if ($this->isEmpty()) {
            // trap for stack underflow
	      throw new RunTimeException('Stack is empty!');
	  } else {
            // pop item from the start of the array
            return array_shift($this->stack);
        }
    }

    public function top() {
        return current($this->stack);
    }

    public function isEmpty() {
        return empty($this->stack);
    }
}

In this example, I’ve used array_unshift() and array_shift(), rather than array_push() and array_pop(), so that the first element of the stack is always the “top”. You could use array_push() and array_pop() to maintain semantic consistency, in which case, the Nth element of the stack becomes the “top”. It makes no difference either way since the whole purpose of an abstract data type is to abstract the manipulation of the data from its actual implementation.

Let’s add some items to the stack:

<?php
$myBooks = new ReadingList();
$myBooks->push('A Dream of Spring');
$myBooks->push('The Winds of Winter');
$myBooks->push('A Dance with Dragons');
$myBooks->push('A Feast for Crows');
$myBooks->push('A Storm of Swords'); 
$myBooks->push('A Clash of Kings');
$myBooks->push('A Game of Thrones');

To remove some items from the stack:

<?php
echo $myBooks->pop(); // outputs 'A Game of Thrones'
echo $myBooks->pop(); // outputs 'A Clash of Kings'
echo $myBooks->pop(); // outputs 'A Storm of Swords'

Let’s see what’s at the top of the stack:

<?php
echo $myBooks->top(); // outputs 'A Feast for Crows'

What if we remove it?

<?php
echo $myBooks->pop(); // outputs 'A Feast for Crows'

And if we add a new item?

<?php
$myBooks->push('The Armageddon Rag');
echo $myBooks->pop(); // outputs 'The Armageddon Rag'

You can see the stack operates on a last in first out basis. Whatever is last added to the stack is the first to be removed. If you continue to pop items until the stack is empty, you’ll get a stack underflow runtime exception.

PHP Fatal error:  Uncaught exception 'RuntimeException' with message 'Stack is empty!' in /home/ignatius/Data Structures/code/array_stack.php:33
Stack trace:
#0 /home/ignatius/Data Structures/code/example.php(31): ReadingList->pop()
#1 /home/ignatius/Data Structures/code/array_stack.php(54): include('/home/ignatius/...')
#2 {main}
  thrown in /home/ignatius/Data Structures/code/array_stack.php on line 33

Oh, hello… PHP has kindly provided a stack trace showing the program execution call stack prior and up to the exception!

The SPLStack

The SPL extension provides a set of standard data structures, including the SplStack class (PHP5 >= 5.3.0). We can implement the same object, although much more tersely, using an SplStack as follows:

<?php
class ReadingList extends SplStack {}

The SplStack class implements a few more methods than we’ve originally defined. This is because SplStack is implemented as a doubly linked list, which provides the capacity to implement a traversable stack.

A linked list, which is another abstract data type itself, is a linear collection of objects (nodes) used to represent a particular sequence, where each node in the collection maintains a pointer to the next node in collection. In its simplest form, a linked list looks something like this:

In a doubly linked list, each node has two pointers, each pointing to the next and previous nodes in the collection. This type of data structure allows for traversal in both directions.

Nodes marked with a cross (X) denotes a null or sentinel node – which designates the end of the traversal path (i.e. the path terminator).

Since ReadingList is implemented as an SplStack, we can traverse the stack forward (top-down) and backward (bottom-up). The default traversal mode for SplStack is LIFO:

<?php
// top-down traversal
// default traversal mode is SplDoublyLinkedList::IT_MODE_LIFO|SplDoublyLinkedList::IT_MODE_KEEP
foreach ($myBooks as $book) {
  echo "$book\n"; // prints last item first!
}

To traverse the stack in reverse order, we simply set the iterator mode to FIFO (first in, first out):

<?php
// bottom-up traversal
$myBooks->setIteratorMode(
    SplDoublyLinkedList::IT_MODE_FIFO|SplDoublyLinkedList::IT_MODE_KEEP
);
foreach ($myBooks as $book) {
  echo $book . "\n";  // prints first added item first
}

Queues

If you’ve ever been in a line at the supermarket checkout, then you’ll know that the first person in line gets served first. In computer terminology, a queue is another abstract data type, which operates on a first in first out basis, or FIFO. Inventory is also managed on a FIFO basis, particularly if such items are of a perishable nature.

The basic operations which define a queue are:

• init – create the queue.
• enqueue – add an item to the “end” (tail) of the queue.
• dequeue – remove an item from the “front” (head) of the queue.
• isEmpty – return whether the queue contains no more items.

Since SplQueue is also implemented using a doubly linked list, the semantic meaning of “top” and “pop” are reversed in this context. Let’s redefine our ReadingList class as a queue:

<?php
class ReadingList extends SplQueue {}[

$myBooks = new ReadingList;

// add some items to the queue
$myBooks->enqueue('A Game of Thrones');
$myBooks->enqueue('A Clash of Kings');
$myBooks->enqueue('A Storm of Swords');

SplDoublyLinkedList also implements the ArrayAccess interface so you can also add items to both SplQueue and SplStack as array elements:

<?php
$myBooks[] = 'A Feast of Crows';
$myBooks[] = 'A Dance with Dragons;

To remove items from the front of the queue:

<?php
echo $myBooks->dequeue() . "\n"; // outputs 'A Game of Thrones'
echo $myBooks->dequeue() . "\n"; // outputs 'A Clash of Kings'

enqueue() is an alias for push(), but note that dequeue() is not an alias for pop(); pop() has a different meaning and function in the context of a queue. If we had used pop() here, it would remove the item from the end (tail) of the queue which violates the FIFO rule.

Similarly, to see what’s at the front (head) of the queue, we have to use bottom() instead of top():

<?php
echo $myBooks->bottom() . "\n"; // outputs 'A Storm of Swords'

Summary

In this article, you’ve seen how the Stack and Queue abstract data types are used in programming. These data structures are abstract, in that they are defined by the operations that can be performed on itself, thereby creating a wall between its implementation and the underlying data.

These structures are also constrained by the effect of such operations: You can only add or remove items from the top of the stack, and you can only remove items from the front of the queue, or add items to the rear of the queue.

Image by Alexandre Dulaunoy via Flickr

I’ll be using MongoDB for our discussion as it is one of the leading open-source NoSQL databases due to its simplicity, performance, scalability, and active user base. Of course the article assumes that you are aware of basic MongoDB concepts (like collections and documents). If not, I suggest you read some of the previous articles here at PHPMaster to get started with MongoDB.

Understanding Relationships

Relationships show how your MongoDB documents are related to each other. To understand the different ways in which we can organize our documents, let’s look at the possible relationships.

1-to-1 Relationship (1:1)

A 1:1 relationship exists when one object of an entity is related to one and only one object of another entity. For example, one user can have one and only one birth date. So if we have a document which stores user information and another document which stores birth dates, there will be a 1:1 relationship between them.

1-to-Many Relationship (1:N)

Such relationship exists when one object of an entity can be related to many objects of another entity. For example, there can be 1:N relationship between a user and his contact numbers since it is possible for one user to have more than one number.

Many-to-Many Relationship (M:N)

Such relationship exists when one object of an entity is related to many objects of another entity and vice versa. If we correlate it to the case of users and items bought by them, one user can purchase more than one items as well as one item can be purchased by more than one user.

Modeling 1-to-1 Relationships (1:1)

Consider the following example where we need to store address information for each user (for now let’s assume that there’s a single address for each user). In this case, we can design an embedded document having the following structure:

{
    "_id": ObjectId("5146bb52d8524270060001f4"),
    "user_name": "Mark Benzamin" 
    "dob": "12 Jan 1991",
    "address": {
       "flat_name": "305, Sunrise Park",
       "street": "Cold Pool Street",
       "city": "Los Angeles" 
    }
}

We have the address entity embedded within the user entity making all of the information present in a single document. This means we can find and retrieve everything with a single query.

<?php
// query to find user 'Mark Benzamin' and his address 
$cursor = $collection->find(
    array("user_name" => "Mark Benzamin"),
    array("user_name" => 1,"address" => 1)
 );

Embedding documents is roughly analogous to de-normalization and is useful when there is a “contains” relationship between two entities. That is, one document can be stored within another, thus placing the related pieces of information within a single document. As all the information is available in one document, such approach has better read performance because a query operation within a document is less expensive for the server and we find and retrieve the related data in the same query.

In contrast, a normalized approach would call for two documents (ideally in separate collections), one to store basic user information and another to store address information. The second document would contain a user_id field indicate the user to which the address belongs.

{
    "_id": ObjectId("5146bb52d8524270060001f4"),
    "user_name": "Mark Benzamin",
    "dob": "12 Jan 1991"
}

{
    "_id": ObjectId("5146bb52d852427006000de4"),
    "user_id": ObjectId("5146bb52d8524270060001f4"), 
    "flat_name": "305, Sunrise Park",
    "street": "Cold Pool Street",
    "city": "Los Angeles" 
}

We now need to execute two queries to fetch the same data:

<?php
// query to find user information
$user = $collection->findOne(
    array("user_name" => "Mark Benzamin"),
    array("_id" => 1, "user_name" => 1)
);

// query to find address corresponding to user
$address = $collection->findOne(
    array("user_id" => $user["_id"]),
    array("flat_name" => 1, "street" => 1, "city" => 1)
);

The first query fetches the _id of the user which is then used in the second query to retrieve his address information.

The embedding approach makes more sense than the referencing approach in this case since we are frequently retrieving user_name and address together. What approach you should use ultimately depends on how you logically connect your entities and what data you need to retrieve from the database.

Modeling Embedded 1-to-Many Relationships (1:N)

Now let’s consider the case where one user can have multiple addresses. If all of the addresses should be retrieved along with the basic user information, it would be ideal to embed the address entities inside the user entity.

{
    "_id": ObjectId("5146bb52d8524270060001f4"),
    "user_name": "Mark Benzamin"
    "address": [
        {
            "flat_name": "305, Sunrise Park",
            "street": "Cold Pool Street",
            "city": "Los Angeles"
        },
        {
            "flat_name": "703, Sunset Park",
            "street": "Hot Fudge Street",
            "city": "Chicago" 
        }
    ]
}

We’re still able to fetch all of the required information with a single query. The referencing/normalized approach would have us design three documents (one user, two addresses) and two queries to accomplish the same task.
Besides efficiency and convenience, we should use the embedded approach in instances where we need atomicity in operations. Since any updates happen within the same document, atomicity is always insured.

Modeling Referenced 1-to-Many Relationships (1: N)

Bear in mind that embedded documents can continue to grow in size over the life of an application which can badly impact write performance. There’s also a limit of 16MB on the maximum size of each document. A normalized approach is preferred if the embedded documents would be too large, when the embedding approach would result in a lot of duplicate data, or if you need to model complex or hierarchical relationships between documents.

Consider the example of maintaining posts made by a user. Let’s assume that we want the user’s name and his profile picture with every post (similar to a Facebook post where we can see a name and profile picture with every post). The denormalized approach would store the user information in each post document:

{
    "_id": ObjectId("5146bb52d8524270060001f7"),
    "post_text": "This is my demo post 1", 
    "post_likes_count": 12, 
    "user": {
        "user_name": "Mark Benzamin",
        "profile_pic": "markbenzamin.jpg"
    }
}

{
   "_id": ObjectId("5146bb52d8524270060001f8"),
   "post_text": "This is my demo post 2", 
   "post_likes_count": 32, 
    "user": {
        "user_name": "Mark Benzamin",
        "profile_pic": "markbenzamin.jpg"
    }
}

We can see this approach stores redundant information in each post document. Looking a bit forward, if the user name or profile picture was ever changed, we would have to update the appropriate field in all of the corresponding posts.
So the ideal approach would be to normalize the information and connect it via references.

{
    "_id": ObjectId("5146bb52d852427006000121"),
    "user_name": "Mark Benzamin",
    "profile_pic": "markbenzamin.jpg"
}

{
    "_id": ObjectId("5146bb52d8524270060001f7"),
    "post_text": "This is my demo post 1", 
    "post_likes_count": 12, 
    "user_id": ObjectId("5146bb52d852427006000121")
}

{
    "_id": ObjectId("5146bb52d8524270060001f8"),
    "post_text": "This is my demo post 2", 
    "post_likes_count": 32, 
    "user_id": ObjectId("5146bb52d852427006000121")
}

The user_id field in the post document contains a reference to the user document. Thus, we can fetch posts made by the user using two queries as follows:

<?php
$user = $collection->findOne(
    array("user_name" => "Mark Benzamin"),
    array("_id" => 1, "user_name" => 1, "profile_pic" => 1)
); 

$posts = $collection->find(
    array("user_id" => $user["_id"])
);

Modeling Many-to-Many Relationships (M:N)

Let’s take our previous example of storing users and the items they purchased (ideally in separate collections) and design referenced documents to illustrate the M:N relationship. Assume the collection which store documents for user information is as follows such that each document contains reference IDs for the list of items purchased by the user.

{                                 
    "_id": "user1",
    "items_purchased": {
        "0": "item1",
        "1": "item2" 
    } 
}

{
    "_id": "user2",
    "items_purchased": {
        "0": "item2",
        "1": "item3" 
    } 
}

Similarly, assume another collection storing the documents for the available items. These documents will in turn store reference IDs for the list of users who have purchased it.

{                                 
    "_id": "item1",
    "purchased_by": {
        "0": "user1"
    } 
}

{                                 
    "_id": "item2",
    "purchased_by": {
        "0": "user1",
        "1": "user2" 
    } 
}

{                                 
    "_id": "item3",
    "purchased_by": {
        "0": "user2"
    } 
}

To fetch all the items purchased by a user, we would write the following query:

<?php
// query to find items purchased by a user
$items = $collection->find(
    array("_id" => "user1"),
    array("items_purchased" => 1)
);

The above query will return the IDs of all the items purchased by user1. We can later use these to fetch the corresponding item information.

Alternatively, if we wanted to fetch the users who have purchased a specific item, we would write the following:

<?php
// query to find users who have purchased an item
$users = $collection->find(
    array("_id" => "item1"),
    array("purchased_by" => 1)
);

The above query returns the IDs of all the users who have purchased item1. We can later use these IDs to fetch the corresponding user information.

This example demonstrated M:N relationships which are very useful in some cases. However, you should keep in mind that many times such relationships can be handled using 1:N relationships along with some smart queries. This reduces the amount of data to be maintained in both documents.

Conclusion

That’s it for this article. We’ve learned about some basic modeling concepts which will surely help you head start your own data modeling: 1-to-1, 1-to-many, and many-to-many relationships, and also a little about data normalization and de-normalization. You should be able to easily apply these concepts to your own application’s modeling needs. If you have any questions or comments related to the article, feel free to share in the comments section below.

Installing the WordPress E-commerce Plugin

The first thing you need to do is to install WordPress. Don’t worry; it’s a straight-forward process that’s well documented here: codex.wordpress.org/Installing_WordPress.

Beyond a WordPress installation (version 3.5+), you’ll also need the following things:

• fsockopen support (for payment gateway IPN access).
• an SSL certificate if you choose to install any direct payment gateways
• cURL support (optional) – some plugins for WooCommerce require cURL.
• SOAP support (optional) – some plugins for WooCommerce require SOAP.

Once WordPress is installed, log in to the dashboard with the admin password you chose and familiarize yourself with the menu on the left. The dashboard is an important place where you’ll customize and manage your site to suit your needs.

Next you need to install WooCommerce. There’s two ways you can do this:

1. The automatic installer – go to Plugins -> Add New, search for “WooCommerce”, and add the plugin. You’ll need to enter your FTP credentials if this is the first time you’re doing this.
2. Manually – Download the plugin from wordpress.org/extend/plugins/woocommerce, unzip the archive, and place the folder in wp-content/plugins.

After you have installed WooCommerce, go to Plugins -> Installed Plugins and activate the WooCommerce plugin.

Configuring WooCommerce

Now that the plugin is activate, click WooCommerce in the side menu. Add WooCommerce Pages by pressing the button labeled “Install WooCommerce Pages” in the banner that comes up.

Then press the Settings button on the welcome page to reach the following page:

There’s a lot of settings on this page, but let’s focus on the ones you need to make a bookstore with PayPal as your payment provider.

General

The general settings speak for themselves. The only things I changed for my own setup was the country to Netherlands and the currency to Euros.

Taxes

You’ll need to have a little bit of tax knowledge to run a webshop. Under the Tax tab, I clicked the small link at the top that reads “Standard” to enter standard tax rates, and added the Dutch BTW tax (which is 21%). The taxes and their amount vary per location, so be sure to check the rules that apply to you. Because tax rules are different depending on where you are, I can’t provide detailed information beyond this is where you fill in the rates.

If you’re unsure, I recommend calling your local tax office and ask how much you’re allowed to earn and what kind of tax papers you’ll need for your specific store. Setting up a webshop is easy, but dealing with taxes is harder. After all, you don’t want to be accused of committing tax fraud!

Customers

To enable customers, go back to the General tab and check the appropriate boxes in the Registration and Customer Accounts sections. For my store, I chose the options below:

Enabling PayPal

To enable PayPal integration, go to the Payment Gateways tab and press the small PayPal link at the top. For the sake of this article I’ll show you how to enable the PayPal sandbox since we don’t want to deal with real money in a fake store!

Go to developer.paypal.com and login with your existing PayPal account (if you don’t have one, sign up for one). Click the site’s “Applications” menu item and then “Sandbox accounts”. It’s here where you’ll make a new test account.

Create a customer account to test purchases. Fill in the form just as you would a normal account. When it comes to entering a balance, this is all fake money so I like to enter a million here. One can dream…

Go back to your webshop site again, and in the PayPal link from earlier fill in the e-mail address of your created sandbox account.

If you’re testing locally, payments won’t fully work. They’ll start working once you have the site up and running on an actual domain.

Customizing your Store

You now have a fully functional webshop, but it doesn’t really look much like a shop. We need to add some products and select a theme.

Adding Products

In the side menu you’ll see a Products category. Click it, then select Add Product and fill in the information for a new product. This is a pretty straight forward process.

For the sake of example, let’s add a “PHP book” for 20 euros. Let’s also add a “PHP e-book” with a download link (check the “Virtual” and “Downloadable” boxes to make a downloadable product). You can set the product image with the Featured Image feature, and add any additional images using the Product Gallery.

Adding a Theme

There are several themes for WooCommerce at woothemes.com/product-category/themes/woocommerce, but of course you’re also free to roll your own or customize an existing theme as you please. For the purpose of this article, we want to have the shop up and running as soon as possible, so let’s use mystile, a clean free theme. You do however need to register before downloading it.

The process of adding a theme is similar to adding a plugin; to install it manually, add it to wp-content/themes and activate it by going to Appearance -> Themes in the side menu and press “Activate” under the theme.

This theme has a selection of settings available in the side menu under Mystile, so feel free to try out the different options to make it look and feel the way you want.

If you get a PHP warning in the bottom of the new homepage, it most likely means you need to update your copy of WooFramework. You can do so by going to Mystile -> Update Framework.

Changing the Menu

We probably don’t need the checkout pages to be available in the site’s menu, so let’s change the menu by going to Appearance -> Menus and make a new menu in the Plus sign tab. Name it whatever you want; I chose to name mine “Main menu”.

Then in the Pages box select the pages you want. I added Home:Home, Cart, Shop, My Account, and every subpage under My Account. Be sure that you drag the subpages into position by having them intended under My Account. Once the menu is saved, select it under the “Theme Locations primary menu” dropdown.

Extra Cleanup

Remove the sample page by going to Pages -> All Pages in the side menu and remove it from there. You may also want to remove the visible sidebar from some of the pages. You can do this by clicking the page’s Quick Edit link and setting its template to “Full Width”.

The URLs don’t look very nice, either. Instead of something like http://wordpress.dev/?post_type=product you might prefer to have something like http://wordpress.dev/products. Go to Settings -gt; Permalinks and under the Common Settings section choose “Post name”.

You may also want to change the permalinks for the specific products. Under the Product permalink base section I chose “Shop base with category” to get a nice, sharable link.

Conclusion

Congratulations, you’ve successfully created a webshop. If you didn’t run into any problems, this process probably took you less than an hour, maybe two hours with reading this article. That’s how easy it is to get up and running with WordPress and WooCommerce!

WooCommerce is an Open Source project, so if you feel like extending it even further, please check them out on GitHub!

Image via Fotolia

Facade is a design pattern used in almost every web application, but often without knowing. The term “design pattern” creates a mental image of something complex and difficult to understand. Even though this can be true sometimes, the Facade pattern is simple to implementation. Let’s see what Facade is and what it does to help us write good code.

The Process of Borrowing a Book

Assume that we’re developing an application for a library management system. Borrowing and returning books are obviously the two most important tasks of such systems. But consider a typical implementation of the book borrowing process:

• A user comes to the library and returns her borrowed books so she can borrow new ones.
• The user must pay a fine for overdue books.
• The user, or a member of the library staff, searches for a new book.
• The availability of the book is verified.
• If the steps above are successfully completed, the location of the book must be retrieved.
• The user borrows the book.
• The status of the book is marked as unavailable in the system.

The implementation of each task is contained in separate classes with their own interfaces. The following code illustrates how a system might let the user borrow a book by calling the necessary methods:

<?php
public class User
{
    public function borrowBook() {
        $bookManager = new Book_Manager();
        $bookManager->returnBooks();

        $bookPayments = new Book_Payments();
        if ($bookPayments->hasOverdueBooks()) {
            $bookPayments->payBookFines();
        }

        $bookLibrary = new Book_Library();
        $bookReservations = new Book_Reservations();

        $book = $bookLibrary->searchBooks();
        $isAvailable = $bookLibrary->isBookAvailable($book);
        $isReserved = $bookReservations->isBookReserved($book); 
        if ($isAvailable && !isReserved) {
            $bookLibrary->locateBook($book);

            $bookManager->borrowBook($book);
            $bookLibrary->updateBookAvailability($book, $status);
        }
    }
}

You can see the process of borrowing a book is actually a complex process! In this implementation, a user has to interact with four different classes and around ten methods to borrow a book.

Assume that each bit of functionality is implemented as a separate screen in the application; can you imagine the effort required for borrowing three books with this system? And the borrower doesn’t need to know about functionality such as checking reservations and updating the status. We certainly have a problem with our implementation.

Implementing a Library Facade

We need to decouple the user from the complex workflow of the library and allow for a simplified interface exposing just the information directly related to a user – a facade. Let’s see the implementation of the library facade.

<?php
class Library_Facade
{
    public function returnBooks() {
        // previous implementation by calling necessary classes
    }

    public function borrowBooks() {
    }

    public function searchBooks() {
    }

    public function reserveBooks() {
    }
}

The user can borrow books by calling the borrowBook() method of the Library_Facade class as shown in the following example:

<?php
class User
{
    public function borrowBook() {
        $libraryFacade = new Library_Facade();
        $libraryFacade->borrowBook();
    }
}

With this facade-based implementation, the user only talks to the Library_Facade class and has no idea how the functionality is implemented beyond it. A user can directly request any feature from the facade and the facade is responsible for handling the complex process and returning the appropriate information. The Facade pattern adheres to the principle of least knowledge in which each unit should have minimal knowledge about the other units.

Even though the low-level functionality is hidden from the user through the facade, the user can still request low-level classes directly when needed. Think about your own projects and where you might find situations where you’ve implemented the Facade pattern without even realizing it.

Facade Pattern Definition

Since we’ve identified the process and importance of implementing the Facade pattern, now it’s time to learn the definition of the pattern. The following is extracted from Wikipedia:

A facade is an object that provides a simplified interface to a larger body of code, such as a class library. A facade can:

• make a software library easier to use, understand, and test since the facade has convenient methods for common tasks;
• make the library more readable, for the same reason;
• reduce dependencies of outside code on the inner workings of a library, since most code uses the facade allowing more flexibility in developing a system;
• wrap a poorly designed collection of APIs with a single well-designed API.

Here’s a class diagram of our library example that identifies the components mentioned in the Facade pattern definition.

Real World Implementations

In the previous sections we learned the theory behind the Facade pattern using a library system as an example. In the real world, facades can be much more complex than the implementation in our library scenario. Let’s review some implementations of the pattern in the context of real-world applications and libraries.

Opauth for Open Authentication

I recently wrote an article about a popular Open Authentication library called Opauth, and I suggest you read it if you haven’t already. Assume we’ve developed a professional social network site and we want our users to be able to use other popular sites such as Twitter, LinkedIn, and Facebook to authenticate. To complete the authentication process we use existing third-party libraries for accessing the networks’ services. Let’s look at some sample code for with a Twitter library for achieving the desired functionality.

<?php
$toauth = new TwitterOAuth('consumer key', 'consumer secret');

$request_token = $toauth->getRequestToken('http://exmaple.com/twitter_oauth.php');

$_SESSION['oauth_token'] = $request_token['oauth_token'];
$_SESSION['oauth_token_secret'] = $request_token['oauth_token_secret'];

if ($toauth->http_code == 200) {
    $url = $toauth->getAuthorizeURL($request_token['oauth_token']);
    header('Location: '. $url);
}
else {
    // Generate error
}

As you can see, we call a set of Twitter-specific library methods to implement the desired functionality. A similar approach would be necessary for both LinkedIn and Facebook. The process has already become complex. We’re not developing a Twitter, Facebook, or Linkedin application; we should just validate the credentials and authenticate the user. Our application shouldn’t be worried about the implementation of each of these services.

We can solve this problem by using the Opauth library as a facade interface. First we need to specify the login URLs of the desired services in a common format to be identified by the Opauth plugin. Consider the following code for implementing the authentication process.

<?php
public function login($stratergy = '') {
    if ($stratergy != '') {
        $this->opauth_lib->initialize();
    }
}

Once the login link is requested, Opauth identifies the requested service from the URL and initializes the library to redirect the user for authentication. Our application now only needs to create the login links and call the initialize method. All of the complex authentication stuff is handled behind-the-scenes using the respective libraries for each service. This can be considered a perfect example for effectively using the Facade pattern.

WordPress Meta Functions

WordPress is not one of the most popular frameworks among serious PHP developers considering the quality of its code. But we can easily find a number of successful facade implementations inside the WordPress codebase. Here I’ll take a look at the update_post_meta() function for saving custom data for WordPress posts.

WordPress allows us to create custom fields associated with existing posts. Think of how we save these fields in a usual situation… we have to implement all the following tasks:

• Validate the field data
• Filter the data for HTML tags, scripts, and SQL injections
• Check the existence of the field in database
• Save or update the record based on the existence status

That’s quite a lot of work to save one single custom field! WordPress hides the complexity of saving these fields by providing a built-in function called update_post_meta() to act as a facade. This permits us to focus on passing the necessary data related to our application; all of the aforementioned tasks are hidden from the user.

Now consider the implementation of update_post_meta() to identify its functionality as a facade:

<?php
function update_post_meta($post_id, $meta_key, $meta_value, $prev_value = '') {
    // make sure meta is added to the post, not a revision
    if ($the_post = wp_is_post_revision($post_id))
        $post_id = $the_post;

    return update_metadata('post', $post_id, $meta_key, $meta_value, $prev_value);
}

function update_metadata($meta_type, $object_id, $meta_key, $meta_value, $prev_value = '') {
    // expected_slashed ($meta_key)
    $meta_key = stripslashes($meta_key);
    $passed_value = $meta_value;
    $meta_value = stripslashes_deep($meta_value);
    $meta_value = sanitize_meta($meta_key, $meta_value, $meta_type);

    $check = apply_filters("update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value);
    if (null !== $check)
        return (bool) $check;

    // Compare existing value to new value if no prev value given and the key exists only once.
    if (empty($prev_value)) {
        $old_value = get_metadata($meta_type, $object_id, $meta_key);
        if (count($old_value) == 1) {
            if ($old_value[0] === $meta_value)
                return false;
        }
    }

    $wpdb->update($table, $data, $where);
}

Only the necessary code is shown; the complete source code for the update_metadata() function is available in meta.php file inside the wp-includes directory. But you can see all of the validation, filtering, and database updates are implemented here and only the facade interface has knowledge about the details.

Conclusion

Facade is one of the most simple and easy to use design patterns in software development. Throughout this article I talked about various implementations of the Facade pattern. Now it’s time to share your experiences in the comments below. Do you know of any library or service that makes use of facades? Feel free to share the practical implementations of the Facade pattern you’ve come across.

Image via Fotolia

What’s a Pipe?

To understand how proc_open() and the process sends and receives data, you know know what a pipe is.

The Unix Philosophy lead early developers to write many small programs each with very specific functionality. These programs shared plain text as a common format, and users could “chain them together” for greater functionality. The output from one command become the input for the next. The virtual channels that let the data flow between commands became known as pipes.

If you’ve ever worked in a Unix shell then there’s a good chance you’ve used pipes, perhaps even without realizing it. For example:

$ mysql -u dbuser -p test < mydata.sql

Here the mysql utility is invoked and a pipe is set up by the system through which the contents of the mydata.sql file is fed into mysql as if you were typing directly at it’s prompt from your keyboard.

There are two types of pipes: anonymous and named. An anonymous pipe is ad hoc, created only for as long as the process is running and is destroyed once it is no longer needed. The example with redirecting the file contents into mysql above uses an anonymous pipe. A named pipe on the other hand is given a name and can last indefinitely. It’s created using special commands and often appears as a special file in the filesystem.

Regardless of the type, an important property of any pipe is that it’s a FIFO (first in, first out) structure. This means the data written into a pipe first by one process is the first data read out from the pipe by the other process.

Introducing proc_open()

The PHP function proc_open() executes a command, much like exec() does, but with the added ability to direct input and output streams through pipes. It accepts some optional arguments, but the mandatory arguments are:

• a command to execute.
• an array that describes the pipes to be used.
• an array reference that will later be populated with references to the pipes’ endpoints so you can send/receive data.

The optional arguments are used for tweaking the execution environment in which the command spawns. I won’t discuss it here, but you can find more information in the PHP manual.

Aside from the command to execute, I would say the descriptor array that defines the pipes is the most important argument to pay attention to. The documentation explains it as an “indexed array where the key represents the descriptor number and the value represents how PHP will pass that descriptor to the child process,” but what exactly does that mean?

The three main data streams for a well-behaved unix process are STDIN (standard input), STDOUT (standard output), and STDERR (standard error). That is, there’s a stream for incoming data, one for outgoing data, and a second outgoing stream for informational messages. STDIN has traditionally been represented by the integer 0, STDOUT by 1, and STDERR by 2. So, the definition with key 0 will be used to set up the input stream, 1 for the output stream, and 2 for the error stream.

These definitions themselves can take one of two forms, either an open file resource or an array that describes the nature of the pipe. For an anonymous pipe, the first element of the descriptive array is the string “pipe” and the second is “r”, “w”, or “a” depending if the pipe is to be read from, written to, or appended. For named pipes, the descriptive array holds the string “file”, the filename, and then “r”, “w”, or “a”.

Once called, proc_open() fills the third parameter’s array reference to return the resources to the process. The elements in the reference can be treated as normal file descriptors and they work with file and stream functions like fwrite(), fread(), stream_get_contents(), etc.

When you’re done interacting with the external command, it’s important to clean up after yourself. You can close the pipes (with fclose()) and the process resource (with proc_close()).

Depending on how your target command/process behaves, you may need to close the STDIN connection before it begins its work (so it knows not to expect any more input). And, you should close the STDOUT and STDERR connections before closing the process, or it might hang while it waits for everything to be clean before shutting down.

A Practical Example: Converting Wiki Markup

So far I’ve only talked about how things work, but I haven’t shown you an example using proc_open() to spawn and communicate with an external process yet. So, let’s see how easy it is to use.

Suppose we have a need to convert a chunk of text with wiki markup to HTML for display in a user’s browser. We’re using the Nyctergatis Markup Engine (NME) to perform the conversion, but since it’s a compiled C binary we need a way to fire up nme when its needed and a way to pass input and receive output.

<?php
// descriptor array
$desc = array(
    0 => array('pipe', 'r'), // 0 is STDIN for process
    1 => array('pipe', 'w'), // 1 is STDOUT for process
    2 => array('file', '/tmp/error-output.txt', 'a') // 2 is STDERR for process
);

// command to invoke markup engine
$cmd = "nme --strictcreole --autourllink --body --xref";

// spawn the process
$p = proc_open($cmd, $desc, $pipes);

// send the wiki content as input to the markup engine 
// and then close the input pipe so the engine knows 
// not to expect more input and can start processing
fwrite($pipes[0], $content);
fclose($pipes[0]);

// read the output from the engine
$html = stream_get_contents($pipes[1]);

// all done! Clean up
fclose($pipes[1]);
fclose($pipes[2]);
proc_close($p);

First the descriptor array is laid out, with 0 (STDIN) as an anonymous pipe that will be readable by the markup engine, 1 (STDOUT) as an anonymous pipe writable by the engine, and 2 (STDERR) redirecting any error messages to an error log file.

The “r” and “w” on the pipe definitions might seem counter intuitive at first, but keep in mind they are the channels that the engine will be using and so are configured from it’s perspective. We write to the read pipe because the engine will be reading the data from it. We read from the write pipe because the engine has written data to it.

Conclusion

There are many ways to interact with external processes; some may be better than using proc_open() given how and what you need to work with, or proc_open() might just be what the doctor ordered for your situation. Of course you’ll implement what makes sense, but now you’ll know how to use this powerful function if you need to!

I’ve placed some example code on the PHPMaster GitHub page that simulates a bare-bones wiki using NME, just like in the example above. Feel free to clone it if you’re interested in playing and exploring further.

Image via Fotolia

Before we talk about recursion, though, let’s take a look at this snippet of code:

<?php
function factorial($number) {
    if ($number < 0) {
        throw new InvalidArgumentException('Number cannot be less than zero');
    }
    $factorial = 1;	
    while ($number > 0) {
        $factorial *= $number;
        $number --;
    }
    return $factorial;
}

A factorial is the result of a number multiplied by all positive integers less than that number, and the function above calculates the factorial of any number given to it using a simple loop. Now let’s rewrite the example this way:

<?php
function factorial_recursive($number) {
    if ($number < 0) {
        throw new InvalidArgumentException('Number cannot be less than zero');
    }
    if ($number == 0) {
        return 1;
    }
    return $number * factorial_recursive($number – 1);
}

We get the same results when we call both functions, but notice that the second function calculates the factorial by calling itself. This is known as recursion.

What’s Recursion?

A recursive function is one that calls itself, either directly or in a cycle of function calls.

Recursion can also refer to a method of problem solving that first solves a smaller version of the problem and then uses that result plus some other computation to formulate an answer to the original problem. Often times, in the process of solving the smaller version, the method will solve yet a smaller version of the problem, and so on, until it reaches a “base case” which is trivial to solve.

To write a recursive function, you need to provide it with some means of return or else it will keep calling itself for eternity (or until the call stack blows up, the script times out, or memory is exhausted). This is known as a guard clause or base case.

The simplest form of a recursive function is as follows:

<?php
function my_recursive_func (args) {
    if (simplest case) {
        // The Base Case/Guard Clause that stops the
        // function from running forever
        return simple value;
    }
    else {
        //call function again with simpler args
        my_recursive_func(argsSimplified);
    }
}

Types of Recursion

When a function calls itself directly, it is referred to as direct recursion. A function in a cycle of function calls that eventually invokes itself is called indirect recursion. Look at the example below of indirect recursion:

<?php
function A($num) {
    $num -= 1;
    if($num > 0) {	
        echo "A is Calling B($num)\n";
        $num = B($num);
    }
    return $num;
}

function B($num) {
    $num -= 2;
    if($num > 0) {
        echo "B is Calling A($num)\n";
        $num = A($num);
    }
    return $num;
}

$num = 4;
echo "Calling A($num)\n";
echo 'Result: ' . A($num);

Calling A(4) 
A is Calling B(3) 
B is Calling A(1) 
Result: 0

The above example is really useless code just meant to show you how a function can call itself indirectly through another function. Calling either A(n>4) or B(n>4) causes the called function to be called from the other function.

It’s important to know a function can call itself indirectly like this, but in this article we’ll only deal with direct recursion.

A Practical Example

To show you how powerful recursion can be, we’ll write a function that searches for a key within an array and returns the result.

<?php
function find_in_arr($key, $arr) {
    foreach ($arr as $k => $v) {
        if ($k == $key) {
            return $v;
        }		
        if (is_array($v)) {
            foreach ($v as $_k => $_v) {
	        if ($_k == $key) {
                    return $_v;
                }
            }
        }
    }
    return false;
}

$arr = [
    'name' => 'Php Master',
    'subject' => 'Php',
    'type' => 'Articles',
    'items' => [
        'one' => 'Iteration',
        'two' => 'Recursion',
        'methods' => [
            'factorial' => 'Recursion',
            'fibonacci' => 'Recursion',
        ],
    ],
    'parent' => 'Sitepoint',
];

var_dump(
    find_in_arr('two', $arr),
    find_in_arr('parent', $arr),
    find_in_arr('fibonacci', $arr)
);

string 'Recursion' (length=9)
string 'Sitepoint' (length=9)
boolean false

Things are all well and good, but notice that we iterate only two levels deep into the array, and so the search for “Fibonacci” in the third level fails. If we want to search an array of indeterminate depth, this would not suffice. We can instead rewrite the search as a recursive function:

<?php
function find_in_arr($key, $arr) {
    foreach ($arr as $k => $v) {
        if ($k == $key) {
            return $v;
        }
        if (is_array($v)) {
            $result = find_in_arr($key, $v);
            if ($result != false) {
                return $result;
            }
        }
    }	
    return false;
}

With the recursive function, we can search an array several levels deep since we have not hardcoded how deep the function goes. It just keeps running until it goes over all of the values in the array.

Head and Tail Recursion

In all of the examples so far we’ve been using what is called head recursion. When the function calls itself, it waits for the result from the call before returning a value of its own. It is possible to write functions in such a way that they do not operate on returned values, but instead pass all required values as parameters. This is known as a tail call (or tail recursion). This method is usually preferred as a language’s runtime can sometimes optimize the calls so that there’s no danger of blowing up the call stack, but PHP does not do this.

Below is our factorial example modified to make a tail call. Note that the result of the recursive call is returned, instead of manipulated further.

<?php
function factorial ($number, $factorial = 1) {
    if ($number < 0) {
        throw new InvalidArgumentException('Number cannot be less than zero (0)');
    }
    if ($number == 0) {
        return $factorial;
    }
    else {
        return factorial($number - 1, $factorial * $number);
    }
}

General Advice

Any code that can be written iteratively can also be written recursively. However, this is not always easy to do (or even wise to do). Recursion shines when traversing trees and lists or performing most O(n log n) sorts. When you need to divide a repetitive problem up, recursion will fit better than an iterative approach, as in the case of searching within the file system and you need to enter any subdirectories to search within as well. Where there’s the traversal of an indeterminate depth, recursion works great.

Keep in mind that PHP does not optimize recursive functions, even if you write them to make tail calls, and recursive functions in general are less efficient and slower than their iterative counterparts, though they sometimes do the job better as shown in the code samples above. Recursion is usually a favored alternative to iteration in functional programming and therefore most functional languages optimize recursive functions.

If you’re using XDebug, be sure to inspect your system’s configuration. By default you’ll have a limit of 100 recursive calls and if you exceed this, your script will throw a “maximum nested limit reached” error. You can update the debug.max_nesting_level config value if you need to change this.

Finally, it’s a good idea to read an explanation of stack heap and recursion causing stack overflow to understand what happens to the call stack during recursion.

Conclusion

In this article I’ve given you a broad look at recursion and how it compares to iteration. I’ve also show you how to write recursive functions, when to write them, and why. I have also tried warn you of some of the pitfalls that you might fall into when using recursion.

Recursion is such that even many experienced programmers can go years without using it and many others have never even heard of it, which is sad because it is a truly powerful concept. I hope with this article I might have given you sufficient knowledge to go out there and start writing your own recursive functions. But remember that like with fire, you have to always be careful and use the tool wisely.

Image by Alexandre Duret-Lutz via Flickr

Architecture

The controller is the entry point for a page, and communicates with view and model components. Aura.Web helps us to easily build controllers that follow the Page Controller design pattern.

Each page of an application is usually unique, and Aura.Web provides the Aura\Web\Controller\AbstractPage class that provides the basic functionality that we can extend and use. But in order to create an object that extends the AbstractPage class, we need to provide some dependencies, usually through the constructor. The dependencies are:

1. An instance of an Aura\Web\Context class that represents the environment.
2. An instance of an Aura\Web\Accept class which helps retrieve Accept headers.
3. An instance of an Aura\Web\Response which creates a response transfer object.
4. An implementation of the Aura\Web\SignalInterface which is a signal manager to execute hooks (similar to an observer/event handler).
5. An implementation of the Aura\Web\Renderer\RendererInterface to incorporate our rendering system.
6. A parameter array in which we can pass the action methods.

The Context class accepts an array of global values, which in most cases will be $GLOBALS. From inside the controller we can use the Context object as $this->context, and can access $_GET, $_POST, $_FILES, raw php://input, and JSON decoded values using the object’s methods getQuery(), getPost(), getFiles(), getInput(), and getJsonInput() respectively. We can also check whether the request was made using GET via isGet(), PUT via isPut(), or an Ajax call via isXhr().

Let’s assume a request to http://localhost/?name=Hello is made. An example to get the value of the name parameter from within our controller is:

<?php
$this->context->getQuery('name', 'default value');

The second parameter to getQuery() is optional; it specifies a default value to be returned if the actual value is empty.

The Accept class accepts an array of $_SERVER information. The reason why it’s not just hardcoded in the constructor is to give us the flexibility to pass whatever we like for testing and such. The object is also available in our controller using $this->accept. It’s methods give us the accepted media type as an array via getContentType(), the character set via getCharset(), encoding via getEncoding(), and language via getLanguage(). A basic example from the action would be:

<?php
$this->accept->getContentType();

Note that an array of key/values is returned, similar to:

Array
(
    [text/html] => 1
    [application/xhtml+xml] => 1
    [application/xml] => 0.9
    [*/*] => 0.8
)

You may be familiar with using PHP’s header() function to add values to the HTTP response that is sent back to the client. Instead, a Response object is used as a web response transfer object. The object holds the values which we can pass along, and later convert to a proper HTTP response using tools like Aura.Http.

The Response object is also made available in the controller via $this->getResponse(). The object lets us set the response’s body content via setContent(), HTTP header values via setHeader(), cookies via setCookie(), and a redirect header via setRedirect(). We can also set the HTTP status code via setStatusCode() and the status text via the setStatusText() methods.

Here’s what extending and using an AbstractPage object looks like:

<?php
namespace Phpmaster\Tutorial\Web\Controller;
use Aura\Web\Controller\AbstractPage;

class Index extends AbstractPage
{
    public function actionGreet() {
        $this->response->setContent(
            '<html>' . 
            '<head><title>Aura web controller</title></head>' .
            '<body>Hello World!</body>' . 
            '</html>'
        );
    }
}

<?php
use Aura\Web\Context;
use Aura\Web\Accept;
use Aura\Web\Response;
use Aura\Web\Signal;
use Aura\Web\Renderer\None as Renderer;
use Phpmaster\Tutorial\Web\Controller\Index;

$page = new Index(
    new Context($GLOBALS),
    new Accept($_SERVER),
    new Response(),
    new Signal(),
    new Renderer(),
    [
        'action' => 'greet',
    ]
);
$response = $page->exec();
echo $response->getContent();

The array of parameters passed as the last argument to our extended AbstractPage specifies which actions need to be called, which format needs to be passed to the rendering strategy, and any other parameters for the action method.

In the execution cycle initiated by exec(), the following are invoked:

1. pre_exec, a hook which calls the page’s preExec() method.
2. pre_action, a hook calling the preAction() method.
3. action() to find and invoke the action method (it actually creates a Reflection class to retrieve the parameters for the method and then calls it).
4. post_action, a hook calling the postAction() method.
5. pre_render, a hook which calls the preRender() method.
6. render() to render the view.
7. post_render, a hook calling the postRender() method.
8. post_exec, a hook which calls the postExec() method.

Rendering

In the example above we explicitly set the content in the controller, but this is not really the best way to organize our code. The view should be separated. Aura.Web doesn’t provide a rendering strategy by default, so it’s easy to integrate any rendering strategy we like. Here I’ll use Mustache.

To create a rendering strategy, we need to extend the Aura\Web\Renderer\AbstractRenderer class, in which we define the exec() method. The controller is available to us in the rendering strategy via $this->controller.

<?php
namespace Phpmaster\Framework\Web\Renderer;
use Aura\Web\Renderer\AbstractRenderer;

class Mustache extends AbstractRenderer
{
    protected $mustache;

    public function __construct($mustache) {
        $this->mustache = $mustache;
    }

    public function exec() {
        $format = $this->controller->getFormat();
        if (! $format) {
            $format = '.html';
        }
        $response = $this->controller->getResponse();
        if (!$response->getContent()) {
            $data    = (array)$this->controller->getData();
            $view    = strtolower($this->controller->getAction());
            $lastval = basename(
                str_replace('\\', '/', strtolower(
                    get_class($this->controller)
                ))
            );
            $file =  $lastval . '/' . $view . $format;
            $response->setContent(
                $this->mustache->render($file, $data)
            );
        }
        $response->setContentType($this->getContentType($format));
    }

    public function getContentType($format) {
        $mimetypes = [
            '.json' => 'application/json',
            '.xml'  => 'application/xml',
            '.html' => 'text/html',
            '.htm'  => 'text/html'
        ];
        return array_search($format, $mimetypes);
    }
}

I’ve made the assumption that we’re keeping all of the Mustache templates saved using the convention <controller name>/<action name>.<format>, where the folders mirror <controller name> and <action name>.<format> is the template’s filename. For example, a controller class Example with the action hello would find it’s template in example/hello.<format>.

Building HTTP Responses

We still haven’t built a proper HTTP response, so let’s see how we can do that now. Once we call the execution cycle of the controller with it’s exec() method we will get back a response transfer object.

The object contains the HTTP status code, status text, cookies, and header values. We can build the HTTP response from it with code similar to that given below:

<?php
$response = $page->exec();

// header('Status: 200 OK');
$statusCode = $response->getStatusCode();
$statusText = $response->getStatusText();

$response->getVersion();
$headers = $response->getHeaders();
foreach ($headers as $header => $value) {
    // header('Content-Type: text/html; charset=utf-8');
    header($header . ': ' . $value);
}

$cookies = $response->getCookies();
foreach ($cookies as $name => $cookie) {
    setcookie(
        $name,
        $cookie['value'],
        $cookie['expire'],
        $cookie['path'],
        $cookie['domain'],
        $cookie['secure'],
        $cookie['httponly']
    );
}

$contentType = $response->getContentType();
if (!$contentType) {
    $contentType = 'text/html; charset=utf-8';
}
header('Content-Type: ' . $contentType);
echo $response->getContent();

I’ve demonstrated only a pure PHP implementation so it’s easy for everyone to understand, but ideally we would use something like Aura.Http or another library which provides the necessary functionality for us.

Conclusion

In this article I’ve covered the basic working principles of Aura.Web, and also showed how we can integrate a rendering strategy and how to build proper HTTP responses. You can use the power of a routing library like Aura.Router which I discussed earlier to dynamically call the controller. Maybe in a future article I’ll show how to integrate all of this and build your own framework from Aura components. Stay tuned!

Image via Fotolia

The only similarity that PDF, GIF, PNG, etc., have when stored in an Access database is that they are all wrapped in an OLE container consisting of a variable length header and trailer. As we shall see, the trailer can be ignored as it was with the package discussed in Part 1. The header is more useful, but doesn’t contain all the information we need.

Adobe Acrobat Documents

In the test database used for this article, there’s a PDF stored in record number 13:

The identification of an Adobe Acrobat Document (PDF) in an Access database OLE object field is achieved using the same method we learned in Part 1 – inspect the first fifty or so bytes looking for a recognisable sequence of characters.

Applying the same method of extracting a chunk of data from the OLE field, then converting it from hexadecimal to decimal, and displaying it in a hex viewer, makes it clear that although we definitely have a PDF stored in the field, we have no other information such as the original name of the PDF or its original file size:

Fortunately, there’s another technique we can use to extract the PDF. Every PDF always starts with the character sequence %PDF and ends with the sequence %%END. This can be verified easily by loading a small PDF in a plain text editor. Alternatively, load one into a hex viewer:

Here I’ve shown only the first and last few bytes, as these are where the PDF delimiters are. The next step is to apply this technique to the contents of the OLE field and find the location of the start and end and of the embedded PDF:

Note that it’s the hexadecimal character sequences that we need to search for; that is, when using PHP’s strpos() function to find the start of the embedded PDF, look for 25504446. When looking for the end, 2525454F46 is the relevant character sequence.

So what do we have now? We’ve identified the OLE object as type Acrobat Document, and we have the start and end locations of the embedded file. We thus have all we need to extract the original file from the OLE field using PHP’s substr() function.

Other Object Types

Before discussing popular images types, it’s worth taking a moment to improve the switch statement presented in Part 1. For the catch-all default condition we simply displayed a message. It’d be much more useful if any unknown OLE types were extracted and saved to disk for later analysis. The new function extractUnknown() takes the entire contents of the OLE field, converts it from hexadecimal to decimal, then saves it to disk using the record ID as its file name. This allows us to view any unknown OLE type in a hex viewer later to ascertain the type of the embedded object. We’ll need this in the next section to identify which records have embedded images.

<?php
function extractUnknown($id, $data) {
   // convert entire object to decimal and save to disk
   file_put_contents($id . ".txt", hex2bin($data));
}

Popular Image Types

It’s not possible to say with any certainty how image types will be identified in an OLE header in any given Access database. It may be that images will be identified as “Paint Shop Pro 6”, or perhaps they’ll be associated with some other image editing software. It depends entirely on what software was known to the system that was used to store the images and on any file associations that were configured.

In order to know what these unknown types are, we can make a list by running every record with an unknown OLE type through the extractUnknown() function. This will be different across the plethora of legacy Access database that exist today.

The image formats we’ll consider here are BMP, GIF, JPEG, and PNG.

GIF, JPEG, PNG

“Good news, everyone!” These three image types can be processed in exactly the same way. What’s more, it’s exactly the same method used earlier to extract an embedded PDF. First we need to find the start position of the embedded image, then the end position, then extract inclusively everything between these two points. The difference is in how we identify the embedded object. The following table summarises these crucial details:

BMP

Identifying the delimiters of an embedded BMP is similar, but requires a little more work. Finding the start position is as easy as it is with the file types discussed above, but finding the end position requires a bit of math. Let’s see the two crucial elements in a hex viewer:

The first two bytes (BM in ASCII), underlined in orange, are the start location of the embedded BMP. The following two bytes, underlined in yellow, are the original size of the BMP stored in little-endian format. The size needs to be converted to big-endian format, then multiplied by two because the object is stored in hexadecimal format.

Given that we now have the start position and the size of the embedded object, we can used the same method to extract a BMP as we used in Part 1 to extract an object from a package.

Putting It All Together

What follows is the PHP script from Part 1 updated to include the new functionality described above. The basic structure is identical to its previous version, and the additional conditions in the switch() statement shows how easy it is to extend the core logic of the script to accommodate other OLE types.

<?php
$offset = array(
    "Packager Shell Object" => 168,
    "Package" => 140
);

if (!function_exists("hex2bin")) {
    function hex2bin($hexStr) {
        $hexStrLen = strlen($hexStr);
        $binStr = "";
        $i = 0;
        while ($i < $hexStrLen) {
            $a = substr($hexStr, $i, 2);
            $c = pack("H*", $a);
            $binStr .= $c;
            $i += 2;
       }
       return $binStr;
    }
}

$dbName = "db1.mdb";
$db = new PDO("odbc:DRIVER={Microsoft Access Driver (*.mdb)}; DBQ=$dbName; Uid=; Pwd=;");

$sql = "SELECT * FROM Table1";
foreach ($db->query($sql) as $row) {
    $objName = "";

    switch (getOLEType($row["image"])) {
        case "Packager Shell Object":
            list($objName, $objData) = extractPackage($row["image"], $offset["Packager Shell Object"]);
            break;
        case "Package":
            list($objName, $objData) = extractPackage($row["image"], $offset["Package"]);
            break;
        case "Acrobat Document":
            list($objName, $objData) = extractPDF($row["id"], $row["image"]);
            break;
        case "Paint Shop Pro 6":
        case "Bitmap Image":
            list($objName, $objData) = extractImage($row["id"], $row["image"]);
            break;
        default:
            list($objName, $objData) = extractUnknown($row["id"], $row["image"]);
    }
    if ($objName != "") {
        file_put_contents($objName, $objData);
    }
}

function extractUnknown($id, $data) {
    // convert entire object to decimal and save to disk
    file_put_contents($id . ".txt", hex2bin($data));
}

function extractPackage($data, $offset) {
    // usable header size
    $headerBlock = 500;
   
    // find name
    $tmp = substr($data, $offset, 255);
    $nullPos = findNullPos($tmp);
    $name = substr($tmp, 0, $nullPos);
    $pos = $offset + strlen($name);

    // find data
    // 1st full path
    list($path1, $nameLen) = findFileName($data, $name, $pos, $headerBlock);
    $pos = $path1 + $nameLen;
    // 2nd full path
    list($path2, $nameLen) = findFileName($data, $name, $pos, $headerBlock);
    // check if only one full path
    if ($path2 > $pos) {    
        $pos = $path2 + strlen($name);
    }
    $oleSizePos = $pos + 2;
    $oleObjSize = flipEndian(substr($data, $oleSizePos, 8), 8);
    $oleHeaderEnd = $oleSizePos + 8;
    $objName = hex2bin(substr($tmp, 0, $nullPos)); 

    // extract object
    $objData = getBlob($data, $oleHeaderEnd, hexdec($oleObjSize) * 2);

    return array($objName, $objData);
}

function extractPDF($id, $data) {
    $delimiter = array(
        "pdfStart" => "25504446",
        "pdfEnd" => "2525454F46"
    );
    // %PDF  - start block common to all PDFs
    $offsetStart = strpos($data, $delimiter["pdfStart"], 0);
    // %%EOF - end block common to all PDFs
    $offsetEnd   = strpos($data, $delimiter["pdfEnd"], $offsetStart) + 12;
    $objData = getBlob($data, $offsetStart, $offsetEnd - $offsetStart);
    return array($id . ".pdf", $objData);
}

function extractImage($id, $data) {
    $delimiter = array(
        "bmpStart" => "424D",
        "gifStart" => "4749463839",
        "gifEnd" => "003B",
        "jpgStart" => "FFD8",
        "jpgEnd" => "FFD9",
        "pngStart" => "89504E47",
        "pngEnd" => "49454E44AE426082"
    );
    $objName = "";
    if (strpos($data, $delimiter["bmpStart"], 0) !== false) { // is object a BMP
   	    list($objName, $objData) = extractBMP($id, $data, $delimiter["bmpStart"]);
    }
    elseif (strpos($data, $delimiter["gifStart"], 0) !== false) { // is object a GIF89
        list($objName, $objData) = extractGIF($id, $data, $delimiter["gifStart"], $delimiter["gifEnd"]);
    }
    elseif (strpos($data, $delimiter["jpgStart"], 0) !== false) { // is object a JPEG
   	    list($objName, $objData) = extractJPEG($id, $data, $delimiter["jpgStart"], $delimiter["jpgEnd"]);
    }
    elseif (strpos($data, $delimiter["pngStart"], 0) !== false) { // is object a PNG
   	    list($objName, $objData) = extractPNG($id, $data, $delimiter["pngStart"], $delimiter["pngEnd"]);
    }
    else {
        // other image types in here
    }
    // save to disk if object was found
    if ($objName != "") {
        file_put_contents($objName, $objData);
    }
}

function extractBMP($id, $data, $bmpStart) {
    $oleObjStart = strpos($data, $bmpStart, 0);
    $oleObjSize = hexdec( flipEndian(substr($data, $oleObjStart+4, 8), 8) );
    // extract object
    $objData = getBlob($data, $oleObjStart, $oleObjSize * 2);
    return array($id.".bmp", $objData);
}

function getBlob($data, $start, $end) {
    return hex2bin(substr($data, $start, $end));
}

function flipEndian($data, $size) {
    $str = "";
    for ($i = $size - 2; $i >= 0; $i -= 2) {
        $str .= substr($data, $i, 2);
    }
    return $str;
}

function findNullPos($str) {
    // must start on a two-character boundary
    return floor((strpos($str, "00") + 1) / 2) * 2;
}

function getOLEType($data) {
    // fixed position of OLE type
    $offset = 40;

    $tmp = substr($data, $offset, 255);
    $nullPos = findNullPos($tmp);
    $tmp = substr($tmp, 0, $nullPos);
    $type = hex2bin($tmp);

    return $type;
}

function hexStrToCase($str, $case) {
    $alphabet = 32;
    $tmp = "";
    $splitHex = array();
    $splitHex = str_split($str, 2);
    $splitTest = hex2bin($splitHex[0]);
    foreach ($splitHex as $key => $value) {
        switch ($case) {
            case "upper":
                if ((intval($value, 16) >= ord("a")) && (intval($value, 16) <= ord("z"))) {
                    $splitHex[$key] = dechex(intval($value, 16) - $alphabet);
                }
                break;
            case "lower":
                if ((intval($value, 16) >= ord("A")) && (intval($value, 16) <= ord("Z"))) {
                   $splitHex[$key] = dechex(intval($value, 16) + $alphabet);
                }
                break;
       }
    }
    $tmp = strtoupper(implode($splitHex));
    return $tmp;
}

function hexStrToTilda1($str) {
    $strDot = "2E";
    $strTilda1 = "7E31";
    $tmp = hexStrToCase($str, "upper");
    if (strlen($tmp) > 24) {
        $dotPos = strrpos($tmp, $strDot);
        $tmp = substr($tmp, 0, 12) . $strTilda1 . substr($tmp, $dotPos, 8);
    }
    return $tmp;
}

function findFileName($data, $str, $offset, $headerBlock) {
    $strLen = 0;
    $tmp = substr($data, 0, $headerBlock);
    $strUpper = hexStrToCase($str, "upper");
    $strLower = hexStrToCase($str, "lower");
    $strTilda1 = hexStrToTilda1($str);
    $strPos = stripos($tmp, $str, $offset);
    if ($strPos === false) {
        $strPos = stripos($tmp, $strUpper, $offset);
        if ($strPos === false) {
            $strPos = stripos($tmp, $strLower, $offset);
            if ($strPos === false) {
                $strPos = stripos($tmp, $strTilda1, $offset);
                $strLen = strlen($strTilda1);
            }
            else {
                $strLen = strlen($strLower);
            }
        }
        else {
            $strLen = strlen($strUpper);
        }
    }
    else {
        $strLen = strlen($str);
    }
    return array($strPos, $strLen);
}

You’ll notice that I’ve not included code for the functions extractGIF(), extractJPEG(), and extractPNG(). That’s because I’m leaving these as an exercise for you, fellow PHP programmers – the code will be very similar to what we’ve covered for the other OLE object types.

Summary

In this article we’ve covered the essential elements of extracting PDFs from OLE fields in a Microsoft Access database using PHP. We also learned how to identify certain image formats, and how to extract them from their OLE container.

Having completed this two-part introduction to how OLE objects are stored in, and can be retrieved from, a Microsoft Access database, we now have yet another tool to assist us with the migration away from legacy Access databases.

You can get the code for this series on the PHPMaster GitHub page. The repo has two branches – part-1 for code to accompany the first part, and part-2 for code for this part.

Image via Fotolia

In this article I’ll show you how I built a sample web application that creates and distributes passes in the form of a “PHPMaster Membership Card”. It is not a full-featured product, but it’s a nice base to build on for more serious real world uses. You can download the demo code for the article from PHPMaster’s GitHub.

Please note: In order to run this article’s code, you (or your client) must be registered to one of the paid Apple iOS Developer Programs which allows you to create the necessary certificates to sign your passes. For this reason I’ve also made a dummy application available online for you to play with.

What’s a Pass and How do I Use One?

A pass is a digitally signed document such as a ticket, membership card, or coupon that can be distributed by email or a web download. It can be opened with the Passbook app on iOS or with an app like PassWallet on Android. On iOS, a pass can also be linked to a companion app, for example the Eventbrite app which allows you to buy tickets and add them to your device’s Passbook, but that’s not mandatory.

Apple’s specs outline four main pass types:

• Boarding passes
• Event tickets
• Retail coupons
• Store cards

There’s also a Generic pass type that covers other purposes, and this the type of pass I’m using here.

Each pass contains various bits of data. Some, such as a member name and bar code are displayed visually on the “front side” of the pass. Other data is located on the “back” of the pass and triggered by the “i” icon. Passes can also contain some hidden information such as a time and location which can be used to display relevant notifications.

On Apple’s Passbook Developers page you can find official guides and some sample code.

App Concept: PHPMaster Membership Card

The sample application has two main features:

• Create and store passes
• Implement the register/unregister web service API

The main form prompts the user for a full name, an email address, and an optional favorite function. The member picture is fetched using the Gravatar API. The backend code then saves the provided data to a database, generates the pass, and sends a copy to the subscriber’s email.

The pass contains the URL and access codes for a web service, so when the subscriber adds the pass to his collection the Passbook app will call a predefined registration URL that must be implemented to check and store the provided data for later use.

App Structure

Since the core of this writeup is to understand pass-related code, I’ll start from a base of well known open source components available on GitHub and using Composer.

The application is built using Slim Framework since it’s lightweight and well suited for both RESTful development and web-GUI applications. Slim’s default PHP template engine is used as well the DateTimeLogWriter from the Slim Extras package.

The data and model layer is covered by Idiorm and Paris. Idiorm takes care of database work, while Paris provides a simple and clean model interface. This allows us to work with a Pass and a Subscriber object and call, for example, $pass->pack() to generate the pass package.

Pass Definition

The first step is to define the pass; how will it look and what data will contain?

With this information at hand, we can create a pass template directory containing the basic assets:

templates/passes/PHPMaster.raw/
    logo.png
    icon.png
    pass.json

Each of the images can have a corresponding ImageName@2x.png version that can be used on retina devices if present. The logo is displayed in the top left of the pass, while the icon is displayed in the push notification box and iOS mail app. pass.json contains the data for the pass.

Inside pass.json, teamIdentifier is assigned to us by Apple when we subscribe to the Developer Program. passTypeIdentifier is a unique reverse-domain ID for our pass type, for example pass.com.phpmaster.membership-test (the “.pass” prefix is required). The serialNumber field must be unique to each pass, so a good value to use is the primary key from the database table that stores passes.

The generic key indicates the pass type we are using and contains the specific fields for the pass. Each pass type has a set of primaryFields, secondaryFields, and auxiliaryFields displayed in different places on the front side; it can also have a number of backFields displayed on the reverse side. Each field has a label (displayed publicly), a key (for internal reference), and a value.

The webServiceURL and authenticationToken fields are defined later in the application and are filled with the base URL of and the access credentials used by the device to register itself on our server.

Certificates

The next step is to obtain the certificate used for pass generation. The Apple Developer’s provisioning panel is used to request certificates and there is a nice video tutorial on the PassKit wiki. You need a specific certificate for each pass type; the certificate’s common name must match the passTypeIdentifier of the pass.

Each pass’s signature must also include the public Apple WWDR Intermediate Certificate.

Directory and File Layout

Here’s what the layout of the application looks like:

The bin directory contains the command line utility signpass.php. This program is a PHP port of Apple’s console utilities written in Objective-C and Ruby. It can be used to validate a pass or to create one from a given directory. It uses the PassSigner library which I detail later.

The config directory holds the configuration files. Make a copy of the sample and name it after your environment (stage, dev, prod, etc). To define a custom environment, create a text file named .mode inside the root directory containing the desired name of your environment. The $config['db'] array in the configuration file is used by Idiorm, and the $config['app'] array is passed directly to the Slim application’s constructor.

The data directory holds log files, generated passes, the SQL dump file, and the Certificate directory that must contain Apple’s public certificate and the certificate for your pass, both in PEM format. Certificates are distributed in CER or P12 format and can be converted with the openssl utility like so:

openssl pkcs12 -in data/Certificate/PHPMaster.p12 -out data/Certificate/PHPMaster.pem

The templates directory holds the front-end template files. There’s two pages, the home (main.php) and the result page (pass.php), which share the header and footer elements. The subscription form has its own file (form.php).

The passes subdirectory holds templates for each pass type. Each pass’ templates are organized into directories named PassTypeOrName.raw containing the necessary files.

The custom library code resides in lib/MyPassbook. Inside this directory there is:

• the PassSigner library, responsible for pass signing and validation
• the model classes built upon the core objects Subscriber, Pass, and Device

DevicePass is an intermediate class needed by Paris and manages the many-to-many relationship between devices and passes; as defined in the Passbook specs, each device can contain many passes and a copy of each pass can be stored in many devices.

The application’s public directory contains the controller files. index.php is the main controller. The controller includes include/bootstrap.php which is responsible for the application’s startup, loading the configuration file, setting up some defaults, connecting ORM to the database, and starting the log writer. In particular, the script also sets some code to the slim.before event hook used to capture the special Authentication HTTP header.

The install.php file is just a quick-and-dirty script that resets the application; there’s probably no need to say that it must be removed after you’ve set everything up!

There should also be a .htaccess file that redirects all non-file URIs to index.php and adds a custom mime type for our passes:

AddType application/vnd.apple.pkpass    pkpass

This allows Safari to open the pass with the PassViewer utility.

Writing the Application

The most important components of the application are the PassSigner class and the index.php front controller. Paris gives us the ability to use model classes so that the underlying database logic is transparent and managed by Idiorm. Creating a model class is as simple as:

<?php
class Subscriber extends Model { }

There’s three classes that need to be created: Pass, Device, and Subscriber.

The basic methods such as create(), find_many(), delete(), and so on are inherited from the base class. We can modify the basic properties (for example the linked database table or column ID), enhance the default methods, and add custom methods as needed.

I added three methods to the Subscriber class:

• pass() – implement a one-to-one relationship with a Pass object and return this object.
• create() – override the default create() method allowing an array of data to be passed.
• createPass() – create a Pass object linked to the current subscriber.

And these are the six methods I added to the Pass class:

• subscriber() – implement a one-to-one relationship with a Subscriber object and return this object.
• devices() – define the many-to-many relationship with the Device object. It has a corresponding passes() method on the Device class.
• create() – same as the create() method of the Subscriber class.
• delete() – override the default method; delete the linked Devices and Subscriber objects.
• filename() – calculate and return the file name for the pass on disk.
• pack() – save the pass to disk using the PassSigner library.

The PassSigner library

PassSigner provides two main public methods for pass management:

• signPass() – take a directory containing data for a single pass and the certificate data and produce a zipped PKPASS file.
• verifyPassSignature() take a PKPASS file and validate its structure and signature.

There are also two utility methods rcopy() and rrmdir() for recursive copy and deletion of directories, and some internal protected methods. The library makes extensive use of exceptions validation functions, and the two important methods check for the Apple certificate which must be defined by the constant APPLE_CERTIFICATE with the certificate path.

To sign a pass, a file named manifest.json must be produced using the pass directory’s contents. This file must be signed with your certificate and include Apple’s public certificate. The signature data is saved in a file named signature.

Let’s say that we have a directory that contain the pass data:

data/passes/PassForUser001.raw
    info.png
    logo.png
    thumbnail.png
    pass.json

The first step is to recursively copy all of the contents to a temporary directory (/tmp/PassForUser001 for example). Make sure there’s no “junk” files that shouldn’t be included, like the annoying .DS_Store files if you’re on OSX. If any of these files in included in the zipped pass but not in the manifest, the pass is invalid.

Then create the associative array to store the manifest data. There is an item for each file in the pass directory, the relative path is the item’s key while the value is the SHA1 hash of the file. The array is encoded and saved as manifest.json in the pass directory.

<?php
$manifestData = array();
$files = new DirectoryIterator($passPath);
foreach ($files as $file) {
    if ($file->isDot() || $file->getFilename() == ".DS_Store") {
        continue;
    }
    $key = trim(str_replace($passPath, "", $file->getPathName()), "/");
    $manifestData[$key] = sha1_file($file->getPathName());
}

Now for the signature… basically, we sign the manifest.json file using our certificate and password, including Apple’s WWDR certificate. The binary output is written to signature. However, there’s a problem here: the the binary option for PHP’s openssl_* functions seems buggy and still generates a text-encoded signature. I’ve worked around this by calling the shell command from PHP instead:

<?php
$signCommand = sprintf(
    "openssl smime -binary -sign -certfile %s -signer %s -inkey %s -in %s -out %s -outform DER -passin pass:%s",
    APPLE_CERTIFICATE,
    $certPath,
    $certPath,
    $manifestPath,
    $signaturePath,
    $certPassword
);

$signResult = false;
$signOut = array(); // needed but unused
exec($signCommand, $signOut, $signResult);
unset($signOut);

If the $zip option is enabled (with by default it is) the pass is packed using the ZipArchive class.

To verify the pass, verifyPassSignature() extracts the given pass to a temporary directory and then calls the internal validateManifest() and validateSignature() methods. Both methods must return true.

<?php
foreach ($files as $file) {
    ...

    // Check that each file is present in the manifest
    if (!array_key_exists((string)$file, $manifestData)) {
        throw new \Exception("No entry in manifest for file '{$file}'"), 506);
    }

    // Check SHA1 hash for each file
    $hash = sha1_file($file->getPathname());
    if ($hash == false || $hash != $manifestData[(string)$file]) {
        throw new \Exception(
            sprintf(
                "For file %s, manifest's listed SHA1 hash %s doesn't match computed hash, %s",
                $file,
                $manifestData[(string)$file],
                $hash
            ),
            507
        );
    }
}

A manifest is valid if the pass directory contains only the files declared inside the manifest, the manifest itself, and the signature file. If a file is missing or there are files not listed then the pass is invalid. Also, the SHA1 hash for each file must match with the one stored in the manifest.

The signature is also validated using openssl in three steps. First we verify the manifest’s contents with its signature. The option -noverify tells OpenSSL to skip the signer’s certificate verification.

$verifyCommand = sprintf(
    'openssl smime -verify -binary -inform DER -in %s -content %s -noverify 2> /dev/null',
    $signaturePath,
    $manifestPath
);

Then the certificates are extracted from the signature:

<?php
$exportCommand = sprintf(
    'openssl smime -pk7out -in %s -content %s -inform DER -outform PEM',
    $signaturePath,
    $manifestPath
);

The command’s output is passed to the internal parseCertificates() method which I won’t discuss here. It uses a mix of OpenSSL and regex to extract certificates from the given data to an array of associative arrays which is used for a certificate-checking loop:

<?php
$certs = self::parseCertificates($pemData);
$foundWWDRCert = false;
for ($i = 0; $i < count($certs); $i++) {
    $commonName = $certs[$i]['subject']['CN'];

    if ($commonName == APPLE_CERTIFICATE_CN) {
        $foundWWDRCert = true;
    }
}

The Index Controller

The controller index.php is responsible for providing both the web-GUI app and the RESTful API. It consists of two URIs: the homepage via GET and the same page via POST. The first page displays only the empty form, but the second is more interesting.

To ensure each email address is unique, it asks Paris which in turn checks the database:

<?php
$subscriber = Model::factory('\MyPassbook\Subscriber')
    ->where_equal('email', $memberMail)
    ->find_one();

if ($subscriber !== false) {
    $errors['membermail'] = sprintf("The email address '%s' is not available", $memberMail);
}

The subscriber thumbnail URL is picked from Gravatar:

<?php
if (empty($errors['membermail'])) {
    $memberThumbnail = "https://www.gravatar.com/avatar/" . md5(strtolower(trim($memberMail))) . "?s=60";
}

And now it can create a new subscriber:

<?php
try {
    $subscriber = Model::factory('\MyPassbook\Subscriber')->create(
        array(
            'name' => $memberName,
            'email' => $memberMail,
            'created' => date('Y-m-d H:i:s', $memberSubscription),
            'function' => $memberFavFunction,
            'picture' => $memberThumbnail
            )
    );
    $subscriber->save();
}
catch (\Exception $e) {
    $errors['subscriber'] = "Error creating subscriber profile";
}

The pass’s JSON template file is loaded into $data and all of the placeholders are filled with real user and app data:

<?php
$data['serialNumber'] = $subscriber->id;
$data['webServiceURL'] = sprintf('https://%s/%s/', $env['SERVER_NAME'], $app->request()->getRootUri());
$data['authenticationToken'] = md5($subscriber->id);
$data['barcode']['message'] = $subscriber->id;
$data['generic']['primaryFields'][0]['value'] = $subscriber->name;
$data['generic']['secondaryFields'][0]['value'] = date('Y', $memberSubscription);
$data['generic']['auxiliaryFields'][0]['value'] = $subscriber->function . '()';
$data['generic']['backFields'][0]['value'] = $subscriber->id;
$data['generic']['backFields'][1]['value'] = $subscriber->created;
$data['generic']['backFields'][2]['value'] = $subscriber->email;

Using the custom model methods, the new $pass is created with $subscriber->createPass() and, if everything is right, the $pass can pack itself.

<?php
if ($pass = $subscriber->createPass($app->config('passes.passType'), $data)) {
    $pass->pack(
        $app->config('passes.path'),
        $app->config('passes.store'),
        $app->config('passes.certfile'),
        $app->config('passes.certpass')
    );

...

}
else {
    $errors['pass'] = 'Unable to create pass';
}

The pack() method is simple: it makes a temporary copy of the template directory, adds the pass-specific files, and calls PassSigner::signPass() on the working directory. The newly created pass is then sent by email and the pass.php template file is rendered to the user with the download link.

Going RESTful

Since a web service URL is embedded inside the pass, Apple’s specs say that we must implement at least two endpoints for registering and unregistering devices. The URI is always /v1/devices/:deviceId/registrations/:passTypeId/:serialNo and is called via POST for registration and DELETE for unregistration.

The Device ID, Pass Type ID, and Pass Serial Number are received from the URI while the auth token is found in the Authorization header. The auth token must be present in the header and linked to a pass in order to succeed, and a 401 response must be returned in the event of unauthorized access.

During the registration process, a Push Token is sent as the body of the request in JSON format: {"pushToken": <pushToken>}. The registration process creates a new Device object in the database and fills the Device ID and Push Token fields provided. Then a DevicePass object is created to store the relationship between the device and the pass.

If we need to update a pass, we use the Device ID and Push Token to send a push notification request to Apple Push Server (and obviously the update mechanisms need to be implemented as well).

The unregistration URI receives all of the same data except for the Push Token. All references for the given pass are deleted, including devices and relationships.

Conclusion

We’ve covered a lot in this article, and there’s still more to explore about Pass management. Feel free to start with the PassSigner library and build on top of it. You can easily create all sorts of Pass applications for you or your clients. Happy coding!

Image via Fotolia