Custom Integration

From Softaculous Wiki
Jump to: navigation, search

Overview

If you have a custom panel and would like to integrate Softaculous, you have made the right decision and you are at the right place.


Pricing

The pricing for custom based integrations is $0.1/month/user with minimum $100/month in billing.

Getting Started

Please download the following files :
http://files.softaculous.com/custom/latest.php
Note : This will download the custom package which will be in the name of the VERSION.zip E.g. If the version is 4.0.3 it will download the 4.0.3.zip In this documentation we refer this package as custom.zip
http://files.softaculous.com/integrating.zip

custom.zip

custom.zip is the Softaculous core. Please unzip and store the files in a suitable location on the server. e.g.

/usr/local/softaculous

NOTE : Softaculous has to be installed on the server(s) where the user files will be stored. It cannot install on ANY REMOTE server. Softaculous should be able to access the users directories to be able to unzip and delete files when required. If you have multiple servers then you will have to install Softaculous on all the servers.

The PANELs webserver (e.g. Apache) must point to the enduser folder which is there in the Softaculous Core.
So if you extract your files to /usr/local/softaculous the enduser folder is located at /usr/local/softaculous/enduser/. This is the User Interface of Softaculous for the ENDUSER.
Also it is very important that apache OR your webserver should be RUNNING as the UNIX user of the LOGGED in user e.g. if user username is logging into your Control Panel and visiting Softaculous, apache should run as user username. This is necessary in order to be able to unzip the files in the users directories.

integrating.zip

integrating.zip has 2 important files :
1) universal.php - PHP File which is the config
2) softpanel.php - a Class which will interact with your panel

NOTE : All these files must be placed in the enduser folder. e.g. /usr/local/softaculous/enduser

Understanding universal.php

universal.php is a very important configuration file of Softaculous. It contains the variables, that are required by Softaculous to work. It has the Path Definitions of Softaculous Files and also most of the Configuration of Softaculous is stored in this file. Below is a sample configuration file. But while integrating PLEASE use the universal.php from the custom.zip you downloaded using the latest.php file. The files in integrating.zip are just for example.

<?php

//////////////////////////////////////////////////////////////
//===========================================================
// universal.php
//===========================================================
// SOFTACULOUS 
// Version : 1.1
// Inspired by the DESIRE to be the BEST OF ALL
// ----------------------------------------------------------
// Started by: Alons
// Date:       10th Jan 2009
// Time:       21:00 hrs
// Site:       http://www.softaculous.com/ (SOFTACULOUS)
// ----------------------------------------------------------
// Please Read the Terms of use at http://www.softaculous.com
// ----------------------------------------------------------
//===========================================================
// (c)Softaculous Inc.
//===========================================================
//////////////////////////////////////////////////////////////

if(!defined('SOFTACULOUS')){

	die('Hacking Attempt');

}

$globals['path'] = '/usr/local/softaculous'; // Where the Softaculous folder exists.
$globals['softscripts'] = '/var/softaculous'; // Where the script packages are going to be stored
$globals['sn'] = 'Softaculous';
$globals['cookie_name'] = 'SOFTCookies817';
$globals['gzip'] = 1;
$globals['language'] = 'english';
$globals['soft_email'] = 'admin@softaculous.com';
$globals['theme_folder'] = 'default';
$globals['timezone'] = 0;
$globals['mail'] = 1;
$globals['mail_server'] = '';
$globals['mail_port'] = '';
$globals['mail_user'] = '';
$globals['mail_pass'] = '';
$globals['off'] = 0;
$globals['off_subject'] = '';
$globals['off_message'] = '';
$globals['update'] = 1;
$globals['update_softs'] = 1;
$globals['add_softs'] = 1;
$globals['email_update'] = 1;
$globals['email_update_softs'] = 1;
$globals['cron_time'] = '1 8 * * *';
$globals['chmod_files'] = '';
$globals['chmod_dir'] = '';
$globals['is_vps'] = 0;
$globals['logo_url'] = '';
$globals['php_bin'] = '';

$globals['enduser'] = $globals['path'].'/enduser';
$globals['mainfiles'] = $globals['enduser'].'/main';
$globals['adminfiles'] = $globals['mainfiles'].'/admin';
$globals['euthemes'] = $globals['enduser'].'/themes';

?>

Explanation of Important Variables

$globals['path'] - Is the Path where Softaculous CORE will reside
$globals['softscripts'] - Is the Path where Softaculous Script Packages will be stored
$globals['sn'] - sn = Site Name that will be shown in the browser
$globals['cookie_name'] - The Cookie Name which will be used by softaculous when cookies are created
$globals['gzip'] - Output in COMPRESSED FORMAT to the BROWSER if the BROWSER supports it
$globals['language'] - The default language folder. Should be available in /path/to/softaculous/enduser/languages/LANGUAGE_NAME
$globals['soft_email'] - The ADMIN Email address for CRON email notifications and other notifications

Understanding softpanel.php

This is the Main file which will act as the point of interacting with your Control Panel. Its a simple class which takes care of many important activities like Creating and Deleting Databases, the disk space available, the logged in user information, etc.

Functions of the Softpanel Class

Here is a little bit explanation of important functions. There are enough comments in the code you downloaded.

function softpanel()
function softpanel(){
	global $cpanel;
	
	//Some Theme Settings
	$this->theme['softimages'] = 'softimages';// Relative to the accessed URL
	$this->theme['url'] = 'themes';// Relative to the accessed URL
	$this->theme['admin_url'] = 'enduser/themes';// Relative to the accessed URL
	$this->theme['logout'] = '/logout/'; // Relative to the accessed URL
	$this->theme['panel_url'] = '/'; // Relative to the accessed URL
	
	// Are you a Dedicated or Virtual Server
	$this->env = '';
	
	if(defined('SOFTADMIN')) return true;

	//Load the Raw Data
	$this->rawdata = $this->rawdata();
	
	//Load the Data
	$this->user = $this->userdata();
	$this->domainroots = $this->domainroots();
	$this->spaceremain = $this->spaceremain();

}

This is the Contructor class.
$this->theme is an array to adjust the theme location so that you can modify the URL of static theme files.
It also loads up the variables :
$this->user - An array of the user information. See function userdata()

$this->domainroots - An array of the domains and their PATHS. See function domainroots()

$this->spaceremain - An integer of the space available. See function spaceremain()


function rawdata()
function rawdata(){
    // Any data you want to load first
}

This is just a function to load any data which might be used by other functions in the class when they are called. You can put all your important data processing code here so that you dont have to reload everything again.


function userdata()
function userdata(){

	$user = array();
	$user['name'] = 'username'; // Username of the account used for MySQL purposes
	$user['displayname'] = 'thedisplayname';// For displaying the actual name
	$user['email'] = 'email@address.com'; // Email of the account
	$user['domain'] = 'domain.com'; // Primary Domain of the account
	$user['homedir'] = '/home/username';// Home Dir of the account
	
	// Softaculous will create a DIRECTORY in this path and files in that DIRECTORY
	// e.g. $this->rawdata['homedir']/.softaculous/files.php
	$user['softdir'] = '/home/username';
	
	return $user;
	
}

You must return the array as shown in the code. It is self explanatory. $user['softdir'] is the path where the .softaculous folder is created.


function domainroots()
// Should return the paths of all domains under this account
function domainroots(){
	
	$array = array();
	
	//The Default Domain with public_html
	$array['domain.com'] = '/home/username/public_html';
	$array['sub.domain.com'] = '/home/username/public_html/sub'; // E.g. of a sub domain
			
	return $array;
	
}

Return value should be a array as shown above. It is of the format domain => /path/to/files/of/domain


function dbhost()
//The Host of the Database
function dbhost($type = 'mysql'){
	return 'localhost'; // If any other host please return that!	
}

Return value should be the MySQL host.


function maxdb()
//The Maximum Number of Database
function maxdb($type = 'mysql'){
	
	return 100000; // The max number of DBs allowed to this user. If a string is given it will be assumed as Unlimited!

}

Return value should be the max number of DBs allowed to this user. If a string is given it will be assumed as Unlimited!


function dbsused()
// Number of dbs used
// If unlimited return a string
function dbsused(){		
	return $this->rawdata['currentMysqlDatabases'];
}

This function is called to CHECK whether the existing number of databases is not GREATER that or EQUAL to (>=) then the allowed number of Databases. Return value should be an int or a string.


function dbname()
// Return the DBNAME as per the panel
// e.g if dbname is given and a prefix is required then please give it here
function dbname($dbname){		
	return $dbname;		
}

If the panel requires to modify the DB NAME that is to be created when installing a script, it has to be done here. Many panels e.g. cPanel accept input from users as DBNAME but create Databases like USERNAME_DBNAME. In such a case this function must return USERNAME_DBNAME


function dbuser()
// Return the DBUSERNAME as per the panel
// e.g if dbusername is given and a prefix is required then please give it here
function dbuser($dbuser){
	return $dbuser;		
}

If the panel requires to modify the Database USER NAME that is to be created when installing a script, it has to be done here. Many panels e.g. cPanel accept input from users as DBUSERNAME but create Databases like USERNAME_DBUSERNAME. In such a case this function must return USERNAME_DBUSERNAME


function dbexists()
// Check whether the Database Exists
// Return true if it exists or false it doesnt
function dbexists($dbname){
	$res = mysql_query("SHOW DATABASES LIKE '$dbname'", $this->conn['conn']);
	if(mysql_num_rows($res) > 0){
		return true;
	}
	return false;
}

This is a function to check whether the Database already exists or not Should return TRUE or FALSE as the case may be.


function dbuserexists()
// Check whether the Database User Exists
// Return true if it exists or false it doesnt
function dbuserexists($dbuser){
	$res = mysql_query("SELECT User FROM mysql.user
						WHERE User = '$dbuser'", $this->conn['conn']);
	if(mysql_num_rows($res) > 0){
		return true;
	}
	return false;
}

This is a function to check whether the Database USER already exists or not Should return TRUE or FALSE as the case may be.


function createdb()
//This will create a Database
function createdb($dbname, $dbuser, $dbpass, $type = 'mysql'){

	// This should create a Database and its user when called
	
	return true;
	
}

This function should create the DATABASE and also the Database USER. The user must also be added to the database so that the user can conduct all necessary operations on the Database.
Parameters :

  • $dbname - The is value that is got from function dbname()
  • $dbuser - The is value that is got from function dbuser()
  • $dbpass - The is a randomly generated string that will be passed by Softaculous when createdb() is called.


function deldb()
//Delete a Database and user
function deldb($dbname, $dbuser, $type = 'mysql'){

	// This should delete a Database and its user when called
	
	return true;

}

This function should delete the DATABASE and also the Database USER.
Parameters passed :

  • $dbname - The is value that is got from function dbname()
  • $dbuser - The is value that is got from function dbuser()


function spaceremain()
//Shows the Disk Space Available
function spaceremain(){
	
	// Note: 1) Should be in BYTES
	//		 2) If it is not numeric then SOFTACULOUS will assume as UNLIMITED space
	
	$space = (1024*1024*1024); // e.g. of a GB
	
	return $space;
	
}

Should return the space available in BYTES. If a string is returned it will be assumed that the user has unlimited space.


function addcron()
// Add a CRON JOB
function addcron($min, $hour, $day, $month, $weekday, $command, $mail = ''){	
	
	return true;
	
}

Add a CRON job for a script.
Parameters passed :

  • $min
  • $hour
  • $day
  • $month
  • $weekday
  • $command - The CRON Command itself.


function delcron()
// Deletes a CRON JOB as per the command given
function delcron($command){

	return true;
	
}

Delete a CRON job of a installation.
Parameters passed :

  • $command - The CRON Command itself. You will have to search and delete the cron job accordingly.


Softaculous CRON

Softaculous has a CRON job that downloads the SCRIPTS from our servers and keeps them uptodate. It is located at :

/path/to/softaculous/cron.php

You can put a file /etc/cron.d/softaculous with the following contents :

1 8 * * * root /usr/bin/php /path/to/softaculous/cron.php >> /dev/null 2>&1

Upgrading

Just unzip the new integrating.zip on to your /path/to/softaculous/

You can find the integrating.zip here: http://files.softaculous.com/integrating.zip

Support

You can always ask us if you have any queries. The support department can be accessed from here : https://www.softaculous.net/support/