php

I just released version 1.0 of my iOS Smart App Banner plugin for WordPress. This plugin lets you put a smart app banner at the top of your post or page when an iOS device visits in mobile Safari. It’s a great tool for app promotion that makes it very easy for people to find & buy your app in the App Store.

I was recently playing around with an idea – a proof of concept – for an mobile app API. If you’ve never done this before, keep reading.

The high-level requirements:

A mobile app that you have control over

An API you’re working on

Users must be authenticated

As I am the app and API owner, I thought it best and easiest to use a two-legged OAuth implementation – username & password plus some secret keys (3-legged vs 2-legged explanation). This is what your users will expect when logging into your app & service. Before you can start, find an appropriate library for your web framework. There are plenty out there, so pick your poison. I’m familiar and develop relatively quickly with CakePHP, so I went with seddonmeida cakephp-oauth-server. I’ll spare you from too much code.

First, you’ll have to set up an OAuth client in the database. This is for your app and nobody else. Follow your library’s instructions; you’ll find out you can’t read values from the database because they should be hashed. Once you have it installed and are sure it’s working, you can start the setup. In the CakePHP plugin,

Swift

1

2

3

4

functionsome_open_oauth_action(){

$client=$this-&gt;OAuth-&gt;Client-&gt;add('myapp://register');//the URL isn't really important in this case

print_r($client);

}

Save your client_id and client_secret in a safe place. You’ll need it in your app. Now, the fun part. You can test this in your browser, but it will work the same way in your app.

First, Grant the Token

In OAuth terms, we’re doing a password type grant with the client_id and client_secret.

You’ll get JSON in return with a few important keys, namely access_token and refresh_token. They will serve as your ID badge for future requests. Keep them around. NB: access_token is used most, but refresh_token has a special place.

Request Something

Making a request for protected resources is easy. Assuming your back-end is set up properly, you should be able to run something like this with no problem:

I know the above URL is at /oauth/, but that doesn’t mean your entire API has to be handled with your OAuth controller. In practice, you should include your OAuth library as a component of each appropriate controller wherever you’re accessing the API, or at least secured content.

Refreshing Your Token

A lot of services using OAuth aren’t going to expire your token. Seddonmeida’s implementation uses an expiration, but in practice doesn’t actually enforce it; that’s up to you. In the case you do have an expiring token, it’s best to refresh your user’s keys from time to time so they aren’t “logged out.” To get a fresh new token, access our OAuth token action and request a refresh_token grant type using the client_id, client_secret, and the refresh_token you received when first authenticating.

We at Pivotal Action were recently given a task for a client – develop a tool for a mobile API where admin can upload a list of retailers so that their mobile app users could find locations near them. It’s basically a “Find near me” utility.

This type of project is broken down into 3 parts: Upload & store geolocation data, find addresses near a given point, and display those locations either textually or on a map display. This quick tutorial will cover the first two parts.

Part 1, Getting Located

The goal of this part is to obtain and store latitude/longitude pairs for given addresses. I’m going to assume you can already get a list of addresses, whether for a spreadsheet/csv file, or other source. With a parsed address, you can obtain the lat/lng pairs from the Google Maps API. Just be forewarned that Google limits you to 2,500 requests per 24h period. That could be a problem for some applications, so you may need another provider like SimpleGeo.com

There are a couple key parts in there. First, you need to URL encode the address details. Second, the curl stuff is pretty standard – you can find similar versions all over the net. Third, the response data comes back as a JSON string, so you need to decode it into a PHP array to make it useful. My default value for lat/lng pairs is 0.0/0.0. There may be cases where Google doesn’t understand the address information or perhaps you’ve gone over your rate limit, so you have to accept more or less a throw-away response. The important thing is that you have your address coordinates saved (dare I say, cached) in your DB. You need this.

Part 2, Finding Yourself

Now how are you supposed to find these stores that are near you, at this moment, without having to use a lame web form or other manual means? You’re going to use the Haversine, aka Great Circle Formula. Don’t click that link unless you really want to be confused. Here’s the gist – the globe is a big sphere, and we know from high school and/or college trigonometry classes that you can figure out lengths and distances on geometric objects. Some guy long ago (whose name was not Haversine) sat down and figured this out for us. What we get as a result of running these maths is the distance between to points on earth, using lat/long pairs. The caveat is these are as the crow flies, not driving directions. What I’m going to show you below is some SQL you can use to find the N closest points within a given distance. This will work on MySQL, and I’m assuming other SQL-compliant DBs. YMMV.

Swift

1

2

3

4

5

6

7

8

9

// scale: MILES - use 3959 ; KM - use 6371 (mean radius of the earth)

$scale=3959;

$sql="SELECT name, address, city, state, zip, ( "

.(int)$scale." * acos( cos( radians(".(float)$loc['lat']

.") ) * cos( radians( lat ) ) * cos( radians( lng ) - radians("

.(float)$loc['lng'].") ) + sin( radians(".(float)$loc['lat']

.") ) * sin( radians( lat ) ) ) ) AS distance FROM "

.$tablename." HAVING distance &lt; ".(int)$distance

." ORDER BY distance LIMIT 0 , ".(int)$limit.";";

(Thank Pavel Chuchuva on Stack Overflow for the SQL [answer here]). You only need a couple parameters to get this chugging along and giving you a list of distances, closest to farthest from the point you are feeding it. Along with your address information, you’re also provided a distance in miles (using 3959 for measurement in Km).

Now you can use these results to display distances to your users. Let Google be your guide for implementing Part 3.

I like to wait quite a while before upgrading Mac OS X to the newest release because, for me, it often requires quite a bit of work. I had hopes that Snow Leopard would be different because Apple finally installed current versions of the whole LAMP stack, but I wanted to wait regardless… just in case.

Why the wait?

I do dev work that require custom libraries in my PHP installation – vanilla PHP from Apple doesn’t have what I need. To do that I’ve relied pretty heavily on the Fink package manager. Too many times I’ve upgraded to the new OS and some of the libraries haven’t yet been updated to work properly on the new system. Usually after a couple months either the libraries get fixed or Google will give me enough results and clues that I can fix the issue myself.

First things first

I went ahead and compiled Apache from scratch. It’s easy enough and you’ll need the 64bit support for PHP. MySQL was much easier – download the intel x86_64 installer for Mac OS X 10.5 (yes, even for Snow Leopard). Side note – MySQL finally got around to recompiling the System Prefs Pane to 64bit.

Installing Fink

I’ll save you some time. First, compile fink from source. When you set up the app, do the 64bit-only packages (you’ll know – it’ll prompt you to pick 32bit or 64bit). I tried the 64bit and PHP wouldn’t install. You can always do a separate mixed architecture install later (see here for details on mixed fink arch installs).

Compiling PHP (with GD)

I need GD. This tutorial did the trick – once I had figured out the 64bit fink issue(s). Follow it and the companion standard PHP / Snow Leopard compile tutorial, linked in that article. Take a look at my compile flags, if you’re interested:export MACOSX_DEPLOYMENT_TARGET=10.6
CFLAGS="-arch x86_64"
CXXFLAGS="-arch x86_64"

Two things: First, my PHP is installed into /Library/PHP5/. Second, my Apache is located at /Library/Apache2/. Nothin to it. Too bad it took me all day to figure this out. At least now I can move on with my life!

[I started this post quite a while ago and forgot about it. Here it is finished. Hopefully you find something useful here]

I’ve had a few projects already where I could really use some PEAR libraries but not sufficient enough access to the server so I could install them in the system-wide PEAR include directory. I went searching for an easy to manage way to package specific PEAR libs along with apps I was building and installing for clients – something that would work without access to system-wide PHP/PEAR setup, and even in rare cases where I couldn’t write outside the document root.

First place to at least read through is the documentation. I’m going to assume you already know the basics of PEAR.

This summary will discuss the FTP method, as it seems applicable to more situations. For me – I keep my sites under version control so I need to be able to perform a local install that I can commit to the repository and either export or update on my various server environments.

Tools:
* Terminal or command-line (CLI)
* CLI version of PHP
* CLI version of PEAR

Steps (code follows)

Create a directory where you want the PEAR libs installed. Note: PEAR will create a directory named pear in the location you specify.

CD into that directory.

Create your config file for your local environment (probably won’t be needed on external servers unless you plan on installing from there, in which case you should create a separate config file for each site).

The first path is the location where you want the files. The second path is the location where the pearrc file is located. I usually put the PEAR files in an includes directory within the site’s document root, just in case a host or client I’m dealing with doesn’t have write access in higher-level directories. It’s best to keep the pearrc file outside of the webroot, or deny access to the file via Apache’s Allow/Deny directives.

To run PEAR commands on your local install, you will need to use the following format

Swift

1

%&gt;pear-c/path/to/app/setup/pearrc[command]

(otherwise you’re likely working on system-wide changes – doesn’t help you when it’s time to deploy to the server). An example,
%> pear -c /path/to/setup/pearrc install File_CSV_DataSource

I just ran across a nasty worm in one of my WordPress blogs (not the most current install). Not only did it overwrite a ton of files, inserting spam links and malware into the pages, but it was sneaky enough to go into my wp-admin/.svn/prop-base/ directory and re-write those files as well. It’s fairly ingenious from the hacker standpoint. Most people like me will rely on the svn revert file.php to send the file back to its original version. That won’t work if the .svn/prop-base files are altered because svn will see that they are the same – it doesn’t bother actually checking the repo, so you’re stuck with infected files.

I solved my problem by deleting the wp-admin directory and doing an svn-up on its parent. That forces SVN to say “hey – that directory is missing. I should pull it down from the repository.” Problem solved (for now).

And I am now running the most current version of WordPress, so hopefully I’m free of risk and infection from here on out.

There are many situations in web apps where site-wide configurations need to be accessible to users through admin interfaces, rather than configuration files residing on the server. It is a practical method of storing configuration values that may need changing from time to time, but without access to the core configuration file.

UPDATE (2008-10-22): This article has been published to the CakePHP Bakery

Code

Settings are stored in the database, so we will first need to start by creating the table:CREATE TABLE settings (id int(10) unsigned NOT NULL auto_increment,key varchar(48) NOT NULL,value text,
PRIMARY KEY (id),
UNIQUE KEY key (key)
)

You’ll notice that Configure:: values are serialized and stored together using the MyApp Configure::key. At first this may seem somewhat counter intuitive to how we think we should store configurations. However, consider the hassle involved with trying to figure out how/where to store multi-dimensional arrays in an inherently flat storage system (db). It’s probably doable, but not without considerable headaches. Storing everything in a serialized string allows Cake to worry about creating the structure – we just save the output.

Next, open up your app_controller.php file and add the following code to the top of the class:var $uses = array('Setting');

You will also need to add some code to your AppController beforeFilter() and afterFilter() methods:
class AppController extends Controller {

var $uses = array(‘Setting’);

function beforeFilter(){
//reads the site-wide config values from the DB and puts them through the Configure::write method
$this->Setting->getcfg();
}

function afterFilter(){
//retrieves the site-wide configurations from Configure::read($key) and puts it back into the db if new
$this->Setting->writecfg();
}
}

Usage

Any place you would like to store a Configure:: value in the database, you only need to use the $key specified in the model. If you don’t, the values will not get saved. An example would look something like:<? Configure::write('MyApp.themeName','My Great Theme'); ?>

Since the retrieval code is run in the before filter, we can treat the Configure:: vars like any others in our app when we need to access them. To recall a value we would run something like:<? $myVar = Configure::read('MyApp.themeName'); //returns 'My Great Theme' ?>

Next Steps

Because this is only a very simple way to store configuration data (one row for the entire app), there will likely be some desire to extend it. You may wish to segregate certain data into their own rows (perhaps individual plugins or components), which would only require some additional code to accept additional keys for read/write access. That, my friends, is a job for another tutorial.

Reading through a few of my most recent posts, you’ll quickly learn that I’m learning CakePHP as my PHP framework of choice. So far, so good. Actually, it’s pretty good, but that is not without some questions I’ve had along the way. I’m probably getting stuck more than I should on best practice coding, but I like to do it the right way, not necessarily the easiest way (read: hacks).

Among some of my initial stumbling blocks has been working through the idea of access control from the framework viewpoint. I “get it” when it comes to writing my own code, like in the revealCMS, and I “get it” in the context of certain “things” (usually users) needing access to specific things (often controllers and actions). The hard part is sorting out where to even start with all the alphabet soup: Auth, Acl, Aro, Aco, etc etc etc. How do you even get to a point where you have a simple working prototype to expand on?

Apparently there are numerous examples and tutorials of how to get started with Cake Acl, however I find many of them to be over-complicated or thorough. In other cases some are simply too terse. There is a fine line between terseness and conciseness. Even the CakePHP docs leave much to be desired for newer users: the official Acl documentation is long and kind-of confusing, and the sample application tutorial (also part of the official docs) seems to do things differently than explained in the primary documentation – a considerable problem, in my opinion. Yes, I do realize that the concept of Acl really depends on your application, but shouldn’t documentation at least be consistent? The one saving grace, however, is that the Bakery has a few examples, which brings me to my next point.

I found a tutorial I actually like so far. By “so far,” I mean I haven’t finished it yet, but to this point I’ve gotten more done than most articles have gotten me in just setting up the Acl… and it’s not all that difficult. It’s Ketan’s How to use Acl with Cake PHP 1.2.x?* No dobut some of you will stumble across this post here, and hopefully find it useful. I think once the dust settles on the first step, you(we) will be able to look at some of the other tutorials and adapt them to our own specific needs.

I’ll try to keep this post updated with additonal solutions as I find them.

* There ARE some typos in the example code, so be aware of that and make modifications as necessary.

I use this blog quite a bit for documenting little quirks, bugs, work-arounds, neat things, and tutorials so that I know where I can find the solution in the future. At the same time, you benefit by hopefully not having to go through some of the same messes I did just to get to this point.

I love CakePHP so far (but still quite the noob), but my biggest gripe is the documentation. The basics are there, but there’s often too little documentation to get the novice going. From the Bakery docs, it’s not exactly clear how to perform tests on models when HABTM (has and belongs to many) relationships are involved. Have no fear, it’s doable (though not straightforward).

Hopefully you baked your MVC pieces and included test scripts to go along with them. If not, do that first. The key part to getting the tests for models that have HABTM relationships is to set-up a fixture representing the table that stores the relationship. Don’t actually set-up the test – just the fixture.

It has been an interesting month – at the same time I’m picking up CakePHP, I have a client project that uses the Zend Framework. Right out of the gates I like CakePHP better. ZF doesn’t seem quite as cohesive as Cake, so getting it set-up has been more challenging. Granted, the client’s setup is a little more complex than the standard setup, but it still seems like there’s a lot more work involved just to get things going – lots more configuration. After two days on Zend I already realize how spoiled I am with Cake.

With Cake, I’m finally starting to learn unit testing. It seems real simple in theory, and I’m sure it is once you get the hang of it, but it is tedious. I’m talking about the amount of actual work involved just getting these test cases working. My simple pleasure at the end of the day is watching the screen fill up with a bunch of green “Pass” statements… no red.