@p9k nope: `bundle install –path vendor –binstubs` and add ./bin to PATH. Gemsets are a terrible idea.

— Chris Moore (@cdmwebs) November 12, 2012

Going to start inlining Zepto into all my bookmarklet and widget Javascript. All the benefits of jquery without the big download.

— gerard sychay (@hellogerard) September 29, 2012

which prompted:

@hellogerard share a sample, please.

— Richard Bronosky (@RichardBronosky) October 12, 2012

Unfortunately, the code I was referring to was client code, but how about a blog post?

The Widget Problem

For whatever reason, I have been writing lots of Javascript widgets and bookmarklets.  This type of 3rd-party code is usually copied and pasted into a website or initiated via a boorkmark (both work in similar fashion). The tricky party about widgets is that the code must be lean and fast, and must be robust to hostile environments.  By hostile environments, I mean that you can’t make any assumptions about a particular website these days.  If you’ve ever tried to scrape arbitrary webpages, you know what I’m talking about.

The problem with jQuery is that sometimes it is neither lean nor fast, and you can’t assume that the website hosting your widget has jQuery already, or has a particular version of jQuery.  But we need jQuery.  We need its selectors, and Ajax helpers, and CSS helpers.  The solution is to load our own jQuery.

I Got Mine (jQuery)

Start with the typical function expression module that isolates your code from any other Javascript.

(function(document, undefined) {

  // ... your isolated code

})(document);

Load jQuery asynchronously, and prepare a callback that runs when jQuery is loaded.

(function(document, undefined) {

  // Load our own jQuery
  s = document.createElement('script');
  s.src='//ajax.googleapis.com/ajax/libs/jquery/1.8.0/jquery.min.js';
  s.onload = function() {
    // ... 
  });

  d.getElementsByTagName('head')[0].appendChild(s);

})(document);

When jQuery loads, it will assign itself to the $ variable, overwriting whatever was using it beforehand, such as the host site’s copy of jQuery.  Fortunately, jQuery keeps a copy of the original value, and running jQuery.noConflict() restores the original value of $ and returns the latest value.  Run $.noConflict() to get our own, local copy of jQuery in the $ variable.

(function(document, undefined) {

  // Load our own jQuery
  s = document.createElement('script');
  s.src='//ajax.googleapis.com/ajax/libs/jquery/1.8.0/jquery.min.js';
  s.onload = function() {
    var $ = jQuery.noConflict();
    // ... $ now safe to use
  });

  d.getElementsByTagName('head')[0].appendChild(s);

})(document);

Can We Do Better?

This works well. However, if the thought of a whole network request (even if cached) just to run your widget bothers you, there’s a surprisingly simple alternative: inline jQuery.  That is, copy and paste the entire jQuery library into your widget code.  This may seem unusual, but despite it’s size, it’s still cheaper than a network request.

(function(document, undefined) {

  // Load our own jQuery
  /*! jQuery v@1.8.1 jquery.com | jquery.org/license */
  (function(a,b){function G(a){var b=F[a]={};return ...

  var $ = jQuery.noConflict();
  // ... $ now safe to use

})(document);

Can We (Still) Do Better?

If inlining all 91k (as of 1.8.2) of jQuery also bothers you: consider Zepto (23k for 1.0RC1). Zepto is billed as “a minimalist JavaScript library for modern browsers with a largely jQuery-compatible API.”

(function(document, undefined) {

  // Load our own Zepto
  /* Zepto v1.0rc1 - polyfill zepto event detect fx ajax form touch - zeptojs.com/license */
  (function(a){String.prototype.trim===a&&(String.prototype ...

  var $ = window.Zepto;
  // ... $ now safe to use

})(document);

Zepto, unlike jQuery, will not assign itself to $ if it is already defined, so no issue there.

Now, don’t make the mistake I did in thinking Zepto is a drop-in replacement as a “lightweight” jQuery because it certainly is not, especially in CSS manipulations.  Support for CSS effects in IE is sketchy, and its Ajax helpers are a bit different.  However, Zepto gives you all the selectors and DOM manipulators you’re used to, has all the Ajax helpers you need, and offers useful utilities such as $.proxy().

So if you need visual effects in your widget, Zepto will probably not do. But if all you need is the ability to add/remove/select elements, then Zepto works great as a jQuery replacement.

Also, if you’re like me, you run into the same problems over and over:

• Manually maintaining crontab files is a burden.
• Frequent jobs that stall or delay may start running multiple copies.
• Knowing when a job fails automatically is tough because honestly who has time to look at log files?
• If you have a webfarm, you have to decide which jobs run on which servers, or all of them.

Enter jobby, the PHP cron job manager.

Install a single crontab entry on each of your servers, and never edit crontab again.  The master cron job runs a PHP file which contains all of your real jobs and executes them according to their individual schedules (using crontab syntax) along with other configs. The nice thing is that since jobby is just PHP, you can decided what jobs to run and when programmatically. Now, I know there are more expansive server configuration tools out there, but those felt too heavy for this kind of use.

More features: jobby will ensure only 1 copy of a job runs at a time, can email one or more recipients if a job fails, and can run as different users on select hosts.

I developed a version of jobby years ago, and have brought it along with me on various projects, slowly tweaking it.  It’s helped me immensely and if you’re interested, check out the README and composer install away!

• 8 ways to share your git repository
• [SO] How to make a git repository read-only?

When read altogether, I had a few options.

1. Run the git-daemon. The repo would be publicy available over the internet via the git (git://) protocol.  This provides read-only access, but it provides it to the whole world.  Not a solution.
2. Run a GitHub-like server, like Gitosis or Gitolite.  This was the sledgehammer solution.  Fine-grained access control, plus all the other bells and whistles. But I was not interested in installing and understanding a whole git-hosting server application.
3. SSH via git-shell.  Each user gets a regular SSH account on the server, but each user gets a git-shell instead of a regular login shell like bash. The git-shell restricts the user to git operations.  Write permissions are restricted using standard Linux permissions on the repo itself.

So #3 was what I needed. I created an SSH login for each user that needed access to the repo. I set the login shell for each user to /usr/bin/git-shell. I put each user in a group that had read-only file system permissions to the repo.  Testing it out worked well.  Users could git clone and pull, but pushing failed and attempting to SSH directly failed.

One last note: as the man page mentions, you can create a directory called git-shell-commands in home directories of git-shell users.  git-shell users will be able to run any command in this directory.  If there is a help program in the directory, it is run when a git-shell user logs in.  More details on git-shell-commands here, including the location of sample git-shell commands on your server.

Normally, you will link to your Blueprint screen.css file like so:

The following lines tell the browser to link first to a mobile-friendly CSS file. Then, if and when the width is 600px, link to the normal, desktop CSS file. The idea is that bandwidth is scarcer on mobile, so we don’t mind downloading two files on a desktop machine if we have to.

To create my mobile.css, I copied screen.css, and made the following changes.

1. Change table elements padding to 2px 

   th, td, caption {padding: 2px;}

2. Resize all image widths to fit on screen 

   a img {border:none;max-width:90%}

3. Change input text fields to 67% width. 

   input.text, input.title {width: 67%; padding: 5px;}

4. Change textarea inputs to 80% width, and reduce height to 150px. 

   textarea {width: 80%; height: 150px; padding: 5px;}

5. Change the overall container to 90% width. 

   .container {width: 90%; margin: 0 auto;}

6. Change all span grid classes to 100% width. 

   .span-1 {width: 100%;}
   ...
   .span-24 {width: 100%; margin-right: 0;}

7. For some reason, I ended up deleting all input.span and textarea.span classes, though I’m not sure why now.
8. Change all append grid classes to 0px right padding. 

   .append-1 {padding-right: 0;}
   ...
   .append-24 {padding-right: 0;}

9. Change all prepend grid classes to 0px left padding. 

   .prepend-1 {padding-left: 0;}
   ...
   .prepend-24 {padding-left: 0;}

10. Change all pull grid classes to 0px left margin. 

    .pull-1 {margin-left: 0;}
    ...
    .pull-24 {margin-left: 0;}

11. Change all push grid classes to 0px margin. 

    .push-1 {margin: 0;}
    ...
    .push-24 {margin: 0;}

Not pretty, but it seems to work well.  Happy CSS!

Facebook authentication, much like the rest of the platform, can be maddening.  It appears easy enough at 1st glance, until you realize the contrived XFBML examples in the docs will not get you very far.  So then you might take a look at the advanced document. And then realize that the advance document, that giant, complicated, very detailed and thorough explanation of OAuth 2.0 as implemented by Facebook, does not actually help you code your website.

This blog post is more for my benefit than yours, and serves to summarize my current Facebook authentication strategy, so I don’t have to figure it out over and over. At least, until Facebook changes it.

My Requirements

First off, realize that there are 3 ways to do any particular thing on the Facebook platform: XFBML, JS, and PHP (server-side).

That said, I do not use the XFBML <fb:login/> button.  XFBML is great for non-developers who can copy and paste the documentation into a website and impress their friends.  But XFBML is slower, ties your user’s application session to your user’s Facebook session, and you can’t make general API calls, so you may as well learn how to use the JS or PHP SDKs anyway.

1. Authentication flow must work with and without JavaScript, as we are targeting older smart phones, such as Blackberry Curves.
2. I do not want to use Facebook to persist my application sessions.  I merely want to use Facebook for authentication and then use standard PHP sessions to maintain a user login.  Using the Facebook session as your application session (as in the case of XFBML above) is sucky.  You will noticed sites that do this because when you log out of the site, you will log out of Facebook, and vice-versa.  Logging out of your site should not log you out of Facebook.  Facebook sessions and your application’s session should be separate.  I want to use Facebook only to authenticate the user, that is, to confirm the user is who they say they are.  Foursquare does a great job of this.

Implementation

First, I need a login login link that non-JS browsers can use.

<a id="fb-login" href="<?= $loginUrl ?>">Login</a> 

That $loginUrl comes from:

$loginUrl = $facebook->getLoginUrl(array('scope' => 'offline_access')); 

The login link will ask the user for offline_access permission, as an example.

Then we need some the FB JS SDK to handle the link for those of us with modern browsers.

            
FB.init( { appId: 'XXXXXX', status: true, cookie: false, oauth: true } );

$('#fb-login').click(function(e) {
  e.preventDefault();

  FB.getLoginStatus(function(response) {

    // maintain application anchor/query string, if any
    q = window.location.search.substring(1);
    if (window.location.hash) {
      q = window.location.hash.split('?')[1];
    }

    // if already logged in, redirect
    if (response.authResponse) {
      window.location.href = '/?signed_request=' + response.authResponse.signedRequest + '&' + q;

    } else {

      // else present user with FB auth popup
      FB.login(function(response) {

        // if user logs in successfully, redirect
        if (response.authResponse) {
          window.location.href = '/?signed_request=' + response.authResponse.signedRequest + '&' + q;
        }
      }, { scope:'offline_access' } );
    }
  });
});

Couple interesting things to point out:

1. In the call to FB.init(), the cookie flag is set to false.  In most FB examples, this flag is set to true.  If this flag is true, the JS will set a cookie (that begins with ‘fbsr_’) that will keep the user connected to your Facebook app during a browser session.  This can confuse your app, because if you do not clear this cookie when your user logs out, your app may automatically re-authenticate your user.  If you do intend to use your user’s Facebook session as your website’s session, set this flag to true.
2. On lines 16 and 25, as in most FB examples, a simple window.location.reload() might appear.  This only works if the JS sets the Facebook cookie, as this cookie will tell the server that the user is authenticated after the reload.  Since we can’t use the cookie, we need another way to tell the server if this login attempt was successful.

Server side

On the server-side, Facebook will tell us if this user is who he says he is with the getUser() method.  If this method returns a non-zero user ID, then Facebook has authenticated this user, and we can create a normal PHP login session, however you usually do that.

$id = $facebook->getUser();

if ($id)
{
    // login successful
    $_SESSION['user'] = $id;
}

// redirect to user dashboard or something
header('HTTP/1.1 302 Found');
header('Location: /');
exit;

getUser() tries to authenticate a few different ways.  You can read the code in the PHP SDK if you’re really curious. One way is from the ‘fbsr_’ cookie.  Another is by checking for the signed_request in the query string.  Remember when we passed that in earlier via JS?   The cool thing is, that even in the non-JS case, Facebook will send that signed_request in the query string, so this code will function the same in both cases.

Keeping the user logged in as he makes requests is the same as usual.  I simply check for the flag (or, in the example above, a user ID) to verify authenticated status.

To logout, I can simply clear the PHP session like normal.

// logout
session_unset();
session_destroy();

// redirect to external home page
header('HTTP/1.1 302 Found');
header('Location: /');
exit;

Again, this does not log me out of Facebook

Conclusion

When might you want to use your user’s Facebook session for your user’s website session?  I think the only case you would do that is if your web app is a Facebook-centric application.  That is, if every feature of your app involves Facebook somehow. In that case, maybe it makes sense because your user cannot use your app without being connected to Facebook.

You can find a fully working example of this flow on my GitHub.  This really belongs in an MVC-type framework, but for simplicity I put everything in a giant if/else statement.  Throw the files in a webroot, add your app’s ID and secret to the PHP file, and try it out. Try it with JavaScript enabled and disabled.  After logging into the example, try logging out of Facebook, and then logging out of the example, and vice-versa. And let me know if you spot anything fishy.

All apps must migrate to OAuth 2.0 for authentication and expect an encrypted access token. The old SDKs, including the old JS SDK and old iOS SDK will no longer work.

<digression> In the spirit of typical Facebook developer documentation, even this ostensibly unambiguous statement raises questions.  See, I have been using the “new” Graph API to authenticate for many months now, but not with the oauth flag set to true.  (In other words, I am on Oauth 1.0?)  Does this mean my code will break on Oct. 1st?  Or when they say that legacy authentication will break on Oct. 1st, do they mean that only the really old legacy auth will break?  In either case, I may as well upgrade to the latest and greatest now. </digression>

Here are the changes I had to make to get my stuff working with the oauth flag set to true.  They are mostly field and param name changes.  There may be other changes important to you, but this is what I needed to modify to upgrade.

1. Add ‘oauth: true‘ to FB.init()

So change this:

FB.init({ appId : XXXXXX });

to this:

FB.init({ appId : XXXXXX, oauth : true });

I infer from Facebook (which is usually dangerous) that this flag will be enabled for everyone on Oct. 1st.

2. Change ‘perms‘ to ‘scope‘

Anywhere you request permissions for your app upon Facebook login, you must change the ‘perms’ field to ‘scope’. So for a typical XFBML implementation, change this:

<fb:login-button perms=”offline_access”></fb:login-button>

to this:

<fb:login-button scope=”offline_access”></fb:login-button>

For a typical JS implementation, change this:

FB.login(function(response) { }, { perms : ‘offline_access’ });

to this:

FB.login(function(response) { }, { scope : ‘offline_access’ });

For a typical non-JS, server-side (PHP) implementation, change this:

<a href=”<?php echo $facebook->getLoginUrl(array(‘req_perms’ => ‘offline_acces's’)); ?>”>Connect with Facebook</a>

to this:

<a href=”<?php echo $facebook->getLoginUrl(array(‘scope’ => ‘offline_acces's’)); ?>”>Connect with Facebook</a>

3. Update JavaScript response object

Functions like FB.login() and FB.getLoginStatus() accept a callback that gets passed a response object from Facebook after an authentication attempt.  The previous response looked like this:

response = { perms : ‘offline_access’, 
             session : { 
               access_token : ‘XXXXXX’, 
               base_domain : ‘mydomain.com’, 
               expires : ‘0’, 
               secret : ‘XXXXXX’, 
               session_key : ‘XXXXXX’, 
               sig : ‘XXXXXX’, 
               uid : ‘XXXXXX’ }, 
             status : ‘connected’ };

The new response looks like this:

response = { authResponse : { 
               accessToken : ‘XXXXXX’, 
               expiresIn : 0, 
               signedRequest : ‘XXXXXX’, 
               userID : ‘XXXXXX’ }, 
             status : ‘connected’ };

You must update your JS authentication logic accordingly.

4. Change server-side PHP call getSession() to getUser()

Versions of the PHP SDK prior to 3.0 had both a getSession() and a getUser() method. After 3.0, there is only the getUser() call.  If you were using getSession() to check for authentication previously, you must use getUser() now.  If you don’t care about the internals of the new SDK, then getUser() functions the same as before and returns the Facebook ID of the currently logged in user, or 0 if there is none.

If you do care about the new SDK, then the reason for this is because Facebook has done away with the session concept and embraced the OAuth2 signed_request concept instead.  For example, the JSON-ified session array is no longer passed back to your callback URL in the query string upon authentication.  Now, an encoded signed_request is passed back in the query string, which contains the same info (user ID, access token, expiration time, etc.)

5. Change server-side PHP Facebook class constructor

The new PHP Facebook class no longer accepts a cookie flag in the constructor.  If you don’t care about the internals of the new SDK, then remove the cookie flag and you’re done.

If you do care about the new SDK, then the reason for this – well, I’m not sure what the reason is.  Perhaps a commenter could enlighten me.  Best as I can tell, they have removed overlapping features of the the JS SDK and PHP SDK. Prior to OAuth2, both SDKs had cookie flags, and both could set and read the session cookie, which could be confusing, especially if you were persisting your own authentication cookie.  Now, the JS can still set and read the signed_request cookie, but the PHP library has gotten out of the cookie game (although it can still read a signed_request cookie set by JS, and now it stores the signed_request data in the PHP session).

One more note about cookie: the new Facebook cookie begins with ‘fbsr_’ and not ‘fbs_’.

Conclusion

That’s it. As I said, these worked for me, but YMMV. Happy upgrading!

Of (PHP) Sessions, Cookies, and Authentication

Do you know the difference between the PHP config directives session.gc_maxlifetime and session.cookie_lifetime? Have you wrestled with implementing a “Remember Me” button on your login page? Learn how popular sites, such as Twitter and Facebook, keep you logged in (apparently) forever and the security risks of such methods.

Who’s Using Your Software?

Software is only successful if someone can use it. Good developers need to do more than just follow specifications, they need to visualize the people who will use it and understand what they need. Get to know your users and the questions you need to ask to make your implementation a success on all fronts.

Last month, Chris Shiflett proposed an excellent blog revival idea, wherein I am to write a blog in the month of March about why I like blogs.  Of the ones I managed to read, I liked this “Ideas of March” the best. As for me, well, we are halfway through April – but I started this draft in March?  Here were the rules:

1. Write a post called Ideas of March.
2. List some of the reasons you like blogs.
3. Pledge to blog more the rest of the month.
4. Share your thoughts on Twitter with the #ideasofmarch hashtag.

So here goes…

Way before I had a technology blog, I had a blog about local issues.  Local politics, sports, development, you name it.  I started that blog because I had a lot of opinions about development that was happening around me and issues that were balloted, and I couldn’t rob the world of my enlightened positions by keeping them to myself.   Blogs allow anyone with something to say to say it.

Blogs are ultimately social.  Before there were tweetups, there were blogger meetups. And it is very easy to have something to talk about when introducing yourself to someone (“Hey, I really liked your blog about…”).  Twitter has taken that “breaking the ice” concept to new levels, but it I’d much rather have someone come up to me and say that they’ve read my blog rather than say that they follow me.

Blogs are written, and writing is a good skill to practice.  If I have to write to explain something, then I have to know it well.  And with practice, the explanation gets better and clearer. Then other thoughts get better and clearer.  Then the world just gets better and clearer.

Oh, and blogs contain a crapload of useful information that solve all sorts of problems, or just spread interesting news.

In summary, I like blogs because:

1. They give everyone a voice.
2. They help people be more social.
3. They help me improve my writing.
4. They contain a crapload of useful information and news.

To round off the requirements, I pledge to blog more in this month of March, er – how about I just pledge to blog more?  And hopefully my RSS tweeter should get out the hashtag in the title.

My biggest source of confusion was the bootstrap process.  Namely, the autoloading of resources.  Yes, I followed the Zend Framework Quick Start and got my app up and running. Unfortunately, I didn’t actually know what was happening.  Finally, I came across this great question on Stackoverflow about bootstrapping the layout resource that pointed me in the right direction:

The line from application.ini

resources.layout[] = 

is equivalent to:

_initLayout() {}

in Bootstrap.php

Aha!  So now it was clear. There are two ways to initialize a resource in Zend:

1. By adding one or more mysterious lines to your application.ini, or
2. By constructing them with good old fashion code in a method that begins with “_init” in Bootstrap.php.

Option #1 bothers me.  Yes, it’s really cool that you can bootstrap a whole MVC application with no code and only a config file, but IMO that option should not be the recommended way for beginners and that options should most definitely not be used in any sort of “Quick Start” guide.  That sort of magic should be reserved for advanced users.  With a little more exploring, I found the code that initialized these resources in the non-trivial Zend_Application_Bootstrap_BootstrapAbstract class.  And I found all the built-in Zend resources in Zend/Application/Resource, which let me see which resources had which options and how to bootstrap them. 

On to option #2, my preferred way. If I want to initialize the Front Controller, I’ll just put this in the bootstrap file:

    
protected function _initFrontController()
{
    $front = Zend_Controller_Front::getInstance();
    $front->setControllerDirectory(APPLICATION_PATH . '/controllers');
    return $front;
}

If I want to enable and initialize the layout:

    
protected function _initLayout()
{
    $layout = Zend_Layout::startMvc();
    $layout->setLayoutPath(APPLICATION_PATH . '/layouts/scripts/');
    return $layout;
}

I really don’t mind carrying this around to every project.  Then I can make changes in the PHP, and not in an INI file.

Clearly I am not the only one struggling with this. I googled problems heavily and the top results usually contained 3 or 4 of the same question asked on Stackoverflow, each of which I opened in a tab.  I think Zend would benefit with a re-organization of the documentation from the ground up, at least of the starter docs and Zend_Application. They should also post a big, flashing red link to that Stackoverflow question about bootstrapping layout. 

Eventually, other components became clear: Resources, Plugins, Action Helpers, and View Helpers, Modules.  I see real power in using the Zend Framework now, particularly with Plugins and Modules, but only after much pain.

I have created a starter project for Zend projects that contains Bootstrap.php the way I like it, and some other custom classes for logging and error handling.  There is a branch for a starter project with modules and without modules.  (Modules is a different blog post altogether.)