Des instructions permettent d'inclure du code qui se trouve dans des fichiers externes et sont particulièrement utiles pour la constitution et l'utilisation de bibliothèques de fonctions. Il n'y a pas d'applications PHP qui n'utilisent pas d'inclusion de fichiers externes.

4 instructions pour inclure du code

Quatre instructions permettent d'inclure des fichiers externes dans un script :

Chacune des instructions accepte comme paramètre le chemin du fichier à inclure dans la page appelante : 

include('entete.html');
include_once('fonctions_communes.php');
require('commun/bib_fonctions.php');
require_once('../general/mes_fonctions.php');

include, include_once, require et require_once sont des structures de langage particulières et les parenthèses ne sont pas nécessaires autour du paramètre.
include('entete.html'); est équivalent à include 'entete.html';

L'extension des fichiers à inclure n'est pas fixée et on peut inclure de fichiers contenant n'importe quel type de code (HTML, CSS, JavaScript et évidemment PHP). Je vous conseille de donner aux fichier à inclure l'extension correspondante à leur contenu : php pour du code PHP, html pour du code HTML, etc. et ne pas utiliser une extension .inc comme c'est parfois le cas.

Quand le fichier inclus est composé de code PHP, ce code est exécuté.

Le fichier n'est inclus que si l'instruction include ou require est exécutée. Les inclusions conditionnelles dans des tests if sont donc possibles. Dans ce cas, les blocs du test doivent obligatoirement être entourés d'accolades ({ et }).
Les inclusions dans des boucles seront faites à chaque itération de la boucle.
Si le fichier inclus contient du code PHP qui déclare des fonctions, l'inclusion provoquera donc des erreurs dûes à l'essai de re-déclaration des fonctions.

Les instructions include_once et require_once fonctionnent de la même façon que include et require, à la différence qu'elles empêchent le même fichier d'être inclus plusieurs fois dans un même script. Cette fonctionnalité est à utiliser par exemple quand des fichier inclus contiennent eux-même d'autres fichiers inclus. cela évite que des variables, des constantes, ou des fonctions soient définies plusieurs fois provoquant ainsi des erreurs.

Les instructions include et include_once enverront une erreur de niveau warning si elles ne peuvent pas trouver le fichier; ce comportement est différent de require et require_once qui enverront une erreur de niveau fatal si elles ne peuvent pas trouver le fichier, ce qui arrêtera donc le script.

Notre bibliothèque de fonctions

Vous avez pu remarquer que jusqu'à maintenant le début des exemples de test est toujours le même : le début d'une page HTML. Le seul élement qui varie est le titre de la page. Pour éviter ces répétitions, nous allons maintenant utiliser une fonction placée dans une bibliothèque (un fichier PHP ne contenant que des fonctions). De cette façon nous allons simplifier notre code, et chose extrêmement importante éviter d'avoir des mélanges de langages différents (une couche d'HTML, une couche de PHP, une couche d'HTML, etc.)

/**
 * Envoie à la sortie standard le début du code HTML d'une page
 *
 * @param string	$titre	Titre de la page
 */
function htmlDebut($titre) {
	$titre = htmlentities($titre, ENT_COMPAT, 'ISO-8859-1');

	echo '<!DOCTYPE html>',
		'<html lang="fr">',
			'<head>',
				'<meta charset="ISO-8859-1">',
				'<title>', $titre, '</title>',
				'<style>',
				'body {	font-size: 13px;', 
						'font-family: Verdana, sans-serif}',
				'h3 {	font-size: 15px;',
						'margin: 0 0 15px 0;', 
						'padding: 5px 0;', 
						'text-align: center;', 
						'background: #FFF5AB}',
				'h4 {	font-size: 13px;',
						'margin: 1em 0 0 0;',
						'padding: 3px;',
						'background: #ebebeb}',
				'</style>',
			'</head>',
			'<body>',
				'<h3>', $titre, '</h3>';
}

Le code de la fonction est une simple instruction echo dont les paramètres sont du code HTML sous la forme de chaîne de caractères. Le code HTML est un peu moins simpliste que celui utilisé jusqu'à maintenant car il intégre un minimum de régles de style CSS.

Le code HTML pourrait être écrit dans une seule valeur littérale. C'est à éviter car dans ce cas beaucoup de caractères sans importance pour le navigateur lui seront transmis (espaces consécutifs, saut saut de ligne, tabulations), à moins de perdre en lisibilité (ie tout le code HTML écrit sur la même ligne). Ces caractères inutiles transiteront sur le réseau et devront être pris en compte par le navigateur alors qu'ils ne servent à rien.
Utilisée avec comme titre 'Test', la fonction va envoyer au navigateur 312 octets. Si on avait mis le code HTML dans une seule expression littérale, en gardant la mise en forme pour la lisibilité, on enverrait 452 octets, soit 44% de plus. Le nombre de caractères inutilement transmis est à multiplier par le nombre de visite à la page, et à mettre en relation avec le pris payé à l'hébergeur du site qui facture la bande passante.
Il est donc particulièrement important de faire transiter sur le réseau des contenus avec la taille la plus petite possible (code HTML, CSS et JavaScript débarassé des sauts de ligne et autres tabulations, fichiers images réduits, etc.); A noter, la description de la fonction sous la forme de commentaires PHPDoc (idem JavaDoc - voir les vidéos pour plus d'explications).

La fonction se trouve dans le fichier bib_fonctions.php, placé dans le dossier de travail.

Exemple : inclusion de fichier

Le fichier bib_fonctions.php est complété par la fonction htmlFin qui génére et affiche le code HTML de fin de page : 

/**
 * Envoie à la sortie standard la fin du code HTML d'une page
 */
function htmlFin() {
	echo '</body></html>';
}

Exercice : bibliothèque de fonctions

Ecrivez une bibliothèque avec les fonctions suivantes :

- la fonction debut_html permet de renvoyer tout le code HTML du début d'une page : 

<!DOCTYPE html>
<html lang="fr">
  <head>
    <title>Titre de la page</title>
  </head>
  <body>

Cette fonction accepte deux arguments : le titre de la page (tag TITLE) et la couleur de fond de la page. Si aucune couleur de fond n'est passée, la valeur par défaut du paramètre est '#FFFFFF'.

- la fonction table_html permet d'afficher les chaînes de caractères qui lui sont passées sous la forme d'une table html. Le nombre de colonnes de la table sera variable, et déterminé par un des arguments. Il faut prévoir aussi des arguments qui permettent de gérer les couleurs : couleur de fond de la table, couleur de fond de cellule pour faire un affichage différencié une ligne sur deux. Ces arguments sont obligatoires. La table html doit avoir une ligne d'en-tête et au moins une ligne de "données". Si des arguments ne sont pas en bon nombre, un message devra être renvoyé pour signaler l'erreur.

- la fonction fin_html renvoie le code HTML qui termine une page. Le pied de page est composé d'une ligne avec le nom de l'auteur de la page (à passer en argument à la fonction), suivi de la date de génération de la page.

Ces trois fonctions doivent se trouver dans le fichier bibli_html.php.

Ecrivez le script test.php qui génére une page HTML en utilisant ces trois fonctions.

Une solution possible

Le fichier bibli_html.php avec les 3 fonctions demandées. 

<?php
/**
 * Renvoie le code HTML du début d'une page
 *
 * @param string    $titre      Titre de la page
 * @param string    $couleur    Couleur de fond de la page
 *
 * @return string   Code HTML du début d'une page
 */
function debut_html($titre, $couleur='#FFFFFF') {
  return '<!DOCTYPE html><html lang="fr"><head>'
        .'<title>'.$titre.'</title>'
        .'<style>body{background-color:'.$couleur.'}</style>'
		.'</head><body>';
}

/**
 * Renvoie le code HTML d'une table.
 * Le texte des cellules est contenu dans les arguments non décrits
 *
 * @param integer   $nbCol      Nombre de colonnes
 * @param string    $coulFond   Couleur de fond de la table
 * @param string    $coulLigne  Couleur d'une ligne sur 2
 *
 * @return string   Code HTML de la table ou message d'erreur
 */
function table_html($nbCol, $coulFond, $coulLigne) {
  if ($nbCol < 1) {
    return 'Mauvais nombre de colonnes';
  }
  if ($coulFond ==  '' || $coulLigne == '') {
    return 'Mauvaise couleur';
  }
  //--- Bon nombre d'arguments ?
  $nbArgs = func_num_args();
  if (($nbArgs - 3) % $nbCol != 0) {
    return 'Mauvais nombre d\'éléments pour la table';
  }
  if (($nbArgs - 3) < ($nbCol * 2)) {
    return 'Pas assez d\'éléments pour faire au moins
            un en-tête et une ligne';
  }
  //--- Les arguments sont mis dans le tableau Args
  $args = func_get_args();
  //--- Début table html ------------------------
  $html = '<table style="text-align:center; background-color:'.
          $coulFond.'">';
  $numLig = 0;
  //--- Boucle de traitement des arguments -------
  // on commence au 3 éme
  for ($i = 3; $i < $nbArgs; $i += $nbCol) {
    $numLig ++;
    //--- Nouvelle ligne
    if ($numLig % 2 == 0) {
      $html .= '<tr>';
    } else {
      $html.= '<tr style="background-color:'.$coulLigne.'">';
    }
    //--- Les celulles
    for ($j = 0; $j < $nbCol; $j++) {
      $html .= '<td style="width:'.floor(100/$nbCol).'px">'
              .$args[$j + $i].'</td>';
    }
    $html .= '</tr>';
  }
  $html .= '</table>';
  return $html;
}
/**
 * Renvoie le code HTML de fin d'une page
 *
 * @param string    $auteur     Nom de l'auteur
 *
 * @return string   Code HTML de fin d'une page
 */
function fin_html($auteur) {
  return '<hr><p>'.$auteur.' ('.date("d/m/Y H:i:s").')'.'</p>'
        .'</body></html>';
}
?>

Le fichier test.php. 

<?php
require'bibli_html.php';

echo debut_html('test'),
	 table_html(3,'#FFFFCE','#FFCC99',
        'un','deux','trois',
        1,2,3,4,5,6),
	 fin_html('François Piat');
?>