Mon wiki - obsolete:informatique:php

doxygen

anonymous@undisclosed.example.com (Anonymous) — Wed, 20 Nov 2024 19:49:16 +0000

Doxygen

C'est un générateur de documentation capable de produire une documentation logicielle à partir du code source d'un programme. Pour cela, il tient compte de la grammaire du language dans lequel est écrit le code source, ainsi que des commentaires.

Le contenu de cette page est valable dans le cadre de la documentation d'un projet en PHP. Pour plus de renseignements, il faut se référer à la documentation officielle.

Définition d'un bloc de documentation

Il y a plusieurs moyen de définir un bloc de documentation. Le plus simple à utiliser avec Netbeans est le JavaDoc :

/**
 *
 */

En effet, il est reconnu par défaut et récupère automatiquement paramètres, valeur de retour et exceptions.

Mots-clefs

Dans la description des commandes décrites, les valeurs entre “<>” sont obligatoires, celles entre “{}” sont optionnelles.
Doxygen reconnait deux syntaxes différentes pour les commandes, celle avec le @ et celle avec le \. Les listes suivantes contiennent un mélange des deux syntaxes car certaines commande commençant par @ sont interprétées par PHPUnit.
Pour la liste complète des mots-clefs, il faut se référer à la documentation officielle.

Description

@author {description} : définition de l'auteur.
\bug {description} : définition des bugs présents dans l'entité.
@deprecated {description} : indication que l'entité est obsolète.
@exception <objet> {description} : définition d'une exception qui peut être générée par l'entité.
@param <type> <nom> {description} : définition d'un ou de plusieurs paramètres de l'entité.
Le type peut être composé si les valeurs sont séparées par des “|”.
Le nom peut être composé si les valeurs sont séparées par des “,”.
@return {description} : définition de la valeur de retour de l'entité.
@see {description} : définition de références pour l'entité.
@since {description} : définition de l'apparition de l'entité. Ça peut être une date, un numéro de version ou tout autre moyen de définir le moment d'apparition de l'entité.
\test {description} : définition des cas de tests de l'entité.
@todo {description} : définition de tâches à faire pour améliorer l'entité.

Mise en forme

\a {mot} : met le mot qui suit en italique.
\b {mot} : met le mot qui suit en gras.
\c {mot} : met le mot qui suit dans une police de type machine à écrire.
\li {description} : permet de générer une liste de valeurs.
\n : force l'insertion d'une nouvelle ligne.
\verbatim : commence un bloc qui affiche le texte tel quel. Les fonctions sont désactivées dans un tel bloc. Le bloc doit se terminer impérativement par \endverbatim.

Configuration

La configuration se fait dans un fichier ini. Il peut être utilisé en ligne de commande ou par l'outil Doxywizard. Il peut être généré manuellement, en ligne de commande ou par l'outil Doxywizard.

ALIASES : ajoute des nouvelles commandes qui seront affichées dans la documentation.
CLASS_DIAGRAMS : insère un diagramme de classe si la valeur est YES.
INPUT : liste de fichiers et répertoires contenant des sources commentées.
JAVADOC_AUTOBRIEF : génère automatiquement la description courte à partir de la première ligne si la valeur est YES. Si la valeur est NO, il faut utiliser la commande \brief.
OUTPUT_DIRECTORY : défini le répertoire de génération de la documentation.
PROJECT_BRIEF : défini une courte description du projet qui apparait sous le nom du projet.
PROJECT_LOGO : défini le chemin d'accès au logo du projet. La taille maximale du logo est 55×200.
PROJECT_NAME : défini le nom du projet.
RECURSIVE : indique si la recherche de documentation se fait de manière récursive ou non.
REPEAT_BRIEF : répète la description courte avant la description détaillée si la valeur est YES.
SOURCE_BROWSER : insère les sources si la valeur est YES. La documentation est automatiquement liée au code et inversement.
STRIP_FROM_PATH : défini la partie du chemin d'accès à ne pas faire apparaître dans la description du fichier source.

Pour la liste complète des options de configuration, il faut se référer à la documentation officielle.

Commandes

Doxygen est destiné à être utilisé en ligne de commande. La génération de documentation peut donc être automatisée.

doxygen -h : affiche la page de manuel.
doxygen [-v] -g [fichier] : génère un modèle de fichier de configuration.
doxygen [-v] -u [fichier] : met à jour un fichier de configuration d'une ancienne version.
doxygen [fichier] : génère la documentation en suivant les règles du fichier de configuration.

Le nom du fichier de configuration peut être omis. Le nom par défaut est Doxyfile.
Le drapeau v indique de ne pas générer de commentaire dans le fichier de configuration.

Examples de fichiers

Avec les deux fichiers ci-dessous, il est possible de générer une documentation basique.

Configuration

Doxyfile

PROJECT_NAME      = "My really special project"
PROJECT_BRIEF     = "So special"
OUTPUT_DIRECTORY  = C:/Test
REPEAT_BRIEF      = NO
STRIP_FROM_PATH   = C:/Test
JAVADOC_AUTOBRIEF = YES
INPUT             = C:/Test
RECURSIVE         = NO
SOURCE_BROWSER    = YES
CLASS_DIAGRAMS    = NO

Source

test.php

<?php
/**
 * The Test class do something.
 * The Test class do something really nice but I wont tell :).
 *
 * @author Me, Myself and I
 * @since version 1.0.0
 * @todo Replace test method by something better.
 */
class Test
{
    /**
     * The test method do something.
     * The test method do something really nice but I wont tell :).
     *
     * @param string  $param1 the first parameter.
     * @param integer $param2 the second parameter.
     * @return a string wich is a concatenation of the inputs
     *
     * @author Me, Myself and I
     * @since version 1.0.0
     * @deprecated since version 2.0.0
     */
    public function test($param1, $param2) {
        $something = $param1 . $param2;
        return $something;
    }
}

installer_hhvm_sur_ubuntu_15.10

anonymous@undisclosed.example.com (Anonymous) — Sun, 24 Nov 2024 17:32:33 +0000

Installer HHVM sur Ubuntu 15.10

# Gère les dépôts utilisés pour installer des programmes (common)
sudo apt-get install software-properties-common
 
# Ajoute la clé publique 
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 0x5a16e7281be7a449
 
# Ajout des dépôts de HHVM à la liste existante
sudo add-apt-repository "deb http://dl.hhvm.com/ubuntu $(lsb_release -sc) main"
 
# Mise à jour des dépots
sudo apt-get update
 
# Installe HHVM
sudo apt-get install hhvm

Pour plus d'informations, voir la page officielle.

utiliser_plusieurs_versions_de_php_sur_la_version_serveur_de_ubuntu_12.04_lts

anonymous@undisclosed.example.com (Anonymous) — Sun, 24 Nov 2024 17:34:16 +0000

Utiliser plusieurs versions de PHP sur la version serveur de Ubuntu 12.04 LTS

Par défaut, la version de PHP installée sur cette version est la version 5.3.10. Voici les différentes étapes pour pouvoir utiliser plusieurs versions de PHP simultanement avec Apache.

Installation des bibliothèques nécessaires

# Bibliothèques pour la compilation
apt-get install libxml2-dev \
libssl-dev \
libbz2-dev \
libcurl4-openssl-dev \
libpng-dev \
libjpeg-dev \
libmcrypt-dev \
libicu-dev \
libldap2-dev \
autoconf \
g++
 
# Bibliothèques pour l'installation
apt-get install chkconfig \
libapache2-mod-fastcgi

Compilation de PHP

# récupération du code source
wget http://ca3.php.net/get/php-5.5.12.tar.bz2/from/a/mirror
 
# extraction de l'archive
tar -xjf php-5.5.12.tar.bz2
 
cd php-5.5.12
 
# configuration des paramètres de compilation
./configure --prefix=/usr/local/php55 \
    --with-config-file-path=/etc/php55 \
    --with-config-file-scan-dir=/etc/php55/php.d \
    --with-mysql \
    --with-mysqli \
    --with-pdo-mysql \
    --with-bz2 \
    --with-curl \
    --with-gettext \
    --with-iconv-dir \
    --with-openssl \
    --with-mcrypt \
    --with-gd \
    --with-pcre-regex \
    --with-zlib \
    --disable-rpath \
    --enable-mbstring \
    --enable-soap \
    --enable-fpm \
    --with-fpm-user=www-data \
    --with-fpm-group=www-data \
    --with-pear \
    --with-ldap=shared \
    --enable-ftp \
    --enable-intl
 
make -j4 && sudo make install
sudo mkdir /etc/php55
sudo cp php.ini-production /etc/php55/php.ini

Notes :

--with-mysql ne doit plus être utilisé car l'extension n'est plus supportée ¹⁾.
--with-mysqli et --with-pdo-mysql utilisent par défaut la bibliothèque libmysqlclient. Il est possible de la remplacer par la bibliothèque mysqlnd qui est native ²⁾.

Configuration de Apache - FastCGI

Il faut commencer par activer le module FastCGI dans Apache.

Ensuite, il faut créer le fichier /var/www/cgi-bin/php-cgi-5.5 :

#!/bin/sh
PHP_FCGI_CHILDREN=3
export PHP_FCGI_CHILDREN
 
PHP_FCGI_MAX_REQUESTS=5000
export PHP_FCGI_MAX_REQUESTS
 
exec /usr/local/php55/bin/php-cgi

Puis rendre ce fichier exécutable.

Configuration de Apache - VirtualHost

Il faut configurer normalement le VirtualHost pour le site que nous voulons servir. Il faut cependant ajouter quelques instructions spécifiques à l'utilisation de FastCGI.

Il faut ajouter l'option d'exécution de CGI

Options Indexes FollowSymLinks MultiViews ExecCGI

Il faut ajouter la méthode que l'on va utiliser pour manipuler les fichiers php :
```
AddHandler fastcgi .php
```
ll faut configurer la méthode que l'on va utiliser pour manipuler les fichiers php :
```
Action fastcgi /cgi-bin/php-cgi-5.5
```
Il faut configurer l'alias utilisé à l'étape précédente :
```
ScriptAlias /cgi-bin/ "/var/www/cgi-bin/"
```

Il faut configurer le dossier dans lequel se trouve les scripts utilisés par le module FastCGI :

<Directory /var/www/cgi-bin/>
    AllowOverride All
    Options None
    Order allow,deny
    Allow from all
</Directory>

Le résultat final devrait ressembler à ce qui suit :

<VirtualHost *:80>
    ServerName project
    ServerAdmin webmaster@localhost
 
    DocumentRoot /var/www/project
    <Directory /var/www/project>
        Options Indexes FollowSymLinks MultiViews ExecCGI
        AllowOverride All
        AddHandler fastcgi .php
        Action fastcgi /cgi-bin/php-cgi-5.5
        Order allow,deny
        allow from all
    </Directory>
 
    ScriptAlias /cgi-bin/ "/var/www/cgi-bin/"
 
    <Directory /var/www/cgi-bin/>
        AllowOverride All
        Options None
        Order allow,deny
        Allow from all
    </Directory>
 
    ErrorLog ${APACHE_LOG_DIR}/project.error.log
 
    # Possible values include: debug, info, notice, warn, error, crit,
    # alert, emerg.
    LogLevel warn
 
    CustomLog ${APACHE_LOG_DIR}/project.access.log combined
</VirtualHost>

Attention, pour que cette configuration fonctionne, il faut que le module actions soit activé. Il est également important de noter que cette configuration peut cohabiter avec le module php.

Liens utiles

¹⁾

Request for Comments: ext/mysql deprecation

²⁾

Choosing a library

xampp

anonymous@undisclosed.example.com (Anonymous) — Sun, 24 Nov 2024 17:34:25 +0000

XAMPP

XAMPP est un kit d'installation d'Apache qui contient MySql/MariaDB, PHP et Perl. XAMPP est réellement très facile à installer et à utiliser - vous n'avez qu'à le télécharger, le décompresser et le démarrer.

Installation sous Windows

Il faut d'abord télécharger la version voulue sur la page de téléchargement. À l'heure actuelle, il y a deux versions disponibles :

1.8.2 qui utilise la version 5.4.22 de PHP et la version 5.5.34 de MySql,
1.8.3 qui utilise la version 5.5.6 de PHP et la version 5.6.14 de MySql.

Il est recommandé d'utiliser l'installeur car c'est la manière la plus simple pour mettre en place XAMPP. Cependant il est aussi possible d'utiliser les archives. Pour plus d'information convernant les différentes étapes d'installation, il suffit de lire la documentation officielle :

Pour utiliser certaines fonctions de XAMPP (php_intl par exemple), il est nécessaire d'installer le pack Microsoft Visual C++ Redistribuable. Il est impératif d'installer la version 32 bit même si la machine hôte est en 64 bit. En fonction de la version de XAMPP installée, il faut installer une version différente de ce pack :

pour XAMPP 1.8.2, il faut installer la version 2008 (disponible ici)
pour XAMPP 1.8.3, il faut installer la version 2012 (disponible ici)

Pour installer ce pack, les droits administrateur sont nécessaires.

Configuration de PHP

Il faut garder en mémoire que le but de XAMPP est de fournir un environnement de développement facilement. Il est très fortement déconseillé de l'utiliser dans un environnement de production. La configuration proposée reste dans cet optique.
Dans le fichier php.ini, chercher et modifier (ou activer) les lignes suivantes :

; dépend de la localisation de la machine.
date.timezone = America/Montreal

; dépend de la puissance de la machine.
memory_limit = 512M

; uniquement pour les développements. Il est nécessaire d'améliorer les performances
; du code plutôt que d'augmenter les limites dans la configuration.
max_input_var = 10000

; uniquement pour les développements sauf si l'application développée à besoin de
; charger de gros fichiers. Très utile pour le chargement de fichier de données
; avec phpmyadmin.
post_max_size = 20M
upload_max_size = 20M

; pour activer l'internationalisation de l'application développée.
extension = php_intl.dll

Configuration d'un hôte virtuel

Pour pouvoir utiliser et tester l'application développée, il est nécessaire de la rendre accessible par Apache. Pour cela, il faut configurer l'hôte afin de servir l'application aux navigateurs qui le demande.
Pour de l'information générale pour la configuration, lire la documentation officielle et les examples de configuration.

Dans le cas de XAMPP, il faut savoir que par défaut, l'accès au système de fichiers du serveur est restreint. Il faut explicitement autoriser l'accès aux répertoires nécessaires. La partie de la configuration qui restreint les accès se trouve dans le fichier httpd.conf :

# Deny access to the entirety of your server's filesystem. You must
# explicitly permit access to web content directories in other 
# <Directory> blocks below.
#
<Directory />
    AllowOverride none
    Require all denied
</Directory>

Voici un example rapide de configuration à faire dans le fichier httpd-vhosts.conf :

<VirtualHost hostname:80>
	ServerName hostname
	DocumentRoot "C:\path\to\web\folder"
	<Directory "C:\path\to\web\folder">
		Options Indexes FollowSymLinks Includes ExecCGI
		AllowOverride All
		Order allow,deny
		Allow from all
		Require all granted
	</Directory>
</VirtualHost>

Il faut noter la présence de Require all granted qui autorise l'accès au répertoire.