The UCS can be found here. A converter for BlazeBoard can be found here.
If you have any question or if you need help post here or send me a pm.
Ludovic 'Ashe' Arnaud
_____________
A converter can be broken down in three parts:
- Converter infos
- Translation schema
- Functions
It is composed of 3 arrays: $converter_infos, $tables, $config_schema.
$converter_infos
Code: Select all
$converter_infos = array(
'forum_name' => 'XMB Forum 1.8',
'version' => '1.0.1',
'phpbb_version' => '2.0.1',
'table_prefix' => 'xmb_',
'author' => '<a href="mailto:[email protected]">Ashe</a>'
);
version is the version of the converter,
phpbb_version is the version of phpBB it has been written for,
table_prefix (optional) is the default table prefix, it will be used if the user does not know if his/her forum uses one.
author is the string that will be echo'ed in the Author column. You can leave your email or your website address if you want to.
pre_message (optional) contains a message that will be displayed before the conversion actually begins. Then the user has the choice to continue and convert or to return to the Converters panel.
$tables
Code: Select all
$tables = array(
'announcements',
'banned',
'category',
...snipped...
'smilies',
'thread'
);
$config_schema
Holds a small conversion table for config settings. Among all recent PHP forums, config tables are stored in three different ways:
- file-based, where everything is stored in a PHP array. Example: the config file is named config.php, it is stored in the config/ folder of the forum and the array is $config.
table_format => 'file',
filename => 'config/config.php',
array_name => 'config' - in a single-row table, having one field per setting (like phpBB 1.x). In this example the table is named [table_prefix]settings, like xmb_settings.
table_format => 'fixed',
table_name => 'settings' - in a table, with only two fields (config_name, config_value) and one row per setting. (like phpBB 2.x). In this example, the table is identical to phpBB2's config table phpbb_config:
table_format => array('config_name'=>'config_value'),
table_name => 'config'
Code: Select all
$config_schema = array(
'table_name' => 'config',
'table_format' => array('config_name' => 'config_value'),
'settings' => array(
'board_disable' => 'not(board_enabled)',
'hot_threshold' => 'hottopic',
'topics_per_page' => 'topicsperpage'
)
);
Translation schema
The core of your converter. It's an array that must be called $converter. Here are all the fields you can use:
- execute_first (string) (optional)
PHP code that will be eval'ued at the beggining of the conversion. - query_first (string|array) (optional)
query_first can either be a string or an array of strings. It holds all the SQL queries you want to execute at the beggining of the conversion. They are processed after execute_first. - execute_last (string) (optional)
PHP code that will be eval'ued at the end of the conversion. - query_last (string|array) (optional)
Identical to query_first, the queries will be executed after execute_last. - test_file (string) (optional - required if you use any of the file management functions)
Holds the filename of any of the forum file, it will be used to make sure the relative filepath is correct. Please do not use files like 'index.php' that are not specific enough. For phpBB2 you would use 'admin/pagestart.php'. - avatars_path (string) (optional - required if you use import_avatar() or import_avatar_gallery())
Path to the avatars directory. Relative to the base directory of the forum you're converting from, if the dir is /mysite/vbulletin/avatars_storage/ then 'avatars_path' will be 'avatars_storage/'. If the target directory does not exist it will be created, if it can't be the user will be prompted to do so. - ranks_path (string) (optional - required if you use import_rank())
Identical to avatar_path but for ranks. - smilies_path (string) (optional - required if you use import_smilie())
Identical to avatar_path but for smilies. - schema (array) (required)
The biggest part, translation tables.
$converter['schema'] is an array where each element describes how a table must be imported. Example:
Code: Select all
array(
'target' => CATEGORIES_TABLE,
'query_first' => 'DELETE FROM ' . CATEGORIES_TABLE,
array('cat_id', 'category.CID', ''),
array('cat_title', 'category.category', 'stripslashes'),
array('cat_order', 'category.displayorder', '')
)
- target (string) (required)
The name of the target table. Always use constants for them. - execute_first (string) (optional)
Identical to the higher level execute_first. There is no execute_last. - query_first (string|array) (optional)
Identical to the higher level query_first. Since target tables aren't automatically emptied, most of the time you will use this field to do so. There is no query_last. - Array elements with no key
Each of those will be an array with three fields. The first one holds the name of the target field, the second one is the names of source table and source field (more on this later in this document). The third one is the function to use. In the example, the field cat_id of table CATEGORIES_TABLE will be field with stripslash'ed result of field category, from the source table [table_prefix]category. Note that you never have to mention the table prefix of any table, they are automagically added. - left_join (string|array) (optional)
Formats:
tablename LEFT JOIN joined_table ON <clause>
tablename LEFT JOIN joined_table USING (field)
tablename LEFT JOIN joined_table AS alias ON <clause>
You can specify one or several LEFT JOIN clauses. - where (string) (optional)
Ex: 'where' => 'members.userid > 1 OR members.status = "Administrator"'
Standard WHERE clause. - group_by (string) (optional)
Ex: 'group_by' => 'ranks.titlename'
Standard GROUP BY clause. - having (string) (optional)
Standard HAVING clause. Note that only MySQL allows to use HAVING with aliases. - order_by (string) (optional - recommended)
Standard ORDER BY clause. - distinct (boolean) (optional) new
Set 'distinct' to TRUE to make the select query uses DISTINCT.
Each element has three fields: target, source, function.
target is the target database field. (optional)
function the function to apply before values are inserted. (optional)
source is the source of data. It can use several formats, here is a quick description with the way it will be translated to SQL language:
table.field
SELECT table.field FROM [prefix]table table
table_alias.field (deprecated)
SELECT table_alias.field FROM ? table_alias
table.field AS alias
SELECT table.field AS alias FROM [prefix]table table
table.field AS table_alias.alias
SELECT table_alias.field AS alias FROM [prefix]table table_alias
table.field AS table_alias.field
SELECT table_alias.field FROM [prefix]table table_alias
The second form is deprecated, but can be used in conjunction with a LEFT JOIN using an alias, otherwise the script has no way to know what table is this alias for. Note that you can also specify an abolute value instead of a fieldname and that value will be treated like if it was returned from the database.
Basic rules: logic
For each element:
- If target isn't empty, it will be filled with the result of the row.
- If source is a fieldname, it will be queried.
- If function isn't empty, the value of source will be passed.
Functions
There are three types of functions:
- global functions, that are used for the script itself or can be used in a converter. They can be found in functions_convert.php.
- general functions to use directly in translation tables. For example, inc() will increment the passed var then return it. str_to_userlevel will translate english levels (Administrator, Moderator, etc...) into their numeric equivalence (ADMIN, MOD, etc...). They can be found in functions_convert.php.
- specific functions. Functions specific to a converter, they are stored at the end of the converter file. Always prefix them with the converter tag or shortname to avoid conflicts.
- Know phpBB coding standards by heart
- Never assume that the entire table will be processed at once, it can be stopped at any time.
- Results of the current row are available through $row. Remember to declare it with global at the beggining of the function.
- If, for any reason you don't want the current row to be inserted set $sql_flag to FALSE. Remember to declare it with global at the beggining of the function.
- ...more tips will come