Integrate External Libraries in OpenCart Using Composer

Integrate External Libraries in OpenCart Using Composer

Almost every framework nowadays has built-in support of Composer, an awesome dependency management tool in PHP, and OpenCart is no exception. In this tutorial, you'll learn how to use Composer to integrate external libraries in OpenCart.

The Role of Composer in OpenCart

Since the introduction of OpenCart 2.2, the Composer-based workflow is supported. So go ahead and grab the latest version of OpenCart; as of writing this, it's 2.3.0.2. Make sure that you install and configure the latest version that you've downloaded as that will be useful later in the article.

Explore the directory structure and you'll notice certain differences compared to earlier versions of OpenCart. In the context of this article, the interesting candidates are the composer.json file and the vendor directory. 

Let's quickly go through the composer.json file.

{
    "name": "opencart/opencart",
    "type": "project",
    "description": "OpenCart",
    "keywords": ["opencart", "ecommerce", "framework", "opensource"],
    "homepage": "http://www.opencart.com",
    "license": "GPL-3.0+",
    "require": {
        "cardinity/cardinity-sdk-php": "^1.0",
        "braintree/braintree_php" : "3.2.0",
        "leafo/scssphp": "0.0.12",
        "divido/divido-php": ">=1.1.1",
        "klarna/kco_rest": "^2.2",
        "php": ">=5.4.0"
    }
}

Although a discussion of Composer syntax is out of the scope of this article, let's quickly go through what it says in layman terms.

First, the OpenCart project itself is now available as a library, so you could install it using Composer itself without manually downloading it from the site. Further, it also requires other third-party libraries to work properly, like divido, leafo, etc. Of course, you don't need to worry about it as that will be handled automatically when you run related Composer commands.

When you install a new library, the related entry will be added to the composer.json file. The related library files are placed under the vendor directory at the same level. Just explore that directory and you should see the libraries are installed already!

The vendor directory also contains autoload.php, generated by Composer itself, which makes sure that the libraries are loaded automatically in OpenCart, so you could use it straight away. Of course, OpenCart includes autoload.php while bootstrapping the project.

So that's a quick introduction of how Composer works with OpenCart. For demonstration purposes, we'll install the popular PHPMailer library using Composer.

Install PHPMailer Using Composer

The PHPMailer is a popular PHP library that's used to send emails. We'll install it in OpenCart using Composer. So go to your terminal and change the directory so that you are at the same level where the vendor directory and composer.json file reside.

Now, run the command composer require phpmailer/phpmailer and press enter! Assuming that everything goes fine, it should look like the following.

$composer require phpmailer/phpmailer
Using version ^5.2 for phpmailer/phpmailer
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing phpmailer/phpmailer (v5.2.16)
    Downloading: 100%         


phpmailer/phpmailer suggests installing league/oauth2-google (Needed for Google XOAUTH2 authentication)
Writing lock file
Generating autoload files

So that's it! PHPMailer is downloaded and installed successfully, and that's the beauty of Composer! Verify that by looking into the vendor directory, and you'll find it installed in the phpmailer/phpmailer directory.

Also, let's open composer.json to see what it looks like.

{
    "name": "opencart/opencart",
    "type": "project",
    "description": "OpenCart",
    "keywords": ["opencart", "ecommerce", "framework", "opensource"],
    "homepage": "http://www.opencart.com",
    "license": "GPL-3.0+",
    "require": {
        "cardinity/cardinity-sdk-php": "^1.0",
        "braintree/braintree_php" : "3.2.0",
        "leafo/scssphp": "0.0.12",
        "divido/divido-php": ">=1.1.1",
        "klarna/kco_rest": "^2.2",
        "php": ">=5.4.0",
        "phpmailer/phpmailer": "^5.2"
    }
}

As you can see, the entry "phpmailer/phpmailer": "^5.2" is added into the require section. So it means that your project requires PHPMailer to work properly.

Let's assume that you're working with other developers and need to share your work regularly. In that case, you just need to share your composer.json file with them and the rest will be handled by Composer itself! They just need to run the composer update command, and that should take care of installing the required dependencies in their copy!

Now, we've installed PHPMailer using Composer, but how to use it? Don't worry, I won't leave you that soon—that's exactly the recipe of our next section!

How to Use the PHPMailer Library?

You've already done yourself a favor by using Composer to install the PHPMailer library, and you'll witness it in this section as we explore how straightforward it is to use in the code.

For example purposes, we'll build a pretty simple custom controller file that you could call to send an email.

Open your favorite text editor and create example/email.php under the catalog/controller directory with the following contents.

<?php
class ControllerExampleEmail extends Controller {
    public function index() {
    // just instantiate the mailer object, no need to include anything to use it.
    $objPhpMailer = new PHPMailer();


    $objPhpMailer->From = "sender@example.com";
    $objPhpMailer->FromName = "Sajal Soni";
    $objPhpMailer->AddAddress("receiver@example.com");


    $objPhpMailer->WordWrap = 50;
    $objPhpMailer->IsHTML(true);


    $objPhpMailer->Subject = "Subject";
    $objPhpMailer->Body    = "<h2>HTML Body</h2>";
    $objPhpMailer->AltBody = "Plain Body";


    if(!$objPhpMailer->Send())
    {
       echo "Message could not be sent. <p>";
       echo "Mailer Error: " . $objPhpMailer->ErrorInfo;
       exit;
    }


    echo "Message has been sent";
    exit;
    }
}

You could test it by accessing your site via http://your-opencart-site-url/index.php?route=example/email.

In the index method, you can see that we've instantiated the PHPMailer object without any include statements that would have included the required PHPMailer classes had we not used a Composer-based workflow. You've got it right, it's auto-loaded by OpenCart itself. Recall that autoload.php in the vendor directory does all the magic!

Following that is some pretty standard stuff required by PHPMailer to send an email. Of course, I've tried to keep the example as simple as possible since the discussion of PHPMailer requires a separate article!

So, that was a quick and simple introduction of how you could use Composer with OpenCart to integrate external libraries.

Conclusion

In this article, we've just scratched the surface of a Composer-based workflow in OpenCart to use third-party libraries in your project. Not to mention that Composer is the future of dependency management tools in PHP. So it's always good to get your hands dirty with that as it's becoming the standard in all popular frameworks.

Queries and suggestions are always appreciated!