Create a bbBolt Server

bbBolt is designed to be quick to setup, but also highly configurable. The Short Version of this section will get a bbBolt Server up and running in minutes. The Long Version then details all of the available options for configuring your server.

The Short Version

There is no administration interface or default plugin for configuring a bbBolt server. Instead, you must create your own plugin to register the server. This ensures that your Server has the required details for running your server.

Before you can create a bbBolt server, you must upload the bbBolt directory to your web server. You can either upload it into the base /wp-content/plugins/ directory or place it within a different directory in the plugin’s directory, for example /wp-content/plugins/my-server-setup/.

Once the bbBolt files are available, you can create a plugin to manage your bbBolt Server.

The plugin should have the usual WordPress Plugin header as outlined in the Codex article on writing a plugin (http://codex.wordpress.org/Writing_a_Plugin#File_Headers).

The plugin must also require the bbbolt-server-class.php file.

<?php
 /*
 Plugin Name: My bbBolt Server
 Description: A plugin for running a bbBolt Server on my website.
 Author: Your Name
 Author URI: http://example.com
 Version: 1.0
 */

require_once( PATH_TO_BBBOLT . '/bbbolt-server.class.php' );

Once we have a plugin header and have included the bbBolt server class, we can create our bbBolt server using the register_bbbolt_server() function. 

register_bbbolt_server( $name, $paypal_credentials, $args );

Parameters:

To create a bbBolt Server, you must call this function and pass it at least two parameters.

  • $name (string)(required) – the name of your plugin or support system
  • $paypal_credentials (array)(required) – an array containing your PayPal API credentials with the keys:
      • ‘username’ (string)(required) – your PayPal API Username
      • ‘password’ (string)(required) – your PayPal API Password
      • ‘signature’ (string)(required) – your PayPal API Signature

If you do not have your PayPal API credentials, refer to the PayPal API Credentials section later in this document for instructions on where to access them.

Calling the Registration Function

You can call the register_bbbolt_server() function from any file in your plugin, but it must be called from within the WordPress init hook.

For example:

function eg_register_test_server(){

     $paypal_credentials = array(
          'username'  => EG_PAYPAL_USERNAME,
          'password'  => EG_PAYPAL_PASSWORD,
          'signature' => EG_PAYPAL_SIGNATURE
     );

    register_bbbolt_server( 'test-server', $paypal_credentials );
}
add_action( 'init', 'eg_register_test_server' );

That’s all that is required. Once we activate this plugin via the WordPress Plugin administration page, it will create a bbBolt Server which runs in test mode (using the PayPal Sandbox) and charges a $20/month subscription fee for registration. If you want to change the subscription price, set the Server to be live or configure it in a myriad of other ways, read on.

The Long Version

Whilst reading The Short Version, you may have noticed that register_bbbolt_server() function accepts an optional third parameter that was not discussed. This parameter is an associative array of arguments for configuring the bbBolt Server and subscription model.

register_bbbolt_server( $name, $paypal_credentials, $args );

Parameters:

  • $args (array)(optional) – an associative array of arguments for configuring the bbBolt Server.

Arguments

The $args array can contain any of the following named arguments.

‘site_url’ (string) – the URL on which the bbBolt Server is running. The default value of the site_url is the WordPress get_site_url() function, which returns the URL of the current site.

‘labels’ (array) – associative array of labels for the client, currently only supports ‘name’ & ‘description’ labels. By default, the ‘description’ label will be used in the subscribers PayPal account to describe what the recurring payment is for. Defaults to “{Blog Name} Support Subscription”.

‘registering_plugin’ (string) – the file and directory of the plugin which is registering this server. Defaults to the folder and file two steps back in the stacktrace because bbBolt assumes your plugin will call the register_bbbolt_server() function, which creates the class. This detail is necessary for deactivating the registering plugin if bbPress is not active.

‘paypal’ (array) – associative array of arguments to configure the PayPal environment, recurring payment model and signup process. The following arguments can be configured within the PayPal array:

  • ‘sandbox’ (boolean) default true – Boolean flag on whether to use the PayPal Sandbox or PayPal production environment.
  • ‘currency’ (string) default ‘USD’ – Any ISO-4217 Currency Code which is supported by PayPal Digital Goods
  • ‘cancel_url’ (string) – the URL to which the customer is returned if she cancels the PayPal authorisation process. Defaults to ‘bbbolt=paypal&return=cancel’ appended to the value of the ‘site_url’ argument.
  • ‘return_url’ (string) – the URL to which the customer’s browser is redirected after successfully authorising the recurring payment with PayPal. Be careful changing this as the subscription does not commence until the user signs up with your site after authorising the payment. Defaults to ‘bbbolt=paypal&return=paid’ appended to the value of the ‘site_url’ argument.
  • ‘subscription’ (array) – an associative array to customise the details of the recurring payment model for your support service.

Customising your Subscription Model

The ‘subscription’ array provides a number of options for customising the price time and trial period of your support service. The array includes:

  • ‘start_date’ (date) – the date and time to start the subscription. Defaults to a day in advance as PayPal requires the start date not be prior to the current date. The date must be formatted as Y-m-d\TH:i:s.
  • ‘description’ (string) – the description of the recurring payment profile displayed in the user’s PayPal account.

The price of the subscription can be configured with the following arguments in the ‘subscription’ array:

  • ‘amount’ (string) – the price of the subscription per period. Defaults to ‘20.00’. The specified amount cannot exceed USD $10,000.00.
  • ‘initial_amount’ (string) – an optional non-recurring payment that must be made when the recurring payments profile is created. Defaults to ‘0.00’.
  • ‘average_amount’ (string) – an indication of the average amount of each transaction for the recurring payment. Defaults to ‘25.00’, which is also the PayPal default. If your subscription is higher than 25, you should specify this value to be equal to or greater than amount.

The temporal details of the subscription can be configured with the following arguments:

  • ‘period’ (string) default ‘Month’ – the unit to calculate the billing cycle. One of Day, Week, Month, Year.
  • ‘frequency’ (int) – default 1 – the number of billing periods that make up the billing cycle. Combined with period, must be less than or equal to one year. For example, the a frequency of 12 would specify to charge the subscription once every 12 months, or once per year.
  • ‘total_cycles’ (int) – default 0 – the total number of billing cycles. If you do not specify a value or specify 0, the payments continue until PayPal (or the buyer) cancels or suspends the subscription. A value other than the default of 0 terminates the payments after the specified number of billing cycles. For example, if ‘total_cycles’ = 2 with frequency = 12 and period = Month would continue the payments for two years.

PayPal also provides a facility for having an optional trial period as part of the subscription. This trial period can include a different price, period & frequency to the standard subscription.

The trial period can be configured with the following arguments  in the ‘subscription’ array:

  • ‘trial_amount’ (string) default ‘0.00’ – the price for each period in the trial cycle. If 0 or ‘0.00’, not trial is added to the subscription.
  • ‘trial_ period’ (string) default ‘Month’ – similar to ‘period’, the unit to calculate the trial cycle. One of Day, Week, Month, Year.
  • ‘trial_frequency’ (int) – default 0 – the number of periods that make up the trial cycle.
  • ‘trial_total_cycles’ (int) – default 0 – the total number of trial cycles.

A Note on Currency Values

When passing a currency value as a parameter, to ‘amount’ for example, PayPal requires that regardless of the specified currency, the number must be formatted with a decimal point. The decimal point must include exactly 2 digits to the right and can have an optional thousands separator to the left, which must be a comma.

For example, EUR 2.000,00 should be specified as 2000.00 or 2,000.00.

Securely Storing your API Credentials

You may have noticed that in the example above, before calling the register_bbbolt_server() function, the $paypal_credentials were allocated from constants (EG_PAYPAL_USERNAME etc.). Your first thought may be to hardcode your PayPal API Credentials within the function that calls register_bbbolt_server() – this is not a good idea.

For security reasons, you should store your API credentials in your site’s database. Ideally, you should also encrypt the credentials using PHP Mcrypt (http://php.net/manual/en/book.mcrypt.php). Storing real credentials in a source code file is a security risk.

Alternatively, you can define the credentials as constants in your wp-config.php file (http://codex.wordpress.org/Editing_wp-config.php). This does not provide as much protection as encrypting your credentials and storing them in the database, but if a potential intruder has access to your wp-config.php file, they will also have access to your WordPress table in the database.

Sandbox to Production

If you skimmed over The Long Version of these instructions, you may have missed the boolean flag to tell bbBolt whether to use the PayPal Sandbox environment or production environment.

By default, bbBolt uses the Sandbox environment. To switch to the production environment, your $args array must set the PayPal Sandbox flag to false.

For example:

function eg_register_test_server(){
     ... // Set credentials & other args values
     $args[‘paypal’][‘sandbox’] = false;
     register_bbbolt_server( 'test-server', $creds, $args );
}

bbPress Requirements Check

As bbBolt makes use of a number of bbPress functions, it runs a check on activation and initialisation to ensure that bbPress is active. If you are confronted with the following screen, you must install and activate the bbPress plugin.

bbPress Requirements Check Screenshot

bbPress Requirements Check