EasyApache 4 & CLI based PHP utilities

With the release of EasyApache 4 in WHM 58 there are various changes to how PHP is managed. The most obvious being that EasyApache 4 brings support for installing multiple PHP versions alongside each other. However with multiple versions of PHP being installed on the server it’s easy to lose track of your command-line based PHP utilities and their PHP requirements.

Certain PHP packages like Composer, Drush, and WP-cli prefer to be run with the latest version of PHP. Unfortunately, having multiple PHP versions can mean not knowing which PHP will execute the utility when you call it directly. This article will detail a few methods to specify which PHP version should be used in instances like this.

Pre-flight Check:

  • These instructions are intended specifically for cPanel-based servers running WHM prior to version 58.
  • Command line access via SSH may be necessary to follow the examples.
  • The server will need to have EasyApache 4 active.
  • PHP 7 will be necessary to follow the provided examples.

Option #1: Directly Call the PHP Binary

The most basic option to workaround these issues is to directly call the PHP binary you need before executing the script. While this can be effective and will work as expected most of the time, certain utilities will not work when using this method.

You may want to attempt this method first and move on to Option #2 if this does not work as expected; generally though, this should work for executing basic PHP code.

/opt/cpanel/ea-php70/root/usr/bin/php someScript.php

The above command will specifically call the 7.0 version of PHP and will execute the someScript.php file within that version of PHP. If they are also installed on the server, the alternative PHP versions can be found at:

  • /opt/cpanel/ea-php55/root/usr/bin/php
  • /opt/cpanel/ea-php56/root/usr/bin/php
  • /opt/cpanel/ea-php70/root/usr/bin/php

Option #2: Use scl to Specify PHP Versions

As mentioned, certain PHP utilities are not provided as basic PHP files and are stored in the PHAR format. These utilities will not execute properly with the above method for specifying the PHP version. For these types of utilities you will need to specify the PHP version using a command called `scl`.

This command is a utility that allows running software in an environment packaged as a ‘Software Collection’. To be brief a ‘Software Collection’ is a way of defining an alternate location to a certain software. Fortunately, WHM provides predefined collections for the various versions of PHP supported by EasyApache 4.

The syntax of this command is as follows:

scl enable {SoftwareCollection} '{CommandToRun}'

Where you replace {SoftwareCollection} with the needed collection [ea-php55, ea-php56, or ea-php70], and you replace {CommandToRun} with the command, utility, or script you need to run.

A good way to highlight this is to review the difference in the following outputs:

root@noms [~]# php -v

PHP 5.6.25 (cli) (built: Aug 25 2016 17:00:38)
Copyright (c) 1997-2016 The PHP Group
Zend Engine v2.6.0, Copyright (c) 1998-2016 Zend Technologies
with the ionCube PHP Loader v4.7.5, Copyright (c) 2002-2014, by ionCube Ltd., and
with Zend Guard Loader v3.3, Copyright (c) 1998-2014, by Zend Technologies
with Zend OPcache v7.0.4-dev, Copyright (c) 1999-2015, by Zend Technologies

root@noms [~]# scl enable ea-php70 'php -v'

PHP 7.0.10 (cli) (built: Aug 25 2016 18:04:55) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies
with Zend OPcache v7.0.10, Copyright (c) 1999-2016, by Zend Technologies

As you can see when calling PHP by itself we get the default version, but when using scl we explicitly called the PHP 7.0 collection and get results to match.

Example #1: Executing a utility [Composer]:

root@noms [~]# scl enable ea-php70 'composer --version'

Composer version 1.2.0 2016-07-19 01:28:52

Example #2: Running a PHP script:

root@noms [~]# scl enable ea-php70 './someScript.php'

With these key tips and tricks you should now be equipped with the necessary tools to run CLI utilities on a server using EasyApache 4. If you have any questions or are not comfortable making these changes yourself, please feel free to contact Heroic Support®.

WHMCS with Private Cloud Servers and Advanced Product Setup

Working with WHMCS & the Liquid Web Reseller Plugin

With the steps of the previous articles complete, we now have the WHMCS Liquid Web plugin setup and enabled. If you followed the previous directions, you’ve successfully created the first product based on VPS offerings. We will now cover some more advanced product creation options.

Step #1: Create a Liquid Web Private Cloud Product

To create your first Private Cloud product you will first need to open the Product Setup Wizard page within the WHMCS interface:

  1. Click on the ‘Addons’ tab at the top of the page.
  2. Select the ‘Liquid Web Storm Servers Billing’ option.
  3. From the sidebar on the left, click ‘Product Setup Wizard’.
  4. Once loaded, select only ‘Liquid Web Private Cloud’ then click ‘Next’.
  5. At this point the process will vary depending on if you already have a Private Cloud server connected to your Liquid Web account.
  6. If you already have a Private Cloud server continue to F, otherwise you will need to create a new Private Cloud server:
    Add Private Cloud

    1. You will see a ‘Add New Server’ dialog box come up, once the page loads.
    2. Select the Zone you’d like the server to be in.
    3. Review the available Private Cloud servers and select the one you’d like.
    4. Provide a hostname for the server in the ‘Host Name’ text input.
    5. Click ‘Add Server’.
  7. You may now create the Private Cloud based product.
  8. Create Private Cloud Product

    You may want to adjust most, if not all, of the fields on this configuration page to customize the product based on your current needs.
  9. After adjusting the options as needed, click the ‘Save & Continue’ button.

Step #2: Advanced Product Configuration Settings

While the initial settings in the Product Setup Wizard are generally enough to accommodate most product creations, there are more advanced settings which might be useful when creating more complex product configurations.

There will be small differences between the advanced settings found within the Private Cloud settings and the VPS based settings, though generally they both have most of the same options.

To access the advanced product configuration settings you can either: click ‘Save & go to Advanced mode’ button when creating a new product, or by opening a current product and selecting the ‘Module Settings’ tab.

Vps Advanced
Private Cloud Advanced

Above you see the VPS advanced configuration page (left) and the Private Cloud advanced configuration page (right).

As seen above the advanced configuration pages are fairly similar in nature, this should make using these pretty simple once you’ve worked with either one. To further simplify understanding the options available, you will only find the following options on the VPS page:

  • Default Configurable Options
    • Used to generate a handful of customer customizable server options, such as: VPS type, Backup settings, IP address quantity, and bandwidth quotas
  • Zone
    • Determines the ‘data center zone’ that the server can be created in
  • Config
    • Defines the specific server that will be used to create the product; e.g. 1G SSD vs 2G non-SSD

The following options are only on the Private Cloud page:

  • Configurable Options
    • Similar to ‘Default Configurable Options’ above, this generates a number of Private Cloud specific options that can be exposed to customers upon checkout.
  • Custom Field
    • Similar to the above point, this generates custom fields to collect data on customer checkout.
  • Parent Server
    • Defines the parent server that this product will use when creating new instances.
  • Available Parents
    • A list of available Private Cloud servers that are usable as a Parent server.
  • Select Parent Automatically
    • When enabled the product should automatically select the parent server based on available resources.

On both Private Cloud & VPS pages you will find:

  • Username & Password
    • These are the credentials used when connected to the Storm API – should be prepopulated with the credentials that were initially created.
  • Template
    • This is the image used to bootstrap the server — this determines the Servers OS, Management Panel type, and Server Management Level.
  • Image
    • Allows the new server to be bootstrapped with a Storm Server Image if the account contains some images.
  • Backup Plan & Backup Quota
    • These options determine if backups are enabled, what type of backup plan is used, and the quota applied to the backups.
  • IPs Number & Maximum Number of IPs
    • Defines the default number of IP addresses to start the server with and the maximum number of IPs a single server can allocate.
  • Bandwidth Quota
    • Allows customization of the Bandwidth quota applied to the server.
  • Monitoring
    • Enables customers to control Monitoring services on the server.
  • Firewall
    • Enables customers to control Firewall services on the server.
  • IPs Management
    • Enables customers to control IP address allocations on the server.

With a multitude of product configuration options available, you can choose exactly how you offer products and services to your customers. By fully utilizing these more advanced settings you can allow customers to select from a very specifically tuned array of products, or to adjust product details as they wish during the checkout process.

Step #3: Working with Configurable Options

To expand further upon the ability for your customers to tweak and adjust services they are ordering you can take advantage of the ‘Configurable Options Groups’ within WHMCS. These ‘Configurable Options’ are additional options that can be presented to a user upon ordering a service.

By utilizing these configurable options with the advanced features discussed above you are able to provide customers a build your own server experience, a variety of products to fit specific needs, or a mixture of both.

To begin working with ‘Configurable Options’ you will need to open WHMCS and go to the ‘Setup -> Products/Services -> Configurable Options’ page. Once there you can see a list of the groups similar to the following screenshot.

WHMCS account setup, the Product Setup Wizard and Storm Servers Billing

Working with WHMCS & the Liquid Web Reseller Plugin
I. What is WHMCS and installing the Liquid Web plugin
II. WHMCS account setup, the Product Setup Wizard and Storm Servers Billing
III. WHMCS with Private Cloud Servers and Advanced Product Setup

In the previous article we covered the basics of WHMCS, the benefits of using our plugin, and how to enable the plugin and widgets we provide in our plugin package. This article will cover the configuration of the Storm API access and your first product.

With the rebuilt Liquid Web reseller plugin for WHMCS, the initial account and API connection setup has been integrated into the new Product Setup Wizard. So, to configure the plugin to access your Liquid Web account via Storm API, we simply will start the process of creating your first product.

Step #1: Connect the plugin to Storm API

To make the initial connection to the Storm API you will first need to open the Product Setup Wizard page:

  1. Click on the ‘Addons’ tab at the top of the page.
  2. Select the ‘Liquid Web Storm Servers Billing’ option.
  3. From the sidebar on the left, click ‘Product Setup Wizard’.
  4. Once loaded, we will make our connection by starting to set up our first product:
    1. Adjust the checkboxes to your liking, for this example we will only select: ‘Liquid Web SSD VPS’
    2. Click Next.
    3. If this is the first product setup you will be redirected to the Account Authentication page.
  5. On the ‘Liquid Web account authentication’ page you will be prompted for your Liquid Web API authentication; you may either enter Liquid Web API credentials or your Liquid Web Manage credentials, and the wizard will create a new API user.
    1. For using a current API user:
    2. Api User login

      1. Click the ‘I have Liquid Web API credentials’ heading.
      2. Enter your Liquid Web Storm API user credentials.
      3. Click ‘Continue’.
    3. For creating a new API user:
    4. Manage Login

      1. Click the ‘Create a NEW Liquid Web API username and password for me’ heading.
      2. Enter your Liquid Web Manage credentials.
      3. Click ‘Create new API account’.
      4. You will now see the new Storm API user that has been created. Write these credentials down for safe keeping.
      5. Click ‘Continue’.

With that completed you have now authorized the plugin to access your Liquid Web account via the Storm APIs. You can now begin to create and setup products to offer your new clients.

Step #2: Create your first VPS product

Having completed all the prior steps we are now ready to create the first product via the Product Setup Wizard. In this tutorial our example product will be based on the Liquid Web SSD VPS, so we are now on the related configuration page, as seen below.

Product Wizard - Add VPS Product

You may want to adjust most, if not all, of the fields on this configuration page to customize the product based on your current needs.

Product Details

  • You need to provide the product name, description, and select a product group.

Module Settings

  • Default values from the database are loaded when you open this page.
  • You need to select the OS template and VPS type when changing the Zone.

Pricing (Monthly)

  • You can set the subscription pricing (monthly) either in percentage or fixed values.
  • When using percentage-based pricing, the module will automatically calculate the pricing of the selected configuration and update the pricing table in WHMCS.

Once you have adjusted the options on this page to your liking you can then proceed with creating the product by clicking ‘Save & Continue’ found on the bottom right of the page.

If you would like to you can verify the product was created by pulling up the ‘Products/Services’ page of WHMCS; found under: Setup > Products/Services > Products/Services, you should find your new product listed there. With this step you will have completed the creation of your first product!

Step #3: Storm Server Billing configuration

Now that we’ve created our first product clients can immediately begin putting in orders via the WHMCS client area. They will be charged based on the price values you configured when working through the Product Setup Wizard.

However with certain products or services you may require that clients pay for various resource usages, such as: bandwidth, disk usage, overall disk space, backups, memory, and/or CPU usage.

In order to control these aspects of a product you can use the ‘Liquid Web Storm Servers Billing’ page:

  1. Click on the ‘Addons’ tab at the top of the page.
  2. Select the ‘Liquid Web Storm Servers Billing’ option.
  3. Once loaded you will see a page similar to:
  4. Enable Billing Page

    Note: the paths on your page will be updated to reflect the location of the files needing to be run on cron.
  5. Configure and Enable the cron jobs:
    1. Using your preferred method [cPanel, or Command line], enable each cron job found on this page.
  6. You will see a dropdown under ‘Enable Billing’, open the dropdown and select your new product from the list.
  7. Once the page loads, you will see various resource usage-related categories where you can set extra charges for various metrics. [Bandwidth, Disk, Memory, etc]
  8. Billing Limits page

  9. Adjust these values to your liking and then click ‘Save Changes’ near the bottom of the page

With these new options and limits in place any servers of this type will now be billed based on resource limits defined on the Billing configuration page.

At this point the plugin should be fully configured with WHMCS and you can now continue to use the ‘Product Setup Wizard’ to create even more products and services to offer your clients.

What is WHMCS and installing the Liquid Web plugin

Working with WHMCS & the Liquid Web Reseller Plugin

What is WHMCS?

The WHMCS software suite provides the necessary tools to automate billing and provisioning of web hosting services on WHM based servers. It provides an easy-to-access management interface allowing resellers full control over the products and services you choose to offer. WHMCS is perfect for the reseller looking to streamline or expand their cPanel-based business.

WHMCS provides automated systems for managing invoices, billing, customer management, and service provisioning – all allowing you to focus more on your clients. Enhanced by the addition of our rebuilt plugin for WHMCS, the process truly is fully automated.

New products can now be created in a few clicks with the new ‘Product Setup Wizard’; once an order has been placed and paid for, the plugin will access the LiquidWeb Manage APIs to spin up and provision the necessary services for you.

Step #1: Installing the LiquidWeb WHMCS plugin

Installation of our WHMCS plugin is a rather simple process and can be done by a few methods: using graphical-based tools and programs, or the command line interface. This section will detail the steps required to install and setup the plugin.

Our WHMCS plugin can now be found on a publicly available GitHub-based repository. Or a direct download link to the installation Zip: Liquid Web for WHMCS.

Download the plugin zip file in your root WHMCS directory. The directory might not be the same for everyone, but an example of how to do this would be:

Via SSH (command line) on the server…
cd /home/$WHMCSUSER/public_html/WHMCS/
wget https://github.com/liquidweb/LiquidWeb-WHMCS-Plugin/archive/master.zip
unzip master.zip
cd LiquidWeb-WHMCS-Plugin-master/
rsync -avH includes/ ../includes/
rsync -avH modules/ ../modules/

You can also use FTP to upload the file, or use the cPanel File Manager if you wish. Regardless of the upload method you will need to unzip the files and put them in place using the commands from above.

Step #2: Activate the LiquidWeb WHMCS plugin

  1. Click on the “Setup” tab near the top of the page
  2. Select the “Addon Modules” option
  3. Open the Addon Page

  4. Once loaded, find ‘Liquid Web Storm Servers Billing’ and click “Activate”
  5. To give this module the correct permissions, click on the “Configure” (i) button and then select “Full Administrator” (ii) in the “Access Control” section and then click ”Save Changes” (iii)
  6. Enable Main Addon

  7. While here you may want to activate the Widget plugin
    1. Find ‘Storm On Demand Widget For WHMCS’ and click “Activate”
    2. To configure this module’s settings, click on the “Configure” button (a), adjust the ‘Low Inventory Threshold’ and ‘Cron Mail’ settings to your liking (b) and then click “Save Changes” (c).
    3. Enable Widget Addon

    4. To give the Widget proper permissions, click “Setup > Staff Management > Administrator Roles”. On the Administrator Roles page you will edit the Role which you’d authorize for the widget.
    5. Open User Role permissions

    6. On the Role editing page find the “Widgets” section, and within that find and enable “Liquid Web Storm Servers”, click “Save Changes”

At this point the Liquid Web WHMCS plugin should now be active and you should be able to start setting up packages and products within WHMCS.

If you’d like to report issues, or provide feedback of any kind, regarding this plugin you can feel free to do so by utilizing the project’s GitHub Issues page.

How to Replace PHP GeoIP with MaxMindDB

Depending on the site or application, looking up geographic information related to an IP address can be a pretty common action. When doing IP geolocation in PHP usually the PHP GeoIP extension would be used to facilitate the retrieval of this information. Unfortunately, this particular plugin is no longer actively supported and has not been updated in a number of years.

With the go-to PHP extension of IP geolocation effectively being deprecated, new projects should begin to use the replacement options that are now provided by MaxMind. However, unlike the original GeoIP, which was shipped as a native PHP extension, the new solutions are provided as PHP-based library packages.

Pre-Flight Check

  • Basic familiarity with PHP coding is necessary to utilize Composer packages.
  • Command line access via SSH may be necessary to follow this tutorial.
  • Composer, Curl, funzip must be available on the server.

Step #1: What are my options now?

As mentioned previously, the new options are no longer provided as native PHP extensions, but rather they come as Composer-based PHP packages. The new options provided by MaxMind are either: GeoIP2-php or DB-Reader-php.

Both of the options provide the ability of IP geolocation with subtle differences; in a sense the GeoIP2-php package is an addition built on top of the DB-Reader-php package, it offers all the same features as DB-Reader-php with the addition of API access.

Additionally, it is important to note that only the DB-Reader option is provided without any additional costs. With the new options MaxMind now charges a subscription fee in order to access their APIs.

Generally for most use-cases the necessary features will be provided by the DB-Reader-php package, as such this article will focus on this option.

Step #2: Get started with MaxMind DB-Reader!

As mentioned in the pre-flight check, Composer will be required in order to follow these steps. If you do not have Composer setup on the server please feel free to review our Composer series here: ‘What is Composer?’.

To acquire the necessary DB-Reader package you will want to start by changing directory so that you are in the root folder of your domain (for this example we will just assume this is `public_html`), then you will run the following command:

[public_html] $ composer require maxmind-db/reader:~1.0

Running this command will download the package files into the current folder, as described in our Composer series. This will create a vendor folder if this is the first time using Composer in this site/project.

Next you will require the actual MaxMind database files which contain the geolocation data. To get these files you will execute the following commands:

[public_html] $ funzip <(curl -L http://geolite.maxmind.com/download/geoip/database/GeoLite2-Country.mmdb.gz) > ./GeoLite2-Country.mmdb
[public_html] $ funzip <(curl -L http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.mmdb.gz) > ./GeoLite2-City.mmdb

With the above commands executed you should now have the necessary components to do Geolocation using the DB-Reader plugin. All that’s left is to implement it in your code.

Step #3: Looking up your first IP

In order to ensure the geolocation features are working properly you may want to do a quick test. First we’ll confirm you have all the right pieces by running the following command:

$ ls -lah

You should see a file structure similar to this:

-rw-rw-r-- 1 someuser someuser 63 Aug 11 17:03 composer.json
-rw-rw-r-- 1 someuser someuser 2.4K Aug 11 17:03 composer.lock
-rw-rw-r-- 1 someuser someuser 73M Aug 11 17:04 GeoLite2-City.mmdb
-rw-rw-r-- 1 someuser someuser 19M Aug 11 17:04 GeoLite2-Country.mmdb
drwxrwxr-x 4 someuser someuser 4.0K Aug 11 17:03 vendor/

Now you are ready to do a quick test, you can do so by creating an index.php file with the following content:

<?php
require_once 'vendor/autoload.php';

use MaxMind\Db\Reader;
$ipAddress = '8.8.8.8';
$databaseFile = './GeoLite2-City.mmdb';

$reader = new Reader($databaseFile);

print_r($reader->get($ipAddress));

$reader->close();

This index file will simply do a quick test to ensure that the database file is being loaded, an IP can be checked, and the results are being provided. The test will be looking up the geographic information related to Google’s DNS server at 8.8.8.8.

Geo-location results for Google's 8.8.8.8 DNS server via MaxMind
Geo-location results for Google’s 8.8.8.8 DNS server via MaxMind

Having followed the directions correctly you should see output similar to the image above when loading the test index page.

Working with Composer & Examples

Tutorial: How to use Composer
I. Composer 101
II. Installing Composer on cPanel servers
III. Working with Composer & Examples

In the previous articles we worked through what composer is, who uses it, and how to install it. Here we will cover some basic use case examples of how to acquire packages using the composer tool we previously setup.

The example documented in this article can be done either locally, or on your Liquid Web Fully Managed cPanel server, in either case these directions should be run as the user owning the website files. On a cPanel server this would mean you’re running these via SSH logged in as the cPanel user and you would be starting from within public_html.

Example #1: Getting GuzzleHTTP using Composer

One of the most popular PHP HTTP clients, Guzzle is a library that can make sending HTTP requests simple and easy. As a widely used and well-documented library, Guzzle is an easy package for any developer or designer to take advantage of.

To try out Guzzle run the following commands:

$ mkdir guzzleTest
$ cd ./guzzleTest/
$ composer require guzzlehttp/guzzle

Then create an index.php file in the same folder with the following content:

<?php
require_once 'vendor/autoload.php';
$client = new GuzzleHttp\Client();

// Make a request
$res = $client->request('GET', 'http://www.timeapi.org/utc/now.json');

// Output the status code of the response
echo 'Page response code: '.$res->getStatusCode();
echo "<hr/>";
// "200"

// Output headers of the response
echo 'Response Content-Type header: ';
print_r( $res->getHeader('content-type') );
echo "<hr/>";
// 'application/json; charset=utf8'

// Output the actual content (body) of the response
echo 'Response Body content: ';
echo $res->getBody();
echo "<hr/>";
?>
In the above PHP code, lines starting with ‘//’ are considered comments and are just there to help detail each step of script.

Opening the new index.php file in your browser should yield a page that shows: the HTTP response code, the ‘Content-Type’ header of the response provided, and the actual content of the response.

Example #2: Getting a framework

While composer is mainly used to get specific libraries and packages needed for a site to run, it’s also possible for a whole framework or CMS to be provided using composer. Laravel is one of many popular PHP frameworks that use composer to distribute their core files. An example of using composer to get Laravel can be done with the following commands:

$ composer create-project --prefer-dist laravel/laravel ./laraTest

Once this command has been executed composer will do a number of things for you; it will create the “laraTest” folder, initialize the composer.json file, get any necessary dependencies and then setup the Laravel-specific files.

To verify this example you will need some familiarity with the Laravel framework, however you can verify that composer did its job by checking the file structure. To check the file structure run the following command:

$ ls -lah

You should see a structure similar to:

total 200K
drwxr-xr-x 11 user users 4.0K Aug 8 13:17 .
drwxr-xr-x 10 user nginx 4.0K Aug 8 13:16 ..
drwxr-xr-x 10 user users 4.0K Apr 27 09:01 app
-rwxr-xr-x 1 user users 1.7K Apr 27 09:01 artisan
drwxr-xr-x 3 user users 4.0K Apr 27 09:01 bootstrap
-rw-r–r– 1 user users 1.3K Apr 27 09:01 composer.json
-rw-r–r– 1 user users 111K Aug 8 13:17 composer.lock
drwxr-xr-x 2 user users 4.0K Apr 27 09:01 config
drwxr-xr-x 5 user users 4.0K Apr 27 09:01 database
-rw-r–r– 1 user users 458 Aug 8 13:17 .env
-rw-r–r– 1 user users 423 Apr 27 09:01 .env.example
-rw-r–r– 1 user users 61 Apr 27 09:01 .gitattributes
-rw-r–r– 1 user users 73 Apr 27 09:01 .gitignore
-rw-r–r– 1 user users 503 Apr 27 09:01 gulpfile.js
-rw-r–r– 1 user users 212 Apr 27 09:01 package.json
-rw-r–r– 1 user users 1.1K Apr 27 09:01 phpunit.xml
drwxr-xr-x 2 user users 4.0K Apr 27 09:01 public
-rw-r–r– 1 user users 1.9K Apr 27 09:01 readme.md
drwxr-xr-x 5 user users 4.0K Apr 27 09:01 resources
-rw-r–r– 1 user users 567 Apr 27 09:01 server.php
drwxr-xr-x 5 user users 4.0K Apr 27 09:01 storage
drwxr-xr-x 2 user users 4.0K Apr 27 09:01 tests
drwxr-xr-x 29 user users 4.0K Aug 8 13:17 vendor

Installing Composer on cPanel servers

Tutorial: How to use Composer
I. Composer 101
II. Installing Composer on cPanel servers
III. Working with Composer & Examples

With a tool like Composer it is generally best to have the ability to run it as any user on the server and from any directory. This is generally referred to as being ‘globally installed’ as any user can access the tool from any location. In this guide we will detail how to install Composer globally on a cPanel based server.

Pre-Flight Check

  • These instructions are intended specifically for installing Composer on a cPanel based server running WHM prior to version 58.
  • We’ll be logging in as root to a Liquid Web Fully Managed cPanel server.
As of WHM version 58 cPanel is now including a version of Composer by default, this can be accessed by simply calling composer from command line.
For more details see: What’s New in WHM 58 & What to Look For

Step #1: Get the installer

Acquire the Composer installer script with the following commands:

$ EXPECTED_SIGNATURE=$(wget https://composer.github.io/installer.sig -O - -q)
$ php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
$ php -r "if (hash_file('SHA384', 'composer-setup.php') === '$EXPECTED_SIGNATURE') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

The above commands will: get the installer’s signature, get the installer file, verify the download by checking the signature and finally confirm if the installer is valid, or corrupt. You should see output similar to:

Installer verified

Step #2: Run the installer

To run the installer in a manner that will install composer globally run the following command:
php ./composer-setup.php --install-dir=/usr/local/bin --filename=composer

With this command run as root composer should now be globally installed on the server.

Step #3: Verify the install

In order to verify the composer installation was successfully you will want to do the following to test. First, as root, run the following command:
# composer -V

You should see something similar to:

Composer version 1.2.0 2016-07-19 01:28:52

If that checks out, you will then want to verify Composer works for the users as well. To confirm composer is working for the cPanel accounts SSH into your server as a cPanel user and do the same:

$ composer -V

You should see something similar to:

Composer version 1.2.0 2016-07-19 01:28:52

Composer 101

Tutorial: How to use Composer

Composer is a dependency manager for PHP, written in PHP. Specifically, it’s used to simplify the process of using PHP libraries in your projects. The use can range from getting a framework, including a library class, or open source projects; generally these packages are downloaded by Composer and then implemented by a developer in a website’s code.

Examples being: Silex MicroFramework, the infamous PHPMailer class, Laravel Framework, and many more – all of which can be found on Composer’s main repository Packagist.

To find a more documented list of classes, libraries, or frameworks that are available you can review the Packagist site.

So How Do I Use This Tool?

To use Composer you will want to be logged in via SSH, or TTY, and you will run the following command:

$ composer require {somepackage}

This will issue a command for Composer that essentially states you are requiring the provided package name in the current folder. What this does is requests the package given; if found, it then creates the following:

  • composer.json
  • /vendor
  • composer.lock

Ok, so that downloaded the necessary PHP files to use the library, or package, you are requesting. It created a “/vendor” folder where it downloaded all the ‘library’ files. Great, you’ve got the necessary files, but now what?

How Do I Use the Composer-provided Libraries?

To use Composer-provided libraries you may need to understand Composer a little bit better first; specifically you’ll need to understand how Composer’s autoloader works. Think of this as your ‘crash course’ to the autoloader.

To make more sense of this concept let’s go back to our ‘What is Composer’ section; as we know Composer is a “Dependency Manager for PHP”. This means it’s getting you a library, or some code, needed for your site or project. It will also grab any libraries, or other requirements, needed by that library to function – hence the name “dependency management tool”, it’s doing that part in the background for you. In order to make use of this tool, you need to make sure you’re properly including everything that is required.

That’s where Composer’s Autoloader comes in, the autoloader is a script which includes and loads any needed dependencies. Long story short, Composer will create for you a file called: “autoload.php” that is located in the “/vendor” folder it creates. This file is all you need to use/re-use the libraries, classes, or etc, that you are getting from Composer.

Using the Autoloader

In order to use a Composer-provided library you will simply need to add the following to your script:
require 'vendor/autoload.php';

Keep in mind that the part within single quotes should be the relative path to this file; this may need adjusting depending on how you are doing things.

Final Tips When Using Composer

Ultimately, including the `require autoloader.php` line allows you to utilize the packages, classes, libraries, etc, that you are asking composer to get for you. These dependencies are downloaded locally to where the ‘require’ command was run.

When working on cPanel servers you should only run and use composer as the cPanel user requiring those dependencies. Doing this will ensure the files are downloaded in a manner that keeps proper user ownership and permissions. However, if you accidentally run Composer as the root user you will simply need to adjust the file permissions and ownership accordingly.

While the usage of Composer is mainly done by developers, if you are experiencing any issues with file ownership, permissions, or if you have any questions feel free to contact our Heroic Support®.

Enabling Let’s Encrypt for AutoSSL on WHM based Servers

With the recent release of cPanel & WHM version 58 there has been the addition of an AutoSSL feature, this tool can be used to automatically provide Domain Validated SSLs for domains on your WHM & cPanel servers.

Initially this feature was released with support provided for only cPanel (powered by Comodo) based SSL certificates, with the plans to support more providers as things progressed. As of now, cPanel & WHM servers running version 58.0.17, and above, can now also use Let’s Encrypt as an SSL provider. More information on Let’s Encrypt can be found here.

Pre-Flight Check

  • These instructions are intended specifically for a managed Liquid Web server with cPanel.
  • The server should be running cPanel & WHM version 58.0.17, or higher.
  • Command line and root level access via SSH will be necessary to follow this tutorial.

Step #1: Enable Let’s Encrypt Auto SSL provider!

In order to install the Let’s Encrypt AutoSSL provider plugin you will simply log in to the server as the root user via SSH and execute the following command:

# /scripts/install_lets_encrypt_autossl_provider

Running this will add and install the necessary RPM files in order to support Let’s Encrypt as an AutoSSL provider. The command should yield results similar to the following:

Installed the cpanel-letsencrypt RPM! AutoSSL can now use Let’s Encrypt.

Step #2: Verify your work

To double check that this has been successful you can simply pull up WHM and load the ‘Manage AutoSSL’ page. Upon loading this page you should see a list similar to the following screenshot.

WHM AutoSSL w/ Let's Encrypt
If your server’s ‘Manage AutoSSL’ page shows the same options as above you have successfully enabled Let’s Encrypt for AutoSSL.

One thing to keep in mind is that there are some domain and subdomain limits that are enforced by Let’s Encrypt. More details on that can be found in cPanel documentation here: Manage AutoSSL – Domain and rate limits.

How to Disable MySQL Strict Mode

MySQL’s, and MariaDB’s, strict mode controls how invalid or missing values in data changing queries are handled; this includes INSERT, UPDATE, and CREATE TABLE statements. With MySQL strict mode enabled, which is the default state, invalid or missing data may cause warnings or errors when attempting to process the query.

When strict mode is disabled the same query would have its invalid, or missing, values adjusted and would produce a simple warning. This may seem like the preferred result, however with strict mode disabled certain actions may cause unexpected results; for instance, when the value being inserted exceeds the maximum character limit it will be truncated to fit the limit.

There are various reasons why MySQL’s strict mode may need to be disabled, however the most common is when a server is running WHMCS — this is a requirement of that tool.

Pre-Flight Check

  • These instructions are intended specifically for disabling MySQL strict mode on a managed Liquid Web server with cPanel.
  • The server should be running either MySQL 5.6/5.7 or MariaDB 10.x
  • Command line and root level access via SSH will be necessary to follow this tutorial.

Step #1: Make Backups, Always!

Whenever modifying files on a server it’s always best practice to take some form of a backup beforehand. This ensures you have a way to revert changes if something goes awry; it’s also beneficial because it helps track when and what changes were made.

While logged into SSH with the root user, do the following:

cp -a /usr/my.cnf{,.strict.bak}
cp -a /etc/my.cnf{,.strict.bak}

The above command uses ‘BASH brace expansion’ in order to make a backup copy of the file in its original directory.

Step #2: Disable MySQL Strict Mode

Depending on the server and the current configurations you may need to edit one, or both, of the following files on the server. Generally, the relevant configuration lines are only in one of them, however, it could be in either one without causing issues; so generally it’s best to check both.

To edit the files, you will open the file with your favorite command line editor. In this example, we use ‘vim’.

vim /usr/my.cnf
vim /etc/my.cnf

In vim, you can press “a” or “i” to enter text insertion mode; pressing the escape key (Esc) on your keyboard returns you to command mode. For a refresher on editing files with vim, see our New User Tutorial: Overview of the Vim Text Editor.

Within each file above you will be looking for a line with the following content:

sql_mode=NO_ENGINE_SUBSTITUTION,STRICT_TRANS_TABLES

If you find a line similar to the above that is setting the `sql_mode` variable then you will need to replace it with the following line to disable MySQL strict mode.

sql_mode=""

Once this adjustment has been made, or you’ve confirmed the file does not need to be adjusted you will then save and close the file.

Step #3: Restart the MySQL Service

Finally, to make these changes effective you will need to restart the MySQL service as it will only read the configuration files when it initially loads up. In order to force MySQL to use the new configuration files you will do the following:

For CentOS 7 servers:
systemctl restart mysql

For CentOS 6 and prior:
/etc/init.d/mysql restart

After issuing this command on the server the MySQL service will be restarted and will load the changes made. If all the directions were followed and completed, then MySQL strict mode should now be disabled.

To verify that the process was completed properly you can run the following:

mysql -e "SELECT @@sql_mode;"

The output may look similar to the following:

+--------------------------------------------+
| @@sql_mode
+--------------------------------------------+
| NO_AUTO_CREATE_USER
+--------------------------------------------+

If you have any questions or are not comfortable making these changes yourself, please feel free to contact Heroic Support®.