Create a BigCommerce PHP App on Heroku

With our focus on B2B eCommerce, many of our BigCommerce customers ask us to create customizations that expand the scope and reach of the BigCommerce platform. Typically, this means we’ll need to create a separate web app, as we often need to integrate with another system, database or third-party API. If you’ve never created an app like this, then the BigCommerce Hello World app for PHP is a good place to get started. An easy way to deploy the Hello World app is on Heroku.

I’ll show you how you can update and deploy the Hello World app on Heroku in a few easy steps. Here is what you need to get started:

• A Heroku account (free)
• PHP and composer installed locally
• git
• a developer account on BigCommerce

First, let’s clone the hello-world PHP app from BigCommerce. On your local machine, change to your favorite directory for new projects and then clone the repo from github.

git clone https://github.com/bigcommerce/hello-world-app-php-silex

Now, cd into the hello-world-app-php-silex directory. Let’s start by changing up a few of the dependencies in composer.js. I removed the dependency on “colinmollenhour/credis” and replaced it with “predis/predis” since predis is one of the preferred redis clients for Heroku. My composer.js now looks like this:

   "require": {
         "silex/silex": "1.*",
         "guzzle/guzzle": "~3.7",
         "propel/propel1": "~1.6",
         "realityking/hash_equals": "dev-master",
         "predis/predis": "1.1.*@dev",
         "alrik11es/cowsayphp": "^1.0",
         "monolog/monolog": "^1.19"
  },  

For fun, I added a dependency on cowsay and monolog for some simple logging. Once, you’ve made the same changes to composer.js, run

composer update

from the command line to retrieve those dependencies and update the composer.lock file.

Now, let’s move some things around. Create a folder called web and move the existing index.php and .env-example files in there. Next let’s update our Procfile for Heroku. Let’s tell Heroku that we have a web app using PHP and Apache2 and that our root folder will be web.

web: vendor/bin/heroku-php-apache2 web/

Since we decided on a different redis client, let’s update the index.php in /web to use Predis. You’ll find two lines in the file that start with $redis. Update those to use Predis:

$redis = new Predis\Client(getenv('REDIS_URL'));

Also in index.php, change the return value of the load function to something fun:

return "<pre>".\Cowsayphp\Cow::say("Cool beans, your app is loaded")."</pre>";

Add a log request to the load function:

$app['monolog']->addDebug('load'); 

Add some more functions:

// Our web handlers
$app->get('/', function() use($app) {
  $app['monolog']->addDebug('logging output.');
 return 'Welcome to Root! I got nothing.';
});

$app->get('/cowsay', function() use($app) {
  $app['monolog']->addDebug('cowsay');
  return "<pre>".\Cowsayphp\Cow::say("Cool beans")."</pre>";
});

Now, we can create an .htaccess file in our web folder to house our BigCommerce environment variables – we’ll fill these values in after we register our app with BigCommerce.

# Set up variable for our app
SetEnv BC_AUTH_SERVICE "https://login.bigcommerce.com"
SetEnv BC_CLIENT_ID "7xxxxx"
SetEnv BC_CLIENT_SECRET "etprsizegxxxxxxx"
SetEnv BC_CALLBACK_URL "https://my-first-bc-app.heroku.com/auth/callback"

RewriteEngine On

# Redirect Trailing Slashes...
RewriteRule ^(.*)/$ /$1 [L,R=301]

# Handle Front Controller...
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]

Next we want to deploy this app to Heroku. Follow these steps and prompts from your command prompt to login, create, deploy and set0up a dyno for http traffic:

heroku login

heroku create my-first-bc-app

git push heroku master

heroku ps:scale web=1

Now, we need to add the Redis add-on to our Heroku instance. You’ll need a credit card on your account at Heroku to do this, but the hobby-dev version we’re adding is free so you won’t be charged anything.

heroku addons:create heroku-redis:hobby-dev

Now, you should be able to open your web app in a browser.

heroku open

If you added our extra functions you can go to https://my-first-bc-app.herokuapp.com/cowsay and see a silly message.

        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
 

Did you run into any problems? Try tailing the logs and hitting the site again.

heroku logs --tail

Once you have everything running, you’ll need to register your new app with BigCommerce.

1. Visit https://developer.bigcommerce.com.
2. Click Log In.
3. Provide your credentials at the prompt (same as you use to log into your store).
4. Click My Apps.
5. Click Create an app.
6. Provide a name for your app at the prompt.
7. lick Next> through App Summary, Details, and Launch Bar: no entries required.
8. On the Technical page, type https://my-first-bc-app.heroku.com/auth/callback into the Auth Callback URL field.
9. On the Technical page, type https://my-first-bc-app.heroku.com/load into the Load Callback URL field.
10. Select some OAuth scope other than the defaults – read-only is fine.
11. Click Save and close.
12. Click View Client ID
13. Copy the Client Id and Client Secret to your .htaccess file environment variable values
14. Add https://my-first-bc-app.heroku.com/auth/callback for the BC_CALLBACK_URL in .htaccess

Now, commit your .htaccess changes and redeploy to heroku:

git add .

git commit -m 'Update .htaccess'

git push heroku master

Now, let’s run the app install in our store.

1. Log into your store and go to your control panel.
2. Click Apps in the left-hand navigation bar.
3. Click My Drafts in the top navigation bar.
4. Click the sample app. It will have the name that you assigned it in the developer portal.
5. Click the Install button.
6. You should see the return value from your /auth/callback method in index.php
7. Refresh the page to call the /load method and see a cowsay message.

That’s all there is to it. Of course, you’ll have to make it do something useful now. 🙂