Ioncube Encoder Pro or Cerberus is required to generate license files that can be distributed to your customers. Most of the nitty-gritty involved with the make_license executable can be found in the user guide (a pdf document) distributed with the encoder in section 4. The entry level version of Ioncube Pro cannot generate licenses, however much of the same restrictions can be applied to an encoded project (section 3 of the user guide) on a per-customer basis, pro/cerberus eliminates the hassle with having to re-encode and redistribute the project for each customer.
In this article we’ll talk about two of the most popular restrictions that can be applied to a license. But first we need to look at how to prepare a project to be used with a license. Since I am using Mac OSX there is no graphical user interface, as such these instructions will be based on the command line options.
Preparing Project for License Management
Let us say that we have our project in a folder called myproject, the simplest way to encode such would be to use the following command (ioncube_encoder5 is for PHP 5.x, ioncube_encoder is for PHP 4.x, version 7 of Ioncube will likely have a separate binary for PHP 5.3 encoding)
ioncube_encoder5 /projects/myproject --into /encoded-projects
The above will encode myproject into a new folder located under /encoded-projects, no licensing or restrictions has yet been applied. To encode the project so that a license file is required you add
ioncube_encoder5 --with-license key.php --passphrase yourpassphrasehere /projects/myproject --into /encoded-projects
Note there is a passphrase used, you must use a passphrase when specifying a license file to be searched, you will use the same passphrase when generating a license with make_license. With the options above the encoded files will search for a file called key.php, and will check the parent folder recursively until it finds it. If it is a valid license the script will execute normally. If it is not, you’ll get a simple error stating that the code has an invalid license.
However I’ve always preferred to show errors a bit more gracefully and more explanatory and to do so the script needs to be able to handle the validation. To do this we add the –license-check option like so.
ioncube_encoder5 --with-license key.php --passphrase yourpassphrasehere --license-check script \ /projects/myproject --into /encoded-projects
What this does is disables the automatic checking done by the ionCube loader, and allows you to handle the script’s response to an license issue using the Loader API. Below is a simple example how to check if the license is expired and respond accordingly.
<?php if(ioncube_file_is_encoded() === false) { /* if this is in a function you can return true to bypass license check if the file is not encoded, makes it easier to debug when you don't have to keep turning on and off the license check during coding and encoding. */ } else { //Obtains the license properties $ic_prop = ioncube_license_properties(); /* Always use === when matching boolean, since a non-boolean response could be interpreted as true or false when it would in fact be an array or other value. For example the function above will return an array of license properties, but if the file is not encoded or does not have a valid license it will return FALSE. As such will never return TRUE but an array response comared with == could be interpreted as a FALSE response. */ if($ic_prop === FALSE) { //ioncube_license_properties returns false if a license file is not found or invalid/corupted echo "License File Not Found or Not Valid."; exit(); } /* The two functions below will return FALSE if the file is 1) encoded, 2) requires a license and 3) the server/time does not meet the license restrictions. */ if(ioncube_license_matches_server() === FALSE) { //This will check to see if the current domain matches the license restriction echo "License is Not Valid for This Domain."; exit(); } $expiry = ioncube_license_has_expired(); if(ioncube_license_has_expired() === TRUE) { //The above function will return true if the license is expired echo "License Has Expired."; exit(); } /* Other checks such as property values, like encoding the user's transaction ID or feature restrictions from the license file. License properties such as UserName can be grabed like so: $ic_prop['UserName']['value'] */ }
So there you have it a very brief explanation of how to encode a project to use a license, and how to check for the license yourself so that you may control the output (such as making your own branded page with the error as opposed to a simple text on white background) or alter the project’s features based on the license properties.
Generating a License with make_license
The ionCube encoder ships with a make_license binary, the Windows and Linux version of the encoder both ship with a linux version of the binary (plus a windows executable for Windows). The Mac OSX version of the encoder only ships with an OSX binary of make_license, which annoyed me quite a bit as I tried to use it on my linux-based hosting provider. For OSX users as of version 6.5 you have to request a linux binary of the make_license file from ionCube support.
In a nutshell this is how utilize the make_license binary manually on a linux server:
./make_license --passphrase yourpassphrasehere --header-line '<?php exit(0); ?>' --property "UserName='Chuck Norris'"
Note that you have to use the same passphrase used to encode your project. The above license has no restrictions yet, rather just a few header lines and encoding a property called UserName with the value of Chuck Norris within. The results of above will generate something like this:
<?php exit(0); ?> ------ LICENSE FILE DATA ------- 9TS21X45EIPmmmjcWh+ZLlelwqJyMLD8 R2SpnyDbbMtdlpgO5bKYCwVI8wM1oqH1 SCLOc/tJ93duEBVt1BFX6//GL+UkLtXI ZxYecENH0KR6sAoR5iEDSMcgicXpxcto NR0VDOJETrkmWGHkc+KhpELoB4iF+RjB ALizJ3gzQjL9HTfDZS+zGF0JVzy7IBrg fNJ5pvxUJ+p/15hrhnYfWhOlkB5lhr/x B+ommB3rAwVAxhRVf0nHGisRo+TFEKi= --------------------------------
The reason for the header lines is because I like to generate my licenses as php files, such as key.php, this way the license in a public location cannot be viewed via the web since the PHP portion would exist the script before it reached the license data, and its easier than telling your customers to place the license data outside of the public_html folder, especially if you’re not using domain or hardware restrictions on the license file.
To add a domain restriction such as example.com (and www.example.com) we would add –allowed-server option like so.
/make_license --passphrase yourpassphrasehere --header-line '<?php exit(0); ?>' \ --property "UserName='Chuck Norris'" --allowed-server example.com,www.example.com
The above will make it so that the license is only valid on example.com and www.example.com, wildcards can also be used such as *.domain.com, or for a single character api?.domain.com (where ? can be no more than a single character), you can also use brackets to match a defined set such as [123].domain.com would match 1.domain.com 2.domain.com and 3.domain.com, likewise [!123].domain.com would match any domain as long as it wasn’t 1., 2. or 3. IP ranges can also be defined (Section 3.6.3 of the user manual for more details).
Time-based restrictions can be applied with –expire-in and –expire-on.
--expire-in 7d --expire-in 8h --expire-on 2012-12-21
The first two would expire in 7 days, or 8 hours, the last one would expire on December 21st 2012 (along with the rest of us).
On Page 2: Automating License Generation with PHP or Python