Topic: A guide to the SMF integration hooks

[Orstio]

One of the great things about SMF is the fact that it has integration hooks throughout the code at key points so that you can add integration functions in at those key points without actually modifying any SMF code at all.


Please note that the documentation about integration hooks for SMF 2.x can be found on the wiki at the page Integration hooks.



Added by emanuele: the information in this topic are still valid for SMF 1.1, that's why the topic is still sticky.

This topic will be a guide to the usages of these hooks.  I hope it serves useful.

Starting up the integration system
The hooks
integrate_pre_include
integrate_pre_load
integrate_verify_user
integrate_validate_login
integrate_login
integrate_logout
integrate_activate
integrate_fix_url
integrate_verify_password
integrate_reset_pass
integrate_delete_member
integrate_register
integrate_outgoing_email
integrate_personal_message
integrate_change_member_data
integrate_redirect
integrate_exit
integrate_whos_online

New in SMF 2.0:
integrate_create_topic
integrate_load_theme
integrate_ouput_error

[Orstio]

There are numerous methods to start up the integration hook system.

Typically, when creating a bridge, I have SMF "wrapped" within the context of a CMS, so the startup is done in the CMS, as a part of the component/module that displays the forum.

I prefer to use the serialized constant method:

Code: [Select]

//define the integration functions
define('SMF_INTEGRATION_SETTINGS', serialize(array(
'integrate_change_email' => 'change_email_function',
'integrate_change_member_data' => 'change_member_data_function',
'integrate_reset_pass' => 'reset_pass_function',
'integrate_exit' => 'exit_function',
'integrate_logout' => 'logout_function',
'integrate_outgoing_email' => 'outgoing_email_function',
'integrate_login' => 'login_function',
'integrate_validate_login' => 'validate_login_function',
'integrate_redirect' => 'redirect_function',
'integrate_delete_member' => 'delete_member_function',
'integrate_register' => 'register_function',
'integrate_pre_load' => 'pre_load_function',
'integrate_whos_online' => 'whos_online_function',
)));
You will notice the format:
     'hook name' => 'function name'

The names of the hooks are defined in SMF code, and the function name can be whatever you want.  In fact, it could even be a native function of the system in which you are integrating.  This is very open-ended.

Alternatively, the 'hook name' => 'function name' can be entered into SMF's settings table with an installation query, as 'variable' => 'value', and the result will be the same.  In this case, you wouldn't need to define the SMF_INTEGRATION_SETTINGS constant; the values would be pulled from the settings table along with all of SMF's other settings.

[Orstio]

Now that we've defined the functions that will be called whenever a hook event takes place, we need to know what these hooks are, and when they take place, and the expected input and output for each one.

This is a list of all the SMF integration hook names to date:

integrate_pre_include
integrate_pre_load
integrate_verify_user
integrate_validate_login
integrate_login
integrate_logout
integrate_activate
integrate_fix_url
integrate_verify_password
integrate_reset_pass
integrate_delete_member
integrate_register
integrate_outgoing_email
integrate_personal_message
integrate_change_member_data
integrate_redirect
integrate_exit
integrate_whos_online

The following posts will discuss each one in detail.

[Orstio]

Used in file:  Load.php
Used in function:  reloadSettings

Variables passed to hook function:  None
Variables expected from hook function: None

Usage:  This hook actually calls a file, not a function.

e.g. 'integrate_pre_include' => 'integration.php'

This is the very first integration hook encountered in the workflow.  It is started immediately after the loading of the SMF settings.  So, if you need to include some scripting at the beginning of SMF, this can be done with this hook in a separate file, without any need for modifying the SMF code.

Example of use:  Information is needed from a separate system that needs to be started after SMF is loaded.

[Orstio]

Used in file:  Load.php
Used in function:  reloadSettings

Variables passed to hook function:  None
Variables expected from hook function: None

Usage:  This hook is started immediately after the integrate_pre_include hook.  It serves much of the same type of purpose, but it calls a function rather than including a file.

Example of use:  Modifying SMF settings to match those of an integrated system.

[Orstio]

Used in file:  Load.php
Used in function:  loadUserSettings

Variables passed to hook function:  None
Variables expected from hook function: $ID_MEMBER (int)

Usage:  This hook is started before checking the SMF cookie for a valid user.  A valid SMF $ID_MEMBER is expected back from the hook function, or SMF will assume it should check the SMF cookie instead.

Example of use:  User is logged into a CMS, but not into SMF, so we want to auto-login to SMF without the SMF cookie.

[Orstio]

Used in file:  LoginOut.php
Used in function:  Login2

Variables passed to hook function:  $_REQUEST['user'], $_REQUEST['hash_passwrd'], $modsettings['cookieTime']
Variables expected from hook function: true, false, or 'retry'.

Usage:  This hook is started before checking for a valid SMF user on login.  This gives the integrated application a chance to use the login credentials before SMF does.  Something to keep in mind is that SMF hashes the password in SHA1 on the client side, so an unhashed password is not available to this function.

A value of true or false returned from the function will continue as normal, and a value of 'retry' will redisplay the login form, with the message "Password security has recently been upgraded.  Please login again."

Example of use:  A user that exists in the integrated application but not in SMF is attempting to login, so needs to ber migrated to SMF before SMF has a chance to authenticate.  Something to keep in mind here is that SMF can authenticate with many other types of hashes, so the hashed passwords of other systems can typically be written directly to the SMF members table, with the hook returning 'retry', which will automatically invoke SMF to rewrite to its own hash on the second login attempt.

[Orstio]

Used in file:  LoginOut.php
Used in function:  Login2

Variables passed to hook function:  $user_settings['memberName'], $_REQUEST['hash_passwrd'], $modsettings['cookieTime']
Variables expected from hook function: None

Usage:  This hook is started after authentication in SMF, but before setting the SMF cookie.  It's main use is setting the login cookie of an alternative system.  Because the user is already authenticated in SMF at this point, there is very little need for further authentication checks.

Example of use:  A user has logged into SMF, and should also be logged into the integrated system at the same time.

[Orstio]

Used in file:  LoginOut.php
Used in function:  Logout

Variables passed to hook function:  $user_settings['memberName']
Variables expected from hook function: None

Usage:  This hook is started before the user entry is deleted from the SMF log online table, and the SMF cookie is dropped.

Example of use:  A user has logged out of SMF, and should also be logged out of the integrated system at the same time.

[Orstio]

Used in file:  ManageMembers.php, Profile.php
Used in function:  AdminApprove, saveProfileChanges

Variables passed to hook function:  The username of the user to be changed
Variables expected from hook function: None

Usage:  This hook is started in two instances.  Whenever the administrator approves members, each of those members' usernames is passed to the hook function for activation in the integrated system as well.  The first instance is in the SMF admin panel, and the second is in the user profile.

Example of use:  A user has registered, and is awaiting admin approval of his account to use both SMF and the integrated application.

[Orstio]

Used in file:  News.php
Used in function:  fix_possible_url

Variables passed to hook function:  The current URL passed to the fix_possible_url function
Variables expected from hook function: The modified URL

Usage:  This hook is started only in XML feeds.  It expects a URL, and is expected to return an alternative URL based on the one passed to it.

Example of use:  SMF is wrapped in a CMS, and the URL of the wrapped CMS needs to appear in outgoing RSS feeds.

[Orstio]

Used in file:  Profile.php, Security.php
Used in function:  modifyProfile2, validateSession

Variables passed to hook function:  username, password
Variables expected from hook function: true/false

Usage:  This hook is started only when sensitive information may be getting changed.  It is called when a user is changing his email address, and when an admin is using the SMF admin panel.  It validates the username and password against the integrated system before proceeding.  SMF expects a value of true if the authentication passes, and false if it fails.

Example of use:  You want an added layer of security to authenticate user changes and SMF admin panel access.

[Orstio]

Used in file:  Profile.php, Reminder.php, Subs-Auth.php
Used in function:  modifyProfile2, setPassword2, secretAnswer2, resetPassword

Variables passed to hook function:  old username, new username, password
Variables expected from hook function: None

Usage:  This hook is started only when a username or password is changed in SMF.

Example of use:  A user changes his password, so the password also needs to change in the integrated system.

[Orstio]

Used in file:  Subs-Members.php
Used in function:  deleteMembers

Variables passed to hook function:  user's ID_MEMBER (int)
Variables expected from hook function: None

Usage:  This hook is started just before a user is deleted from SMF.

Example of use:  A user has deleted his account, or the admin has deleted a user's account, and the account needs to be deleted in the integrated system as well.

[Orstio]

Used in file:  Subs-Members.php
Used in function:  registerMember

Variables passed to hook function:  $regOptions (array), $theme_vars (array)
Variables expected from hook function: None

Usage:  This hook is started just before a user is entered into SMF.  It is one of the more powerful integration hooks, passing all necessary variables in an array for use in the integrated system.

The $regOptions array by default will contain the following keys:

memberName
emailAddress
passwd (SHA1 hash)
passwordSalt
posts
dateRegistered
memberIP
memberIP2
validation_code
realName
personalText
pm_email_notify
ID_THEME
ID_POST_GROUP

It is important to note that all text values will already be enclosed in single quotes for ease of use in queries.  More fields are available, and more are added with the addition of mods like the Custom Profile Fields mod.

Example of use:  A user has registered in SMF, or an admin has created a user in the SMF admin panel, and the user needs to be created in the integrated system as well.

[Orstio]

Used in file:  Subs-Post.php
Used in function:  sendmail

Variables passed to hook function:  $subject, $message, $headers
Variables expected from hook function: true/false

Usage:  This hook is started just before the output of the email is modified for sending.  The message body is still plain text at this point.

Example of use:  The forum is wrapped in a CMS, so all of the URLs in outgoing emails need to be rewritten to point to the CMS.

[Orstio]

Used in file:  Subs-Post.php
Used in function:  sendpm

Variables passed to hook function:  $recipients, $from['username'], $subject, $message
Variables expected from hook function: None

Usage:  This hook is started just before an SMF Personal Message is sent.  It passes an array of recipients, the username of the sender, the subject, and the message body.

Example of use:  A user sends a PM, and that PM should appear in the integrated system as well as SMF's PM system.

[Orstio]

Used in file:  Subs.php
Used in function:  updateMemberData

Variables passed to hook function:  $memberNames (array), $var (string), $data (string)
Variables expected from hook function: None

Usage:  This hook is started just before any changes are made to users profiles.  It is started when an admin is changing multiple users in the admin panel, and also when a user is changing his own profile.

The $var array is similar to the $regOptions array in the integrate_register hook.  It contains all of the key names for the fields to be changed.  The $data array will contain the associated values for those keys.
 
Example of use:  A user changes his profile information, and that information needs to be passed to the integrated system.

[Orstio]

Used in file:  Subs.php
Used in function:  redirectexit

Variables passed to hook function:  $setLocation, $refresh
Variables expected from hook function: None

Usage:  This hook is started just before SMF redirects after a form submission.  To avoid resubmission of form data, SMF uses its own redirect system.  The $setLocation variable will be the URL to which to redirect, and the $refresh variable is a boolean determining whether a page refresh should be done after loading.
 
Example of use:  Similarly to the integrate_outgoing_email function above, this can be used to rewrite redirection URLs back to a wrapped CMS page.

[Orstio]

Used in file:  Subs.php
Used in function:  obExit

Variables passed to hook function:  $do_footer && !WIRELESS (boolean)
Variables expected from hook function: None

Usage:  This hook is started just before SMF exits.  This hook is extremely important for true bridges, because in certain circumstances, the forum can becomes unwrapped from the integrated context without this hook.  It will execute whatever code is in the hook function before exiting PHP.
 
Example of use:  SMF is wrapped in a CMS, and the CMS needs to finish off its execution before exit.