How To Create User-Friendly PHP Script Installation

Note: This tutorial is about creating installation for scripts that users have to install themselves. Assuming you have written such script, the tutorial assumes you have at least intermediate programming experience.

"Open the file include/database.conf.php, go to line 319, and enter DB details as root:password@mysql:localhost. Then CHMOD the file to 755..."

Does your script installation manual look like that? Pretty bad! It shouldn't.

Your scripts must install through a web page. The user should dig as little tech details as possible. If you can limit the complex work to FTP-ing the files and adding DB connection details, that would be best. Just like Wordpress does.


What Makes User-Friendly Script Installation?

Ideally the user would just download your software and start using it. Unfortunately this is not possible with web based scripts because they need to be installed on a web server and usually use a database. Fortunately people who download such script have at least some very basic technical knowledge. They don't need to be explained what is a right-click of the mouse.

Here is what they really need fro your installation:

  • Step by step instructions
  • Not having to deal with script code
  • Preferably web based installation script
  • Understandable error messages
  • Clear information about server requirements

Without following exactly the same order I'll show you what does it take to create such user friendly installation that will keep your users happy and will drastically reduce the number of support emails.

I already implemented these concepts in the latest installations of my exam software and the membership management script. Since then I've literally stopped getting any support emails regarding installation issues.

Keep Most Instructions Right On The Screen

Having installation manual is a must. Unfortunately many users don't read it. Even if they read it, it's hard for them to follow the steps switching their attention between the manual and the actual installation screen. So, when possible, give explanations right on the screen, in the forms your users have to feel.

For example on the screen where they have to enter database connection details, give hints and links about how to create a MySQL database through a web hosting control panel, how to add user to it etc.

Pre-Installation Checks

To avoid frustrations after installation, perform pre-installation checks of the server environment and let user know if something is wrong. It's best even not to allow them to continue if a major feature is not present. Here is for example how some of our installation screens look:

Pre Installation Checks

And here is how to perform such checks:

Checking PHP Version:

$php_version=phpversion();
if($php_version<5)
{
  $error=true;
  $php_error="PHP version is $php_version - too old!";
}

At the end you can decide just to highlight the error or to halt further execution if $error is true.

Checking MySQL Version:

Checking MySQL (or other database) version is harder because you have to connect to the database in order to run a version query. You can do that if you first ask for the DB login details, but it's better to have pre-installation checks as first step.

An option to check before connecting to the DB is to run a function like this (I got this code from somewhere):

// declare function
function find_SQL_Version() { 
  $output = shell_exec('mysql -V');    
  preg_match('@[0-9]+\.[0-9]+\.[0-9]+@', $output, $version); 
  return @$version[0]?$version[0]:-1; 
}

$mysql_version=find_SQL_Version();        
if($mysql_version<5)
{
  if($mysql_version==-1) $mysql_error="MySQL version will be checked at the next step.";
  else $mysql_error="MySQL version is $mysql_version. Version 5 or newer is required.";
}

If the function can't execute shell_exec it returns -1. Then you can use this value to notify the user that there is no error yet because you could not check the version.

Checking Mail and other important PHP functions

Some lame PHP hosts disable mail() function in order to prevent spam. Checking whether mail() or any other more specific function is available is very simple:

if(!function_exists('mail'))
{
  $mail_error="PHP Mail function is not enabled!";
}

Check For Safe Mode

PHP safe mode is pretty boring issue to deal with. Here is how to make sure safe mode is off:

if( ini_get("safe_mode") )
{
  $error=true;
  $safe_mode_error="Please switch of PHP Safe Mode";
}

Checking if Sessions Work

Most PHP scripts use sessions or cookies to store some data. Some hosts don't have sessions or cookies configured properly. Here is a very simple way to check sessions:

$_SESSION['myscriptname_sessions_work']=1;
if(empty($_SESSION['myscriptname_sessions_work']))
{
  $error=true;
  $session_error="Sessions must be enabled!";
}

Then on the front-end (views, templates, HTML code, whatever you call it), displaying the results of your checks is pretty simple:

<?php if(empty($php_error)) echo "<span style='color:green;'>$php_version - OK!</span>";
else echo "<span style='color:red;'>$php_error</span>";?>

It's a good idea even to set a variable called $fatal_error or something like that and set it to true if any of the fatal checks return error. Then you can disable the "next step" button if $fatal_error is true. You don't want users to continue if there is a fatal error.

If there is no fatal error, you can let the user go to the next step:


DB Configuration File On The Fly

Instead of asking the user to open some file in a text editor and mess with a PHP or other programming code, you'd better give them web based form where they can enter their DB details (just like Wordpress does). Then if permissions are in place you can generate the config file or edit it on the fly. Else, present the user a text that they can directly paste in a file so at least they don't have to worry about messing with programming code.

So here is what you can do once they submit a form with fields for DB host, DB name, DB user and DB password:

$db_error=false;
// try to connect to the DB, if not display error
if(!@mysql_connect($_POST['dbhost'],$_POST['dbuser'],$_POST['dbpass']))
{
  $db_error=true;
  $error_msg="Sorry, these details are not correct. 
  Here is the exact error: ".mysql_error();
}

if(!$db_error and !@mysql_select_db($_POST['dbname']))
{
  $db_error=true;
  $error_msg="The host, username and password are correct. 
  But something is wrong with the given database.
  Here is the MySQL error: ".mysql_error();
}

So if $db_error is true, you can show them understandable error so they don't have to wonder what's wrong. You can replace the mysql_ functions with mysqli_ functions to be up to date with the new trends, but for now the current version works fine.

Then construct the Db config code that your app users. It could be something like this:

// try to create the config file and let the user continue            
$connect_code="<?php
define('DBSERVER','".$_POST['dbhost']."');
define('DBNAME','".$_POST['dbname']."');
define('DBUSER','".$_POST['dbuser']."');
define('DBPASS','".$_POST['dbpass']."');
?>";

The code will vary depending on how you have it in your app. What matters is to generate it as a string and have it ready for writing to a file or showing to the user.

Now, if you can write to the existing file you have dedicated for connecting to the DB, do it. If not, let the user copy the code and save the file:

if(!is_writable("inc/db_connect.php"))
{
  $error_msg="<p>Sorry, I can't write to <b>inc/db_connect.php</b>.
  You will have to edit the file yourself. Here is what you need to insert in that file:<br /><br />
  <textarea rows='5' cols='50' onclick='this.select();'>$connect_code</textarea></p>";
}
else
{
  $fp = fopen('inc/db_connect.php', 'wb');
  fwrite($fp,$connect_code);
  fclose($fp);
  chmod('inc/db_connect.php', 0666);
}

That's it! Then let the user continue to the next step.


Create DB Tables and Insert Required Data

This step is simple. Having the connect file in place connect to the DB and run queries to create the tables and insert any data in them. This could look like this:

// assuming you have DB established connection 
// and have the resource identifier in $db_link

$q="DROP TABLE IF EXISTS `users`;";
mysqli_query($db_link,$q);

$q="CREATE TABLE `users` (
`id` bigint(20) unsigned NOT NULL auto_increment,
`username` varchar(100) NOT NULL default '',        
`level` varchar(100) NOT NULL default '',        
PRIMARY KEY  (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8";           
mysqli_query($db_link,$q);

$q="INSERT INTO `users` (username, level) VAUES ('admin','admin');";
mysqli_query($db_link,$q);

Or something similar, hopefully you get the idea.


Redirect To The Right Page

At last, just redirect the user where should go - whether this is admin/index.php, admin.php or where ever you want them to start using your script. Don't let them hang and tell them what to load, just get them there. Like this:

header("Location: admin.php");

That's it. Having such installation will keep you and your users much happier.


Back to top

Contact | About Us | Affiliates | Privacy & Legal | Terms of use | Support policy

Designed by Dani Velkova