With a private alpha release due out soon, we’re gearing up to help developers take full advantage of the 3.0 platform. Our goal is to make it as easy as possible to build really advanced plugins, widgets, gateways, and modules. To facilitate that we’ve written some detailed interfaces and libraries, as well as put together a pretty in-depth developer manual. And while the v3 source is almost entirely open, I figured what the heck, how about some source code documentation? So I created Doctorate.

Doctorate is a simple plugin for minPHP that documents source code using Reflection. Being able to read the source documentation without actually having to open the source code is a huge advantage. But because the Blesta API is just a simple access wrapper for the Models it’s a huge time saver for us. It would take months to document every API request (there are hundreds and hundreds), but Doctorate does it automatically.

Here is a sneak peak of the source code documentation from Doctorate…

Here is a sneak peak at the developer manual…

So when can you expect to get your hands on the developer manual and source documentation? If you’ve made it onto our developer list you can take advantage of these resources as soon as alpha is released. When 3.0 goes into beta we’ll make the documentation public.

Last week I introduced the Blesta import library, discussed why this is an important feature of Blesta and touched a little bit on how to work with the library. This week we get a little more technical and dive a bit deeper into the import library, but first a little history on the topic. The import library has been available since version 1.0, but the documentation was only made available as of version 1.3. If you are using a version older than 1.3 some functions may or may not be available, or may have varying parameters or requirements so please be aware of this fact when consulting the

import documentation. To get started, begin by creating a new PHP document in your favorite text editor or IDE. You must save this file in a location accessible to the /inc/ directory of your Blesta installation. I recommend creating a directory called “import” in the root directory of your Blesta installation and placing this file in there. Following the above you should now have a PHP document in the path /your_blesta_install/import/. You can then copy/paste the code below to get started:

<?php
require("../inc/config.php");
require("../inc/import.class.php");
 
final class myImport extends AbstractImport {
   public static $db;
 
   public function __construct($sqlHost, $sqlUser, $sqlPass, $sqlDB) {
      myImport::$db = new mysql($sqlHost, $sqlUser, $sqlPass, $sqlDB);
      myImport::$db->linkid = mysql_connect($sqlHost, $sqlUser, $sqlPass, true);
      myImport::$db->select();
 
   }
}
$import = new myImport("localhost", "yourUser", "yourPass", "YourOldDatabase");
 
// We’ll fill this part in later
?>

The above code snippet assumes you are importing from a MySQL database. If you are importing from another type of database or file you should replace the contents of the constructor with the appropriate code to access that data. Also note the relative path of the two included files. Be sure this is the correct path to both config.php and import.class.php of your Blesta installation. Both of these files are required in order to use the import library. Next you’ll want to write the appropriate functions to extract the data out of your current database or file so it can be sent over to the appropriate import library function. Let’s look at an example:

<?php
public static function importInvoices() {
   // Grab all invoices and their line items
   $sql = "SELECT invoices.invoice_id, invoices.client_id, invoices.invoice_date_entered, ";
   $sql .= "invoices.invoice_date_due, invoices.invoice_date_paid, invoices.invoice_status, ";
   $sql .= "invoices.invoice_amount_paid, invoice_line_items.line_item_id, invoice_line_items.package_id, ";
   $sql .= "invoice_line_items.line_item_description, invoice_line_items.line_item_total_amount FROM invoices ";
   $sql .= "LEFT JOIN invoice_line_items ON invoices.invoice_id=invoice_line_items.invoice_id ";
   $sql .= "ORDER BY invoices.invoice_id ASC";
   myImport::$db->query($sql);
 
   //Build an array of all invoice data and their line items
   $invoice = array();
   $lineitems = array();
   $lastiid = 0;
   for ($i=0, $j=0; $j <= myImport::$db->numRows(); $j++) {
      $data = myImport::$db->fetchAssoc();
      // Is this a new invoice?
      if ($lastiid != $data['invoice_id']) {
         // Add the last invoice
         if (count($lineitems) > 0) {
            $invoice['lineitems'] = $lineitems;
 
            // Add the Invoice
            myImport::importInvoice($invoice);
 
            $lineitems = array();
            $i=0;
         }
 
         $invoice['id'] = $data['invoice_id'];
         $invoice['uid'] = $data['client_id'] + UIDSTART;
         $invoice['dateb'] = date('Y-m-d', $data['invoice_date_entered']);
         $invoice['dated'] = date('Y-m-d', $data['invoice_date_due']);
         // only mark it as paid if the status is "Paid"
         $invoice['dater'] = ($data['invoice_status'] == "1" ? date('Y-m-d', $data['invoice_date_paid']) : "0000-00-00");
         $invoice['previous'] = "0.00";
         $invoice['applied'] = $data['invoice_amount_paid'];
         $invoice['type'] = "email";
         $invoice['status'] = "sent";
         $invoice['notes'] = "ModernBill Import";
      }
 
      // Add this as a line item
      $lineitems[$i]['id'] = $data['line_item_id'];
      $lineitems[$i]['iid'] = $data['invoice_id'];
      $lineitems[$i]['sid'] = $data['package_id'];
      $lineitems[$i]['name'] = $data['line_item_description'];
      $lineitems[$i]['price'] = $data['line_item_total_amount'];
      $i++;
 
      $lastiid = $data['invoice_id'];
   }
}
?>

The above example was taken from the ModernBill 5.2.0 import script, and demonstrates how data is formated then sent to the appropriate import library function. To call this function we replace the line:

// We’ll fill this part in later

With:

$import->importInvoices();

Take special notice of the line:

myImport::importInvoice($invoice);

This is the syntax with which we call the import library functions. The above line calls the importInvoice library function, which is used to import an invoice and its line items into Blesta. Importing into Blesta is as easy as creating a basic PHP 5 class document that extends the AbstractImport class found in /inc/import.class.php of your Blesta installation and invoking the appropriate library function. That’s all there is to it! For a complete listing of all available import functions and their parameters/requirements please see the import documentation.