Who is this for?
This guide is for those that are not particularly fond of reading code or documentation. Let’s face it, most of us don’t! So, the system integration is kept simple as possible without too much technical l33t’ness.
For you developers, take a look at the implementation documentation which also contains the change log between versions.
YOUR system...
Is fantastic! Yes, why else would you spend time and money on integrating such a rich featured Installer like this one to your system? I'm flattered, I am :)
So how do we do this? Especially when neither of us really wants to read (in my case write) too much text or go over some boring documentation? Let's start by looking at some screenshots with huge arrows in them!
Well, no, it isn't. This is phpBB3. However, this structure might have some similarities to yours or you could at least relate to it.
First step
Simply copy one of the installer folders from the examples in Installer Examples folder. This guide will use the Normal example. Just drop it into your system folder... like this:
Locate and copy your configuration
Can you find your system config? That's a rather silly question, but serves the purpose. Simply copy everything in your configuration file.
Locate masks
Open the installer folder, which you just threw into your systems folder. Once open, you should see 4 folders, and 3 files:
Open the masks folder and you will see four mask files. One of them has a .php extension – which will be the configuration mask (template) for your system.
Editing the Config mask
First off, the name of the mask file is database_config.php and your systems configuration file is named config.php... probably isn't, but let's pretend here!
So, rename the mask file so it will match the name of your system config file, in this case, config.php.
Open the renamed mask file and you will see some PHP code in it. Notice that the string values in the sample config are "replaceable keywords".
NOW, clear the mask file and paste the copied configuration PHP code from your config file - into the mask file! If this would be the phpBB config, the masked config should be changed to:
There is just ONE more thing to do here, and that is to tell the Installer that you renamed the PHP config mask.
How do we do that? Later in this guide we edit the Installers configuration.php and we will take care of everything in one pass-through.
Editing the SQL mask
This one is even simpler than editing the configuration mask! No bullshit here mates! Just export all your database tables using PhpMyAdmin (or some other similar tool) and paste all the exported stuff into database_commands.sql mask file.
But wait!! What about the table prefix? We have to go through the queries and add the {dbprefix} keyword in front of all table names so that feature in the Installer will work properly.
The hard part is now done! The rest of the stuff just gets easier as it goes along, I promise :)
The other masks
Are not as crucial as PHP code and SQL queries, they are edited the same way and are used to display information to the user. So, if anything goes wrong in them you should be able to spot them as you test the installation.
Editing the Installer config
Is simpler than you think, the config is full of descriptive comments and pretty easy to navigate.
There are few settings we need to change to make the installer as general as possible.
PHP Requirements step
is enabled with 'directives' switched on. If you do not care about Safe Mode, Register Globals or Magic Quotes Runtime or have no idea what they are, then make sure you have directives set to false.
Next are the loaded extensions, and we are going to be using the mysql extension. Which, you know, is the extension that provides PHP the ability to interact with MySQL database. So just remove the encryption part.
If you do not care about the PHP version, just set both to false and everything will be acceptable. But, if you want to support every PHP5 version (like most want) then set phpversion to 5.0.0 and maxversion to 5.x.x
'maxversion' => '5.x.x', # means maximum version of 5
The supported range will be between 5.0.0 – 5.99.99. See section 6.2 in the Implementation documentation for more information.
Language step
Is enabled but you probably don't need that, so put the enable setting to false.
If you do however, then you must know that the key is the value that will be written to system config file. In other words, if the config is set like
'supported' => array(
'uk'=>'English (UK)',
'usa'=>'English (USA)',
'de'=>'German',
'fr'=>'French'),
Then English (UK) will be selected by default in the step, and uk will be the value written to your config. The keys should match the flag image names, so if you need to rename the language keys then rename the flag images accordingly ('uk' = 'uk.png').
Create Configuration File
is the last step we are going to change. Remember that we renamed the mask file earlier to config.php? Now change the value for maskname, and if the your config was placed in a folder called, let's say, includes, then you would put 'includes' in 'savetofolder'.
'savetofolder' => 'includes',
Keep it blank if your config.php is located in the very same folder as index.php.
The installer supports multiple configs, and if you have more than one config you have to add more array entries into the 'configs' setting. Let's say you have to add dbconf.php as well, but that file is located in system directory ... no problem!
array('maskname' => 'config.php',
'savetofolder' => 'includes'),
array('maskname' => 'dbconf.php',
'savetofolder' => 'system'),
),
Installer Settings
Is where we configure the Installer itself. If you want the Installer to ignore itself after installation, then just put this to true.
This means that as long as there exists a config for your system (and it contains something), the Installer will be ignored. If the config would be deleted, the installer would arise again and show you the installation steps needed to configure your system. Neat, isn't it?
If you want the Installer to delete itself automatically, then you need to set these three accordingly.
'allow_self_destruction' => true,
'automatically_self_destruct' => true,
The keywords
You might want to change the keywords as well, as I assume your project is not named Normal-System :)
'company' => 'Normal-Company',
'product' => 'Normal-System',
'version' => '2.12 RC',
Connecting Installer and System
The Installer is implemented such that it cannot be started directly from browser. Which means that
Will NEVER work!
This is done to enhance security as ONLY YOUR SYSTEM can launch the installer. So, there is no need to logon to FTP to remove some installer folder, or open some specific installation URL – just run the system normally and the Installer will take care of the rest.
Sounds complicated? It is very simple, first we open up index.php
And put this code AT THE VERY TOP OF IT!! It's very important, hence the casing ;)
define('INST_RUNSCRIPT', pathinfo(__FILE__, PATHINFO_BASENAME));
define('INST_BASEDIR', str_replace(INST_RUNSCRIPT, '', __FILE__));
define('INST_RUNFOLDER', 'installer/');
define('INST_RUNINSTALL', 'installer.php');
if (is_dir(INST_BASEDIR.INST_RUNFOLDER) &&
is_readable(INST_BASEDIR.INST_RUNFOLDER.INST_RUNINSTALL))
require(INST_BASEDIR.INST_RUNFOLDER.INST_RUNINSTALL);
?>
This code specifies some information for the installer so it will know where it was launched from. Then checks if the installer exists and is readable, and if so it is launched.
Done!
Before you test the installer, you should try out the Configuration Overview tool, it shows you what steps are enabled, which steps are "hidden" and so on.
