Hook System

From PHPDevShell

Finding a hook for your script is easy, most major hook location are covered, if you are looking for a specific hook location I would gladly insert that location in the next release. You can hook scripts to any scripts, plugins and third party plugins. The best practice is to create your hookin scripts through the plugin install (see Writing plugins), however, you could add scripts through the Hooks gui system as well. You need to place hook scripts in your phpDevShell installation location under plugins, lets create a hook called "register" as we will be using this hook file for the example below, so we create in plugins/Sample/hooks/register.hook.php

The hook system is very easy to use, allowing developers to hook inside another plugins script on all the locations the original developer allowed. To see where a user could hook into, simply login to PHPDevShell goto System Admin -> Hook Admin and click on view source next to the script where you would like to hook inside. Now look for tags like,

$template->hook('on_submit');

this means that you can hook a script in that location and benefit in all available variables to add additional functionality. Remember if you as a plugin developer added hook point in your script, any other plugin developer could easily extend your plugin as well.

For this example I am going to hook inside the PHPDevShell plugins registration script to add for example phone number fields. So have a look at the source file for the PHPDevShell registration script. As you can see there are plenty hook locations here, I am most interested in on_submit, on_update and bottom_html. This is the location I will inject my hooks into.

The way it works is, you only have to create one hook script per host script even though it plugs into a host script on multiple locations. Then inside your hooks script you control the location like so;

if ($template->hook_request == 'on_submit')
{
    // Do this...
}
 
if ($template->hook_request == 'on_update')
{
    // Do this...
}
 
if ($template->hook_request == 'bottom_html')
{
    // Do this...
}

This will execute the certain portions only when the hook location is active. You need to place hook scripts in your phpDevShell installation location under plugins, lets create a hook called "register" as we will be using this hook file for the example below, so we create in plugins/Sample/hooks/register.hook.php. So after you created your hook script you can either choose to install it using the plugin auto installer setup or for testing just create it through the gui at System Admin -> Hooks Admin -> New Hook. This will give the hook script immediate access to its host.

So lets have a look at a complete example hooks script, remember the SimplePhonebook, uses hooks and will serve as a good example on hooks. (note the first line about security, it's slighty different from a regular script)

//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Security //////////////////////////////////////////////////////////////////////////////////////////////////////////////
// This string checks security. //////////////////////////////////////////////////////////////////////////////////////////
(is_object($security)) ? null : exit('Access Denied!'); //////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
// Now we determine if we are in the right location for this hook.
// Lets use this hook to see if the field was mandatory and completed.
// Multiple hooks may be added in one hook location,
if ($template->hook_request == 'on_submit')
{
	// Ok, dont panic, the end-user just submitted the registration, lets handle it.
	// We need to do basic error checking for mandatory field.
	if (empty($_POST['cell_number']) && empty($_POST['work_number']) && empty($_POST['home_number']))
	{
		$template->global['hook_field_error'] = true;
		$template->warning(__('Oops, you must give at least one contact number excluding fax number before I will add it to the phonebook database.'));
	}
}
 
// If we got this far, we will have the user id by now as well.
// We can use this hook location to save the results into the database.
if ($template->hook_request == 'on_update')
{
	// How on earth will I know what the user id was that was just saved?
	// Lets get some values to insert into database.
	$user_id      = $template->global['user_id'];
	$cell_number  = $_POST['cell_number'];
	$work_number  = $_POST['work_number'];
	$fax_number   = $_POST['fax_number'];
	$home_number  = $_POST['home_number'];
 
	// Lets save database string.
	// Insert into the database.
	$db->new_query
	("
		REPLACE INTO
			_db_simple_phonebook (user_id, cell_number, work_number, fax_number, home_number)
		VALUES
			('$user_id', '$cell_number', '$work_number', '$fax_number', '$home_number')
	");
 
	$template->ok(sprintf(__('Contact numbers for user id %s was added.'), $user_id));
 
}
 
// Again we determine if we are in the right location for this hook.
// Do HTML for bottom_html hook.
// Multiple hooks may be added in one hook location,
if ($template->hook_request == 'bottom_html')
{
	// Ok, lets create extra field for a telephone number.
	$HTML = <<<HTML
		<tr class="highlight">
			<th class="head" colspan="2">
				{$core->__('SimplePhonebook Database')}
			</th>
		</tr>
		<tr class="highlight">
			<td>
				{$core->__('Cell Number')}
			</td>
			<td>
				<input type="text" size="20" name="cell_number" value="{$_POST['cell_number']}" class="boxnormal">
				{$template->info_mark(__('Enter users Cell Number'))}
			</td>
		</tr>
		<tr class="highlight">
			<td>
				{$core->__('Work Number')}
			</td>
			<td>
				<input type="text" size="20" name="work_number" value="{$_POST['work_number']}" class="boxnormal">
				{$template->info_mark(__('Enter users Work Number'))}
			</td>
		</tr>
		<tr class="highlight">
			<td>
				{$core->__('Fax Number')}
			</td>
			<td>
				<input type="text" size="20" name="fax_number" value="{$_POST['fax_number']}" class="boxnormal">
				{$template->info_mark(__('Your Fax Number'))}
			</td>
		</tr>
		<tr class="highlight">
			<td>
				{$core->__('Home Number')}
			</td>
			<td>
				<input type="text" size="20" name="home_number" value="{$_POST['home_number']}" class="boxnormal">
				{$template->info_mark(__('Your Home Number'))}
			</td>
		</tr>
HTML;
 
}

The following hook locations types are available for the developer to user or to include in your own code;

$template->hook('head');
$template->hook('header');
$template->hook('foot');
$template->hook('on_submit');
$template->hook('on_update');
$template->hook('before_update');
$template->hook('on_delete');
$template->hook('on_edit');
$template->hook('inline');
$template->hook('check');
$template->hook('check_errors');
$template->hook('check_general');
$template->hook('head_html');
$template->hook('top_html');
$template->hook('middle_html');
$template->hook('bottom_html');
$template->hook('aaa_general');
$template->hook('baa_general');
$template->hook('caa_general');
$template->hook('daa_general');
$template->hook('eaa_general');
$template->hook('faa_general');
$template->hook('gaa_general');
$template->hook('haa_general');
$template->hook('iaa_general');
$template->hook('jaa_general');
$template->hook('kaa_general');
$template->hook('laa_general');
$template->hook('maa_general');
$template->hook('naa_general');
$template->hook('oaa_general');
$template->hook('paa_general');
$template->hook('qaa_general');
$template->hook('raa_general');
$template->hook('saa_general');
$template->hook('taa_general');
$template->hook('uaa_general');
$template->hook('vaa_general');
$template->hook('waa_general');
$template->hook('xaa_general');
$template->hook('yaa_general');
$template->hook('zaa_general');
$template->hook('aba_general');
$template->hook('aca_general');
$template->hook('ada_general');
$template->hook('aea_general');
$template->hook('afa_general');
$template->hook('aga_general');
$template->hook('aha_general');
$template->hook('aia_general');
$template->hook('aja_general');
$template->hook('aka_general');
$template->hook('ala_general');
$template->hook('ama_general');
$template->hook('ana_general');
$template->hook('aoa_general');
$template->hook('apa_general');
$template->hook('aqa_general');
$template->hook('ara_general');
$template->hook('asa_general');
$template->hook('ata_general');
$template->hook('aua_general');
$template->hook('ava_general');
$template->hook('awa_general');
$template->hook('axa_general');
$template->hook('aya_general');
$template->hook('aza_general');
$template->hook('aab_general');
$template->hook('aac_general');
$template->hook('aad_general');
$template->hook('aae_general');
$template->hook('aaf_general');
$template->hook('aag_general');
$template->hook('aah_general');
$template->hook('aai_general');
$template->hook('aaj_general');
$template->hook('aak_general');
$template->hook('aal_general');
$template->hook('aam_general');
$template->hook('aan_general');
$template->hook('aao_general');
$template->hook('aap_general');
$template->hook('aaq_general');
$template->hook('aar_general');
$template->hook('aas_general');
$template->hook('aat_general');
$template->hook('aau_general');
$template->hook('aav_general');
$template->hook('aaw_general');
$template->hook('aax_general');
$template->hook('aay_general');
$template->hook('aaz_general');

Even the hook scripts requires dead simple php code.

Hook System

From PHPDevShell

Views

Personal tools

Navigation

Search

Toolbox