Pitchoune
10/07/2005, 15h54
Les documents de cette partie sont fait pour guider les personnes qui écrivent du code pour modifier vBulletin.
Couleurs clés des exemples de code :
$code = red_code($var); Ne pas coder de cette façon
$code = normal_code($var); Coder plutôt comme cela
$_GET / $_POST / $_REQUEST
Les variables $_GET et $_POST doivent être lancés à travers la fonction globalize() afin d'assurer la suppression des guillemets autour des variables avant d'être utilisées, avec l'exception de $_REQUEST['do'] et $_POST['do'] qui sont utilisées en tant que variable de contrôle pour décider quels branches d'un script qui doit être exécuté. N'utilisez pas les variables $_GET / $_POST / $_REQUEST etc... dans les templates.
$DB_site->query("
UPDATE " . TABLE_PREFIX . "table SET
field_one = '" . addslashes(trim($_POST['field_one'])) . "',
field_two = '" . addslashes(htmlspecialchars_uni(trim($_POST['field_two']))) . "'
WHERE key_field = " . intval($_POST['key_field']) . "
");
globalize($_POST, array(
'field_one' => STR,
'field_two' => STR_NOHTML,
'key_find' => INT
));
$DB_site->query("
UPDATE " . TABLE_PREFIX . "table SET
field_one = '" . addslashes($field_one) . "',
field_two = '" . addslashes($field_two) . "'
WHERE key_field = " . $key_field . "
");
Accolades
Les accolades devraient être placés sur une nouvelle ligne à chaque fois.
if ($condition_one)
{
// do something
}
else if ($condition_two)
{
// do something else
}
else
{
// don't do anything
}
Utilisez toujours les accolades, même pour les boucles et embranchements qui contiennent qu'une seule ligne de commande.
if ($condition_one)
// do something
else
if ($condition_two)
// do something else
else
// don't do anything
if ($condition_one)
{
// do something
}
else
{
if ($condition_two)
{
// do something else
}
else
{
// don't do anything
}
}
AND / and / && OR / or / || etc...
Utilisez « AND » au lieu de « and » ou « && », et « OR » au lieu de « or » ou « || ».
if ($var1 && $var2 || $var3)
if ($var1 and $var2 or $var3)
if ($var1 AND $var2 OR $var3)
Mettez en majuscules « AS » dans la fonction foreach.
foreach($array AS $key => $val)
{
// do something
}
Boucles et embranchements
Les commandes des boucles et des embranchements (incluant la fonction foreach) doivent être séparé d'un espace avant d'ouvrir les parenthèses.
for ($i =0; $i < 10; $i++)
{
// do something
}
while ($result = $DB_site->fetch_array($results))
{
// do something
}
if ($condition != 'something')
{
// do something
}
foreach ($array AS $key => $val)
{
// do something
}
« else if » est préconisé face à « elseif ».
if ($condition)
{
// do something
}
else if ($condition_two)
{
// do something else
}
Commenter le code
Utilisez le type de commentaire // pour une ligne ou quelques courtes lignes de descrption, ou la syntaxe /* .... */ pour un grand bloc.
// Ceci est une simple ligne de commentaire
// Ceci est un court descriptif qui vous
// indique comment commenter
/*
Ceci est un
long commentaire
qui peut prendre
plusieurs lignes...
*/
Les commentaires doivent précéder le code qu'ils décrivent, comme suit :
$var = 0; // initialize $var
if ($var) // check $var
// initialize $var
$var = 0;
// check $var
if ($var)
Quand vous commentez des branches ou des embranchements, il est accepté de mettre du commentaire entre les accolades.
if ($var)
{
// $var is true so do the following code
echo $var;
}
Séparez les branches « do » et les gros blocs majeurs du code avec le commentaire en exemple ci-dessous. Il est suggéré de copier cette ligne et de l'insérer automatiquement dans votre éditeur PHP. Si vous souhaitez indiquer ce que fait la branche « do », ajoutez un commentaire juste après la ligne de commentaire.
require_once(./global.php);
// ################################################## ###########################
if (empty($_REQUEST['do']))
{
$_REQUEST['do'] = 'modify';
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'edit')
{
// do edit code
}
// ################################################## ###########################
// lists items in a table
if ($_REQUEST['do'] == 'modify')
{
// do modify code
}
Préfixez lesdéfinitions des fonctions PHP avec la ligne de commentaire suivante. Encore une fois, vous devriez inclure cette ligne automatiquement dans votre éditeur PHP.
// ###################### Start is_something ######################
function is_something()
{
return iif($var, true, false);
}
// ###################### Start fetch_uppercase ######################
function fetch_uppercase($var)
{
return strtoupper($var);
}
Comparaison de variables, etc...
Les standards suivants doivent être suivies :
if (empty($array)) // true si $array est vide
if ($string == '') // true si $string a aucun contenu
if ($integer) // true si $integer n'est pas 0
if (!$integer) // true si $integer est 0
if ($boolean) // true si $boolean est true
if (!$boolean) // true si $boolean est false
Si le type de donnée est important, utilisez === et !==.
if ($boolean === true) // true si $boolean est 'true', false si $boolean est un integer true
if ($integer !== 0) // true si integer n'est pas 0, false si $integer est 'true'
Notez ce qui suit :
$integer = 0;
if ($integer = '') // retournera true
$string = '';
if ($string == '0') // retournera true
$string = '0';
if ($string == '') // retournera true
Fonction retournant des valeurs booléennes
À moins qu'il n'y ait une bonne raison d'utiliser 1/0, à cause de la possibilité d'obtenir la valeur de retour 2, utilisez true/false comme valeurs de retour pour des fonctions.
function is_three($var)
{
if ($var == 3)
{
return 1;
}
else
{
return 0;
}
}
function is_three($var)
{
if ($var == 3)
{
return true;
}
else
{
return false;
}
}
Utilisez true/false au lieu de TRUE/FALSE. Réservez les versions en majuscules pour les constantes personnalisées.
if ($var === TRUE)
if ($var === true)
Guillemets et chaînes
Les chaînes doivent être entre simple guillemets (') si elles contiennent aucune variable ou de caractère de contrôle, sinon utilisez les guillets normaux (").
$flat_string = 'Salut, ceci est une chaîne.';
$dynamic_one = "Salut,\n ceci est une chaîne.";
$dynamic_two = "Salut $username,\n ceci est une chaîne.";
Choisir entre les ' et les " est selon ce que vous souhaitez faire, dépendant des circonstances.
$string_one = "L'heure actuelle est $timenow et la date est $datenow";
$string_two = 'L\'heure actuelle est ' . $timenow . ' et la date est ' . $datenow . '.';
Les requêtes SQL doivent toujours être ainsi :
$results = $DB_site->query("SELECT field FROM " . TABLE_PREFIX . "table AS table");
Les variables ne doivent pas entourées de guillemets si cela n'est pas nécessaire.
$var = "$x";
$result = strtoupper("$string");
$var = $x;
$result = strtoupper($string);
$string = fetch_something("something$var");
Les appels eval() doivent avoir des guillemets simples (') si possible, afin d'éviter d'implanter des caractères inutiles.
eval("\$template = \"" . fetch_template('template') . "\";");
eval('$template = "' . fetch_template('template') . '";');
Guillemets et les tableaux de valeurs
Les clés de tableau doivent être entourées de guillemets si ce sont des chaînes ou des variables, même si vous savez que la variable évalue un entier. Les types de guillemets utilisés doivent suivre ce qui est indiqué dans le didacticiel « Guillemets et chaînes ». Notez que $var = array[$key]; causera une parse error si $key n'est pas entre guillemets et si c'est une valeur négative, et causera une notice si $key est une chaîne ou n'est pas entre guillemets.
$a = $userinfo[12];
$b = $userinfo['username'];
$c = $userinfo["$field"];
Des clefs de tableau composées doivent citer la variable la plus éloignée.
$a = $userinfo["$var[12]"];
$b = $userinfo["$var[username]"];
$c = $userinfo["$var[field]"];
Les tableaux composés de chaînes entourés de guillemets doivent évités d'être si possible en dehors de la chaîne avec le point opérateur, bien que ceci soit absolument inévitable, la syntaxe {...} peut être utilisée.
$a = "Salut, mon nom est $userinfo[12], comment allez-vous ?";
$b = "Salut, mon nom est $userinfo[username], comment allez-vous ?";
$c = "Salut, mon nom est $userinfo[$field], comment allez-vous ?";
$d = 'Salut, mon nom est ' . $userinfo["$var[field]"] . ', comment allez-vous ?';
$e = "Salut, mon nom est {$userinfo[$var[username]]}, comment allez-vous ?";
Nommer les embranchements « do »
La plupart des pages vBulletin contient des embranchements « do ». Les nominations ci-dessous sont à suivre.
if (empty($_REQUEST['do']))
{
// set default branch for this script
$_REQUEST['do'] = 'modify';
}
// ################################################## ###########################
if ($_POST['do'] == 'kill')
{
// 'kill'
// run code to remove item in database
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'delete')
{
// 'delete'
// display delete confirmation message
}
// ################################################## ###########################
if ($_POST['do'] == 'insert')
{
// 'insert'
// run code to insert new item into database
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'add')
{
// 'add'
// display form to add new item
}
// ################################################## ###########################
if ($_POST['do'] == 'update')
{
// 'update'
// run code to update item in database
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'edit')
{
// 'edit'
// display form to edit item
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'modify')
{
// 'modify'
// show default branch for this script
}
Autant que possible, gardez les embranchements dans l'ordre listée ci-dessus, avec 'modify' (l'action par défaut) le plus en bas du script.
Si un script contient des embranchements pour plus de edit/add/delete qu'il puisse exister (comme template.php qui modifie les styles et les templates), vous devez placer un suffixe pour les noms des embranchements kill/delete/insert/add/update/edit avec le type d'objet.
if ($_REQUEST['do'] == 'edittemplate')
{
// show form to edit a template
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'editstyle')
{
// show form to edit a style
}
Si la fonctionnalité « do » d'un embranchement ne correspond pas à edit, update, add, insert, delete ou kill, donnez-lui un nom qui permet de récapituler l'embranchement.
if ($_REQUEST['do'] == 'rebuildstylecache')
{
// rebuild style cache
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'updatetemplateparentlists')
{
// update template parent lists
}
Gardez les groupes des embranchements applicables à un type d'objet simple dans le script.
// if (empty($_REQUEST['do']))
// if ($_REQUEST['do'] == 'rebuildstylecache')
// if ($_POST['do'] == 'killstyle')
// if ($_REQUEST['do'] == 'deletestyle')
// if ($_POST['do'] == 'insertstyle')
// if ($_REQUEST['do'] == 'addstyle')
// if ($_POST['do'] == 'updatestyle')
// if ($_REQUEST['do'] == 'editstyle')
// if ($_REQUEST['do'] == 'updatetemplateparentlists')
// if ($_POST['do'] == 'killtemplate')
// if ($_REQUEST['do'] == 'deletetemplate')
// if ($_POST['do'] == 'inserttemplate')
// if ($_REQUEST['do'] == 'addtemplate')
// if ($_POST['do'] == 'updatetemplate')
// if ($_REQUEST['do'] == 'edittemplate')
// if ($_REQUEST['do'] == 'modify')
Nommer les fonctions
Les noms des fonctions personnalisées doivent (autant que possible) décrire ce qu'ils font, pour qu'une prsonne qui lise le code puisse savoir comment l'utiliser et puisse savoir sa fonction par son nom.
Les noms des fonctions personnalisées doivent écrit en minuscules et doit utiliser les sous-tirets ( _ ) pour séparer les mots.
$var2 = issomething($var1);
$var2 = isSomething($var1);
$var2 = is_something($var1);
Les noms des fonctions personnalisées doivent suivre les modèles suivants :
print_ Fonctions qui envoie directement le code dans le navigateur ou dans des variables type echo ou print.
print_input_row
print_standard_error
print_cp_header
construct_
Fonctions qui retournent des variables HTML pour un affichage ultérieur.
construct_edit_toolbar
construct_forum_jump
is_contains_
Fonctions qui retournent true/false basé sur des conditions.
is_valid_email
is_wysiwyg_compatible
contains_bbcode_img_tags
can_
Fonctions qui retournent des true/false basés sur des permissions.
can_moderate
can_administer
can_announce
verify_
Fonctions qui vérifie les conditions et qui affiche un message d'erreur si une condition n'est pas acceptée.
verify_ip_ban
verify_post_errors
verify_word_allowed
convert_
Fonctions qui convertit une variable d'entrée d'un format de donnée à un autre format de donnée.
convert_kb_to_mb
convert_html_to_bbcode
convert_bits_to_array
cache_
Fonctions qui lit les données de la base de données (habituellement) et crée un cache de variables PHP pour alléger la charge SQL.
cache_templates
cache_forums
cache_birthdays
fetch_
Fonctions qui retourne des tableaux / chaînes / entiers etc... Si le type de donnée à être retourné n'est pas explicite dans le nom de la fonction (comme fetch_userinfo ou fetch_template), spécifiez le type de donnée dans le nom de la fonction, comme fetch_template_update_sql, fetch_replaced_session_url, fetch_reminders_array, etc...
fetch_template
fetch_user_search_sql
fetch_user_location_array
process_
Fonctions qui exécute des actions sur un tableau de valeurs afin de le préparer pour une référence plus tard.
process_thread_array
process_post_preview
process_online_location
build_
Fonctions qui sauvegarde les données dans la base de données pour une recherche plus tard, comme mettre en cache les anniversaires dans la table datastore, régénérer la table style, etc...
build_bbcode_cache
build_new_post
build_attachment
delete_
Fonctions qui supprime quelque chose de la base de données.
delete_thread
delete_post_index
delete_user_pms
undelete_
Fonctions inverse de la suppression.
undelete_thread
undelete_post
import_
Fonctions du système d'importation qui prend une rangée de donnée et qui l'insère en tant que message/discussion/utilisateur (etc...) dans la base de données.
import_thread
import_post
import_user
sanitize_
Fonctions qui exécutent des actions sur les paramètres d'entrée pour les garder en mémoire pour l'étape suivante, comme retirer les caractères interdits, vérifier si une date est valide, qu'une valeur $perpage a un sens, etc...
sanitize_perpage
sanitize_url
sanitize_reminder_date
parse_
Fonctions qui intialise le formatage des balises BB en quelque sorte.
parse_bbcode
parse_usernote_bbcode
parse_pm_bbcode
handle_
Fonctions qui sont appelées par le formateur de balises BB pour échanger avec un type particulier de balise BB.
handle_bbcode_img
handle_bbcode_list
handle_bbcode_parameter
file_
Fonctions qui crée des échanges directement dans le système de fichiers.
file_read
file_download
file_append
log_
Fonctions qui touche aux journaux de vBulletin.
log_admin_action
log_vbulletin_error
log_upgrade_step
exec_
Fonctions qui actuellement exécute une action au lieu de retourner quelque chose.
exec_shutdown
exec_queries
exec_cron
sort_
Fonctions qui trie les données.
sort_search_items
sort_threaded_posts
strip_
Fonctions qui trie les éléments des chaînes.
strip_bbcode
strip_blank_ascii
strip_empty_bbcode
xml_
Fonctions qui lit ou sort du XML.
xml_import_style
xml_parse_language_otag
xml_escade_cdata
vb_ ou vb
Fonctions qui remplace des fonctions PHP par des remplacements vBulletin dessinés pour étendre les fonctionnalités ou pour modifier la fonction originale. Si la fonction originale contient des sous-tirets ( _ ), la fonction sera préfixée par « vb_ » au lieu de « vb ».
vbmail
vb_number_format
vbsetcookie
js_
Fonctions Javascript définis dans le code PHP (plutôt que d'être dans des fichiers .js).
js_dots
js_confirm_clear_db
js_forum_jump
Retrait
Toujours utiliser une seule tabulation pour chaque retrait.
function construct_something($var)
{
global $vboptions;
if ($vboptions['somevar'])
{
if ($var == 'something')
{
return true;
}
else
{
return false;
}
}
else
{
return true;
}
}
Syntaxe des requêtes SQL
Toujours mettre les requêtes entre des guillemets (").
$DB_site->query('SELECT field FROM ' . TABLE_PREFIX . 'table ORDER BY field');
$DB_site->query("SELECT field FROM " . TABLE_PREFIX . "table ORDER BY field");
Les appels dans la fonction SQL ne doivent pas contenir d'espaces.
$DB_site->query("SELECT COUNT(*) AS records, SUM(field_one) AS total FROM " . TABLE_PREFIX . "table");
Si la chaîne de la requête est trop longue et qu'il est préférable de l'écrire en plusieurs lignes, faites ceci et mettez le mot-clé de cause au début de la ligne de la façon suivante : double guillemets ("), retour à la ligne, retrait, [chaîne de la requête], retour à la ligne, retrait, double guillemets (").
$results = $DB_site->query("SELECT field_one, field_two field_three,
IF(field_four = 'Yes', 1, 0) AS field_four,
FROM " . TABLE_PREFIX . "table_one AS table_one
LEFT_JOIN " . TABLE_PREFIX . "table_two AS table_two USING(field_one)
WHERE table_one.field_two IN('bla bla bla', 'moo moo moo')
ORDER BY table_one.field.one DESC
LIMIT 5, 10");
$results = $DB_site->query("
SELECT field_one, field_two field_three,
IF(field_four = 'Yes', 1, 0) AS field_four,
FROM " . TABLE_PREFIX . "table_one AS table_one
LEFT_JOIN " . TABLE_PREFIX . "table_two AS table_two USING(field_one)
WHERE table_one.field_two IN('bla bla bla', 'moo moo moo')
ORDER BY table_one.field.one DESC
LIMIT 5, 10
");
Les clauses « AND » additionnelles dans la clause WHERE doivent être en retrait si il y en a plusieurs.
$results = $DB_site->query("
SELECT field_one, field_two
FROM " . TABLE_PREFIX . "table AS table
WHERE field_one IN(3,4,5)
AND field_two <> ''
AND field_three = 'something'
ORDER BY field_one
");
Ne pas mettre entre guillemets des valeurs numériques dans le requêtes SQL, utilisez intval() ou $var += 0; pour vous assurer que la variable est sûre.
$DB_site->query_first("SELECT something FROM table WHERE tableid = '$numericvar'");
$DB_site->query_first("SELECT something FROM table WHERE tableid = '" . intval(numericvar) . "'");
$DB_site->query_first("SELECT something FROM table WHERE tableid = " . intval(numericvar));
$numericvar = intval($numericvar);
$DB_site->query_first("SELECT something FROM table WHERE tableid = $numericvar");
Ne pas spécifier de longueur pour les champs numériques à moins de spécifier « UNSIGNED ZEROFILL ».
$DB_site->query("
ALTER TABLE " . TABLE_PREFIX . "table
ADD field_four SMALLINT(5) UNSIGNED NOT NULL,
ADD field_five INT(10) UNSIGNED NOT NULL
");
$DB_site->query("
ALTER TABLE " . TABLE_PREFIX . "table
ADD field_four SMALLINT UNSIGNED NOT NULL,
ADD field_five INT UNSIGNED NOT NULL
");
Ne pas utiliser le mot-clé « AFTER » dans une requête « ALTER ». Certains serveurs ont des soucis avec le mot-clé « AFTER », il est préférable de ne pas l'utiliser.
$DB_site->query("
ALTER TABLE " . TABLE_PREFIX . "table
ADD field_six INT UNSIGNED NOT NULL AFTER field_five
");
$DB_site->query("
ALTER TABLE " . TABLE_PREFIX . "table
ADD field_six INT UNSIGNED NOT NULL
");
Les formats des requêtes INSERT / REPLACE doit être celui-ci :
$DB_site->query("
INSERT INTO " . TABLE_PREFIX . "table
(field_one, field_two, field_three)
VALUES
(1, 2, 'moo'),
(1, 2, 'baa'),
(1, 5, 'quack')
");
Listez toujours les noms des champs dans les requêtes INSERT / REPLACE. Vous ne mettez jamais à jour tous les champs d'un coup.
$DB_site->query("
INSERT INTO " . TABLE_PREFIX . "table
VALUES
(1, 'one', 'some text')
");
$DB_site->query("
INSERT INTO " . TABLE_PREFIX . "table
(field_one, field_two, field_three)
VALUES
(1, 'one', 'some text')
");
Si un champ dans une requête INSERT a la propriété AUTO_INCREMENT, ne pas l'inclure dans la requête.
$DB_site->query("
INSERT INTO " . TABLE_PREFIX . "table
(auto_increment_field, field_two)
VALUES
(NULL, 'texty bits')
");
$DB_site->query("
INSERT INTO " . TABLE_PREFIX . "table
(field_two)
VALUES
('texty bits')
");
Utilisation des espaces
Les opérateurs doivent toujours être entourés par des espaces à l'exception de ++ et --.
$a = 1;
$b += $a;
$c = $a . $b;
$d = $b . 'something' . $c;
$e = $d * $b;
$f = $e / $a;
$g = ($f + $e) * $b;
$h++;
$i--;
Les appels de fonction et les définitions ne doivent pas avoir d'espaces avant la parenthèse.
$x = htmlspecialchars($y);
$item = $DB_site->fetch_array($items);
Les arguments de fonction doivent avoir un espace après chaque virgule.
$x = fetch_something($a, $b, $c);
$i = construct_something(strtoupper('something') . ' ' . substr($var, 0, $b));
Les espaces non nécessaires dans les parenthèses ne doivent pas être utilisés.
$var = addslashes( $var );
$str = fetch_something( strlen( $var ), strpos( $x, $y ) );
$x = construct_x(substr($string, 0, strlen($bla)) . '/' . ucfirst($string));
if ($x == 1 AND ($y == 2 OR $z == 3) AND ($a = fetch_x($x, $y) OR $a == $bla))
Couleurs clés des exemples de code :
$code = red_code($var); Ne pas coder de cette façon
$code = normal_code($var); Coder plutôt comme cela
$_GET / $_POST / $_REQUEST
Les variables $_GET et $_POST doivent être lancés à travers la fonction globalize() afin d'assurer la suppression des guillemets autour des variables avant d'être utilisées, avec l'exception de $_REQUEST['do'] et $_POST['do'] qui sont utilisées en tant que variable de contrôle pour décider quels branches d'un script qui doit être exécuté. N'utilisez pas les variables $_GET / $_POST / $_REQUEST etc... dans les templates.
$DB_site->query("
UPDATE " . TABLE_PREFIX . "table SET
field_one = '" . addslashes(trim($_POST['field_one'])) . "',
field_two = '" . addslashes(htmlspecialchars_uni(trim($_POST['field_two']))) . "'
WHERE key_field = " . intval($_POST['key_field']) . "
");
globalize($_POST, array(
'field_one' => STR,
'field_two' => STR_NOHTML,
'key_find' => INT
));
$DB_site->query("
UPDATE " . TABLE_PREFIX . "table SET
field_one = '" . addslashes($field_one) . "',
field_two = '" . addslashes($field_two) . "'
WHERE key_field = " . $key_field . "
");
Accolades
Les accolades devraient être placés sur une nouvelle ligne à chaque fois.
if ($condition_one)
{
// do something
}
else if ($condition_two)
{
// do something else
}
else
{
// don't do anything
}
Utilisez toujours les accolades, même pour les boucles et embranchements qui contiennent qu'une seule ligne de commande.
if ($condition_one)
// do something
else
if ($condition_two)
// do something else
else
// don't do anything
if ($condition_one)
{
// do something
}
else
{
if ($condition_two)
{
// do something else
}
else
{
// don't do anything
}
}
AND / and / && OR / or / || etc...
Utilisez « AND » au lieu de « and » ou « && », et « OR » au lieu de « or » ou « || ».
if ($var1 && $var2 || $var3)
if ($var1 and $var2 or $var3)
if ($var1 AND $var2 OR $var3)
Mettez en majuscules « AS » dans la fonction foreach.
foreach($array AS $key => $val)
{
// do something
}
Boucles et embranchements
Les commandes des boucles et des embranchements (incluant la fonction foreach) doivent être séparé d'un espace avant d'ouvrir les parenthèses.
for ($i =0; $i < 10; $i++)
{
// do something
}
while ($result = $DB_site->fetch_array($results))
{
// do something
}
if ($condition != 'something')
{
// do something
}
foreach ($array AS $key => $val)
{
// do something
}
« else if » est préconisé face à « elseif ».
if ($condition)
{
// do something
}
else if ($condition_two)
{
// do something else
}
Commenter le code
Utilisez le type de commentaire // pour une ligne ou quelques courtes lignes de descrption, ou la syntaxe /* .... */ pour un grand bloc.
// Ceci est une simple ligne de commentaire
// Ceci est un court descriptif qui vous
// indique comment commenter
/*
Ceci est un
long commentaire
qui peut prendre
plusieurs lignes...
*/
Les commentaires doivent précéder le code qu'ils décrivent, comme suit :
$var = 0; // initialize $var
if ($var) // check $var
// initialize $var
$var = 0;
// check $var
if ($var)
Quand vous commentez des branches ou des embranchements, il est accepté de mettre du commentaire entre les accolades.
if ($var)
{
// $var is true so do the following code
echo $var;
}
Séparez les branches « do » et les gros blocs majeurs du code avec le commentaire en exemple ci-dessous. Il est suggéré de copier cette ligne et de l'insérer automatiquement dans votre éditeur PHP. Si vous souhaitez indiquer ce que fait la branche « do », ajoutez un commentaire juste après la ligne de commentaire.
require_once(./global.php);
// ################################################## ###########################
if (empty($_REQUEST['do']))
{
$_REQUEST['do'] = 'modify';
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'edit')
{
// do edit code
}
// ################################################## ###########################
// lists items in a table
if ($_REQUEST['do'] == 'modify')
{
// do modify code
}
Préfixez lesdéfinitions des fonctions PHP avec la ligne de commentaire suivante. Encore une fois, vous devriez inclure cette ligne automatiquement dans votre éditeur PHP.
// ###################### Start is_something ######################
function is_something()
{
return iif($var, true, false);
}
// ###################### Start fetch_uppercase ######################
function fetch_uppercase($var)
{
return strtoupper($var);
}
Comparaison de variables, etc...
Les standards suivants doivent être suivies :
if (empty($array)) // true si $array est vide
if ($string == '') // true si $string a aucun contenu
if ($integer) // true si $integer n'est pas 0
if (!$integer) // true si $integer est 0
if ($boolean) // true si $boolean est true
if (!$boolean) // true si $boolean est false
Si le type de donnée est important, utilisez === et !==.
if ($boolean === true) // true si $boolean est 'true', false si $boolean est un integer true
if ($integer !== 0) // true si integer n'est pas 0, false si $integer est 'true'
Notez ce qui suit :
$integer = 0;
if ($integer = '') // retournera true
$string = '';
if ($string == '0') // retournera true
$string = '0';
if ($string == '') // retournera true
Fonction retournant des valeurs booléennes
À moins qu'il n'y ait une bonne raison d'utiliser 1/0, à cause de la possibilité d'obtenir la valeur de retour 2, utilisez true/false comme valeurs de retour pour des fonctions.
function is_three($var)
{
if ($var == 3)
{
return 1;
}
else
{
return 0;
}
}
function is_three($var)
{
if ($var == 3)
{
return true;
}
else
{
return false;
}
}
Utilisez true/false au lieu de TRUE/FALSE. Réservez les versions en majuscules pour les constantes personnalisées.
if ($var === TRUE)
if ($var === true)
Guillemets et chaînes
Les chaînes doivent être entre simple guillemets (') si elles contiennent aucune variable ou de caractère de contrôle, sinon utilisez les guillets normaux (").
$flat_string = 'Salut, ceci est une chaîne.';
$dynamic_one = "Salut,\n ceci est une chaîne.";
$dynamic_two = "Salut $username,\n ceci est une chaîne.";
Choisir entre les ' et les " est selon ce que vous souhaitez faire, dépendant des circonstances.
$string_one = "L'heure actuelle est $timenow et la date est $datenow";
$string_two = 'L\'heure actuelle est ' . $timenow . ' et la date est ' . $datenow . '.';
Les requêtes SQL doivent toujours être ainsi :
$results = $DB_site->query("SELECT field FROM " . TABLE_PREFIX . "table AS table");
Les variables ne doivent pas entourées de guillemets si cela n'est pas nécessaire.
$var = "$x";
$result = strtoupper("$string");
$var = $x;
$result = strtoupper($string);
$string = fetch_something("something$var");
Les appels eval() doivent avoir des guillemets simples (') si possible, afin d'éviter d'implanter des caractères inutiles.
eval("\$template = \"" . fetch_template('template') . "\";");
eval('$template = "' . fetch_template('template') . '";');
Guillemets et les tableaux de valeurs
Les clés de tableau doivent être entourées de guillemets si ce sont des chaînes ou des variables, même si vous savez que la variable évalue un entier. Les types de guillemets utilisés doivent suivre ce qui est indiqué dans le didacticiel « Guillemets et chaînes ». Notez que $var = array[$key]; causera une parse error si $key n'est pas entre guillemets et si c'est une valeur négative, et causera une notice si $key est une chaîne ou n'est pas entre guillemets.
$a = $userinfo[12];
$b = $userinfo['username'];
$c = $userinfo["$field"];
Des clefs de tableau composées doivent citer la variable la plus éloignée.
$a = $userinfo["$var[12]"];
$b = $userinfo["$var[username]"];
$c = $userinfo["$var[field]"];
Les tableaux composés de chaînes entourés de guillemets doivent évités d'être si possible en dehors de la chaîne avec le point opérateur, bien que ceci soit absolument inévitable, la syntaxe {...} peut être utilisée.
$a = "Salut, mon nom est $userinfo[12], comment allez-vous ?";
$b = "Salut, mon nom est $userinfo[username], comment allez-vous ?";
$c = "Salut, mon nom est $userinfo[$field], comment allez-vous ?";
$d = 'Salut, mon nom est ' . $userinfo["$var[field]"] . ', comment allez-vous ?';
$e = "Salut, mon nom est {$userinfo[$var[username]]}, comment allez-vous ?";
Nommer les embranchements « do »
La plupart des pages vBulletin contient des embranchements « do ». Les nominations ci-dessous sont à suivre.
if (empty($_REQUEST['do']))
{
// set default branch for this script
$_REQUEST['do'] = 'modify';
}
// ################################################## ###########################
if ($_POST['do'] == 'kill')
{
// 'kill'
// run code to remove item in database
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'delete')
{
// 'delete'
// display delete confirmation message
}
// ################################################## ###########################
if ($_POST['do'] == 'insert')
{
// 'insert'
// run code to insert new item into database
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'add')
{
// 'add'
// display form to add new item
}
// ################################################## ###########################
if ($_POST['do'] == 'update')
{
// 'update'
// run code to update item in database
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'edit')
{
// 'edit'
// display form to edit item
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'modify')
{
// 'modify'
// show default branch for this script
}
Autant que possible, gardez les embranchements dans l'ordre listée ci-dessus, avec 'modify' (l'action par défaut) le plus en bas du script.
Si un script contient des embranchements pour plus de edit/add/delete qu'il puisse exister (comme template.php qui modifie les styles et les templates), vous devez placer un suffixe pour les noms des embranchements kill/delete/insert/add/update/edit avec le type d'objet.
if ($_REQUEST['do'] == 'edittemplate')
{
// show form to edit a template
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'editstyle')
{
// show form to edit a style
}
Si la fonctionnalité « do » d'un embranchement ne correspond pas à edit, update, add, insert, delete ou kill, donnez-lui un nom qui permet de récapituler l'embranchement.
if ($_REQUEST['do'] == 'rebuildstylecache')
{
// rebuild style cache
}
// ################################################## ###########################
if ($_REQUEST['do'] == 'updatetemplateparentlists')
{
// update template parent lists
}
Gardez les groupes des embranchements applicables à un type d'objet simple dans le script.
// if (empty($_REQUEST['do']))
// if ($_REQUEST['do'] == 'rebuildstylecache')
// if ($_POST['do'] == 'killstyle')
// if ($_REQUEST['do'] == 'deletestyle')
// if ($_POST['do'] == 'insertstyle')
// if ($_REQUEST['do'] == 'addstyle')
// if ($_POST['do'] == 'updatestyle')
// if ($_REQUEST['do'] == 'editstyle')
// if ($_REQUEST['do'] == 'updatetemplateparentlists')
// if ($_POST['do'] == 'killtemplate')
// if ($_REQUEST['do'] == 'deletetemplate')
// if ($_POST['do'] == 'inserttemplate')
// if ($_REQUEST['do'] == 'addtemplate')
// if ($_POST['do'] == 'updatetemplate')
// if ($_REQUEST['do'] == 'edittemplate')
// if ($_REQUEST['do'] == 'modify')
Nommer les fonctions
Les noms des fonctions personnalisées doivent (autant que possible) décrire ce qu'ils font, pour qu'une prsonne qui lise le code puisse savoir comment l'utiliser et puisse savoir sa fonction par son nom.
Les noms des fonctions personnalisées doivent écrit en minuscules et doit utiliser les sous-tirets ( _ ) pour séparer les mots.
$var2 = issomething($var1);
$var2 = isSomething($var1);
$var2 = is_something($var1);
Les noms des fonctions personnalisées doivent suivre les modèles suivants :
print_ Fonctions qui envoie directement le code dans le navigateur ou dans des variables type echo ou print.
print_input_row
print_standard_error
print_cp_header
construct_
Fonctions qui retournent des variables HTML pour un affichage ultérieur.
construct_edit_toolbar
construct_forum_jump
is_contains_
Fonctions qui retournent true/false basé sur des conditions.
is_valid_email
is_wysiwyg_compatible
contains_bbcode_img_tags
can_
Fonctions qui retournent des true/false basés sur des permissions.
can_moderate
can_administer
can_announce
verify_
Fonctions qui vérifie les conditions et qui affiche un message d'erreur si une condition n'est pas acceptée.
verify_ip_ban
verify_post_errors
verify_word_allowed
convert_
Fonctions qui convertit une variable d'entrée d'un format de donnée à un autre format de donnée.
convert_kb_to_mb
convert_html_to_bbcode
convert_bits_to_array
cache_
Fonctions qui lit les données de la base de données (habituellement) et crée un cache de variables PHP pour alléger la charge SQL.
cache_templates
cache_forums
cache_birthdays
fetch_
Fonctions qui retourne des tableaux / chaînes / entiers etc... Si le type de donnée à être retourné n'est pas explicite dans le nom de la fonction (comme fetch_userinfo ou fetch_template), spécifiez le type de donnée dans le nom de la fonction, comme fetch_template_update_sql, fetch_replaced_session_url, fetch_reminders_array, etc...
fetch_template
fetch_user_search_sql
fetch_user_location_array
process_
Fonctions qui exécute des actions sur un tableau de valeurs afin de le préparer pour une référence plus tard.
process_thread_array
process_post_preview
process_online_location
build_
Fonctions qui sauvegarde les données dans la base de données pour une recherche plus tard, comme mettre en cache les anniversaires dans la table datastore, régénérer la table style, etc...
build_bbcode_cache
build_new_post
build_attachment
delete_
Fonctions qui supprime quelque chose de la base de données.
delete_thread
delete_post_index
delete_user_pms
undelete_
Fonctions inverse de la suppression.
undelete_thread
undelete_post
import_
Fonctions du système d'importation qui prend une rangée de donnée et qui l'insère en tant que message/discussion/utilisateur (etc...) dans la base de données.
import_thread
import_post
import_user
sanitize_
Fonctions qui exécutent des actions sur les paramètres d'entrée pour les garder en mémoire pour l'étape suivante, comme retirer les caractères interdits, vérifier si une date est valide, qu'une valeur $perpage a un sens, etc...
sanitize_perpage
sanitize_url
sanitize_reminder_date
parse_
Fonctions qui intialise le formatage des balises BB en quelque sorte.
parse_bbcode
parse_usernote_bbcode
parse_pm_bbcode
handle_
Fonctions qui sont appelées par le formateur de balises BB pour échanger avec un type particulier de balise BB.
handle_bbcode_img
handle_bbcode_list
handle_bbcode_parameter
file_
Fonctions qui crée des échanges directement dans le système de fichiers.
file_read
file_download
file_append
log_
Fonctions qui touche aux journaux de vBulletin.
log_admin_action
log_vbulletin_error
log_upgrade_step
exec_
Fonctions qui actuellement exécute une action au lieu de retourner quelque chose.
exec_shutdown
exec_queries
exec_cron
sort_
Fonctions qui trie les données.
sort_search_items
sort_threaded_posts
strip_
Fonctions qui trie les éléments des chaînes.
strip_bbcode
strip_blank_ascii
strip_empty_bbcode
xml_
Fonctions qui lit ou sort du XML.
xml_import_style
xml_parse_language_otag
xml_escade_cdata
vb_ ou vb
Fonctions qui remplace des fonctions PHP par des remplacements vBulletin dessinés pour étendre les fonctionnalités ou pour modifier la fonction originale. Si la fonction originale contient des sous-tirets ( _ ), la fonction sera préfixée par « vb_ » au lieu de « vb ».
vbmail
vb_number_format
vbsetcookie
js_
Fonctions Javascript définis dans le code PHP (plutôt que d'être dans des fichiers .js).
js_dots
js_confirm_clear_db
js_forum_jump
Retrait
Toujours utiliser une seule tabulation pour chaque retrait.
function construct_something($var)
{
global $vboptions;
if ($vboptions['somevar'])
{
if ($var == 'something')
{
return true;
}
else
{
return false;
}
}
else
{
return true;
}
}
Syntaxe des requêtes SQL
Toujours mettre les requêtes entre des guillemets (").
$DB_site->query('SELECT field FROM ' . TABLE_PREFIX . 'table ORDER BY field');
$DB_site->query("SELECT field FROM " . TABLE_PREFIX . "table ORDER BY field");
Les appels dans la fonction SQL ne doivent pas contenir d'espaces.
$DB_site->query("SELECT COUNT(*) AS records, SUM(field_one) AS total FROM " . TABLE_PREFIX . "table");
Si la chaîne de la requête est trop longue et qu'il est préférable de l'écrire en plusieurs lignes, faites ceci et mettez le mot-clé de cause au début de la ligne de la façon suivante : double guillemets ("), retour à la ligne, retrait, [chaîne de la requête], retour à la ligne, retrait, double guillemets (").
$results = $DB_site->query("SELECT field_one, field_two field_three,
IF(field_four = 'Yes', 1, 0) AS field_four,
FROM " . TABLE_PREFIX . "table_one AS table_one
LEFT_JOIN " . TABLE_PREFIX . "table_two AS table_two USING(field_one)
WHERE table_one.field_two IN('bla bla bla', 'moo moo moo')
ORDER BY table_one.field.one DESC
LIMIT 5, 10");
$results = $DB_site->query("
SELECT field_one, field_two field_three,
IF(field_four = 'Yes', 1, 0) AS field_four,
FROM " . TABLE_PREFIX . "table_one AS table_one
LEFT_JOIN " . TABLE_PREFIX . "table_two AS table_two USING(field_one)
WHERE table_one.field_two IN('bla bla bla', 'moo moo moo')
ORDER BY table_one.field.one DESC
LIMIT 5, 10
");
Les clauses « AND » additionnelles dans la clause WHERE doivent être en retrait si il y en a plusieurs.
$results = $DB_site->query("
SELECT field_one, field_two
FROM " . TABLE_PREFIX . "table AS table
WHERE field_one IN(3,4,5)
AND field_two <> ''
AND field_three = 'something'
ORDER BY field_one
");
Ne pas mettre entre guillemets des valeurs numériques dans le requêtes SQL, utilisez intval() ou $var += 0; pour vous assurer que la variable est sûre.
$DB_site->query_first("SELECT something FROM table WHERE tableid = '$numericvar'");
$DB_site->query_first("SELECT something FROM table WHERE tableid = '" . intval(numericvar) . "'");
$DB_site->query_first("SELECT something FROM table WHERE tableid = " . intval(numericvar));
$numericvar = intval($numericvar);
$DB_site->query_first("SELECT something FROM table WHERE tableid = $numericvar");
Ne pas spécifier de longueur pour les champs numériques à moins de spécifier « UNSIGNED ZEROFILL ».
$DB_site->query("
ALTER TABLE " . TABLE_PREFIX . "table
ADD field_four SMALLINT(5) UNSIGNED NOT NULL,
ADD field_five INT(10) UNSIGNED NOT NULL
");
$DB_site->query("
ALTER TABLE " . TABLE_PREFIX . "table
ADD field_four SMALLINT UNSIGNED NOT NULL,
ADD field_five INT UNSIGNED NOT NULL
");
Ne pas utiliser le mot-clé « AFTER » dans une requête « ALTER ». Certains serveurs ont des soucis avec le mot-clé « AFTER », il est préférable de ne pas l'utiliser.
$DB_site->query("
ALTER TABLE " . TABLE_PREFIX . "table
ADD field_six INT UNSIGNED NOT NULL AFTER field_five
");
$DB_site->query("
ALTER TABLE " . TABLE_PREFIX . "table
ADD field_six INT UNSIGNED NOT NULL
");
Les formats des requêtes INSERT / REPLACE doit être celui-ci :
$DB_site->query("
INSERT INTO " . TABLE_PREFIX . "table
(field_one, field_two, field_three)
VALUES
(1, 2, 'moo'),
(1, 2, 'baa'),
(1, 5, 'quack')
");
Listez toujours les noms des champs dans les requêtes INSERT / REPLACE. Vous ne mettez jamais à jour tous les champs d'un coup.
$DB_site->query("
INSERT INTO " . TABLE_PREFIX . "table
VALUES
(1, 'one', 'some text')
");
$DB_site->query("
INSERT INTO " . TABLE_PREFIX . "table
(field_one, field_two, field_three)
VALUES
(1, 'one', 'some text')
");
Si un champ dans une requête INSERT a la propriété AUTO_INCREMENT, ne pas l'inclure dans la requête.
$DB_site->query("
INSERT INTO " . TABLE_PREFIX . "table
(auto_increment_field, field_two)
VALUES
(NULL, 'texty bits')
");
$DB_site->query("
INSERT INTO " . TABLE_PREFIX . "table
(field_two)
VALUES
('texty bits')
");
Utilisation des espaces
Les opérateurs doivent toujours être entourés par des espaces à l'exception de ++ et --.
$a = 1;
$b += $a;
$c = $a . $b;
$d = $b . 'something' . $c;
$e = $d * $b;
$f = $e / $a;
$g = ($f + $e) * $b;
$h++;
$i--;
Les appels de fonction et les définitions ne doivent pas avoir d'espaces avant la parenthèse.
$x = htmlspecialchars($y);
$item = $DB_site->fetch_array($items);
Les arguments de fonction doivent avoir un espace après chaque virgule.
$x = fetch_something($a, $b, $c);
$i = construct_something(strtoupper('something') . ' ' . substr($var, 0, $b));
Les espaces non nécessaires dans les parenthèses ne doivent pas être utilisés.
$var = addslashes( $var );
$str = fetch_something( strlen( $var ), strpos( $x, $y ) );
$x = construct_x(substr($string, 0, strlen($bla)) . '/' . ucfirst($string));
if ($x == 1 AND ($y == 2 OR $z == 3) AND ($a = fetch_x($x, $y) OR $a == $bla))