php/doc-fr

French translation of the PHP documentation

Documentation française de PHP

Ce document a pour but d'expliquer comment participer à la rédaction de la documentation française de PHP.

Si vous voulez lire la documentation et non la rédiger aller voir le site PHP.net : https://www.php.net/manual/fr/

De plus, si une erreur est présente dans la documentation vérifiez qu'elle ne se trouve pas non plus dans la documentation anglaise, si oui corrigez celle-ci d'abord. La traduction française suivra la modification faite dans la documentation anglaise.

Sommaire

1. Installation
2. Construire la documentation
3. Revision Tracking
4. Coding Standard
5. Traduction, relectures et orthographe
6. Workflow git
7. Commandes utiles

1: Installation

Pour construire la documentation il faut posséder à minima les trois repository suivant :

• php/doc-base : qui possède les outils pour construire la documentation trouvée sur github.com : https://github.com/php/doc-base
• php/doc-en : la version anglaise de la documentation sur laquelle se rabattre quand la version française est inexistante pour une page : https://github.com/php/doc-en
• php/doc-fr : la version française de la documentation : https://github.com/php/doc-fr

Note : vous pouvez cloner à partir du miroir GitHub, mais le dossier où se situe la documentation anglaise doit être nommé en et celui de la documentation française doit être nommé fr afin de pouvoir construire la documentation.

2: Construire la documentation

Il est important de savoir construire la documentation pour s'assurer que les changements effectués ne cassent pas le build, ce qui empêchera la publication de la dernière version de celle-ci sur php.net.

En s'imaginant qu'on se situe dans le dossier fr dans la structure de dossier suivante :

|
|- base
|- en
|- fr
 |- ...

Il suffit d'exécuter php ../base/configure.php --with-lang=fr

Si tout ce passe bien vous serez accueillis avec le message suivant :

All good. Saving .manual.xml... done.
All you have to do now is run 'phd -d /home/user/Dev/php-docs/base/.manual.xml'
If the script hangs here, you can abort with ^C.
         _ _..._ __
        \)`    (` /
         /      `\
        |  d  b   |
        =\  Y    =/--..-="````"-.
          '.=__.-'               `\
             o/                 /\ \
              |                 | \ \   / )
               \    .--""`\    <   \ '-' /
              //   |      ||    \   '---'
         jgs ((,,_/      ((,,___/

 (Run `nice php configure.php` next time!)

Sinon, vous avez une erreur XML Docbook qu'il faut corriger avant.

3: Revision Tracking

Pour s'assurer que la traduction française soit à jour avec la documentation anglaise, un système de rev-check existe.

Ceci ce manifeste par le commentaire suivant en haut de chaque fichier XML :

<!-- EN-Revision: git-hash Maintainer: XXXX Status: YYYYY -->

Lors de la mise à jour d'un fichier pour répliquer les changements effectués sur la version anglaise il est primordial de mettre à jour la clé de hachage git-hash du commit anglais.

Le statut du rev-check peut actuellement être consulté sur le site des outils de la documentation de PHP : http://doc.php.net/revcheck.php?p=filesummary&lang=fr

Pour voir les fichiers qui doivent être mise à jour, allez sur le lien "Outdated Files" qui amène à : http://doc.php.net/revcheck.php?p=files&lang=fr

Normalement le rev-check se trouve sur le site https://doc.php.net, mais à cause de la migration récente de la documentation de SVN à git il se trouve là-bas actuellement.

4: Coding style

Fichier XML

Le pas à respecter pour l'indentation est de 1. Le caractère d'indentation est l'espace (aucune tabulation n'est admise dans les fichiers .xml). Exemple :

<note>
_<para>
__<example>
___<title>
___</title>
__</example>
_</para>
</note>

De plus la soft-limit du nombre de caractères par ligne est de 80.

Exemple PHP

Officiellement le groupe de documentation PHP a choisi d'utiliser les coding standards de PEAR, vous les trouverez ici : http://pear.php.net/manual/en/standards.php

En pratique néanmoins le coding style est un mélange entre PEAR et PSR-2/12, essayez donc de suivre le style dans lequel la page a été écrite, ou celui de la documentation anglaise.

Le code source PHP commence à la colonne zéro de l'exemple :

<?php
ca_commence_ici(); // bien
  ca_commence_ici(); // pas bien
?>

On notera aussi qu'on privilégie les echo à print (echo sans parenthèses). Tout le code est censé être compatible avec error_reporting(E_ALL)

5: Traduction, relectures et orthographe

Afin d'avoir un manuel en bon français, la traduction de certains termes techniques se trouve dans le document TRADUCTIONS.txt.

Il est aussi nécessaire de relire la traduction pour s'assurer que le texte traduit ait du sens et soit en accordance avec le texte anglais.

Après la relecture d'une traduction le tag/commentaire suivant <!-- Reviewed: no/yes --> doit avoir la valeur yes. Lors d'une modification d'un fichier relu ce tag doit passer à la valeur no, sauf lors de modifications mineures/changements purement XML (e.g. changement d'un élément <methodsynopsis>).

Traduire une nouvelle page

La traduction d'une nouvelle page anglaise en français est relativement simple:

1. Copier le fichier à traduire
2. Coller-le au même emplacement, mais dans votre dossier fr
3. Ajouter le commentaire de revision tracking avec la clé de hachage git-hash de la version du fichier anglais que vous venez de copier

La clé de hachage git-hash permet de s'assurer que le fichier soit bien à jour après que la traduction soit faite.

Il est à noter que le fichier doit être entièrement (modulo les exemples) traduit avant d'être ajouté au repo git officiel.

6: Workflow git

Essayez (dans la mesure du possible) de commiter répertoire par répertoire, ou dans reference/ extension par extension.

Pour les messages de logs des commits, on essayera de :

• faire des messages en anglais (au cas où un non-francophone a besoin de comprendre les modifications)
• faire des messages explicites (ne pas mettre "typo" quand on rajoute du texte...)

Utilisateur lambda

Pour proposer une modification vous devez passer par une pull request contre le miroir GitHub doc-fr, pour cela faire un fork du repository doc-fr de GitHub, créer une nouvelle branche (feature branch), faire vos modifications, committer, puis git push la branche sur votre fork afin d'ouvrir une pull request.

Si des remarques sont faites sur votre pull request suivez-les.

En cas de conflit avec votre branche et la branche master, il est préférable de faire un git rebase de votre branche sur master au lieu de git merge la branche master dans la votre.

Utilisateur ayant un accès VCS (c.à.d un compte @php.net, avec du karma sur doc-fr)

Il n'est pas nécessaire de passer par une pull request. Vous pouvez commit et push directement sur la branche master du repo doc-fr sur https://github.com.

Éviter les "merge commit" et préférez un git rebase suivi d'un merge fast-forward.

Ne créer et pusher pas des branches différentes de master sur le repo git officiel.

7: Commandes utiles

Tester syntaxiquement tous les exemples dans le dossier reference :

Ici, on va lancer une analyse syntaxique de tous les fichiers dans les répertoires "functions" de fr/reference/. La technique est simple, on configure short_open_tag à Off en ligne de commande pour que PHP n'analyse que les exemples commençants par <?php, puis on lance la moulinette :

cd reference
for i in $(find -name *.xml); do php -d "short_open_tag=Off" -l $i; done > syntax.txt
cat syntax.txt | grep -B1 Errors

doc-fr's Issues

Typo function => fonction + small update (par => avec)

From manual page: https://php.net/function.fgetcsv

---

"les fichiers encodés par un encodage d'un octet peuvent être mal lus par cette function. "

"les fichiers encodés avec un encodage d'un octet peuvent être mal lus par cette fonction. "

Call to undefined function collator_create() in PHP 8.2.8

From manual page: https://php.net/collator.create

--Call to undefined function collator_create() in PHP 8.2.8 ???

French Translation grammatical issue

From manual page: https://php.net/mysqli.query

---

"les données doivent être correctement formatéES" i/o "les données doivent être correctement formaté"

sentance is contradictory

From manual page: https://php.net/language.oop5.traits

---

Précédence ¶

Une méthode héritée depuis une classe mère est écrasée par une méthode issue d'un Trait. L'ordre de précédence fait en sorte que les méthodes de la classe courante écrasent les méthodes issues d'un Trait, elles-mêmes surchargeant les méthodes héritées.

this sentance is contradictory

`fopen()` : description of `'a+'` mode

From manual page: https://php.net/function.fopen

---

Translation has confusion between "happened" and "appended".

| 'a+' | Ouvre en lecture et écriture ; place le pointeur de fichier à la fin du fichier. Si le fichier n'existe pas, on tente de le créer. Dans ce mode, la fonction fseek() n'affecte que la position de lecture, les écritures surviennent toujours. les écritures sont toujours ajoutées à la fin

| 'a+' | Open for reading and writing; place the file pointer at the end of the file. If the file does not exist, attempt to create it. In this mode, fseek() only affects the reading position, writes are always appended.

Undocumented behaviour difference between php7.4 and php8.2

From manual page: https://php.net/function.strtotime

[edit] My bad, I found this page where the change is, in fact, documented. However, the page is not easy to find. I think there should be a warning when an incorrect number format is used.

---

I noticed the following difference in output for the same code between php7.4 and php8.2:

echo date('Y', strtotime('+-1 year', time()));
// php7.4: 2023
// php8.2: 2025

I didn't find this difference documented anywhere.

Maybe +- should be discouraged with a warning ?

Versions used for this comparison:

PHP 7.4.3-4ubuntu2.19 (cli) (built: Jun 27 2023 15:49:59) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.3-4ubuntu2.19, Copyright (c), by Zend Technologies

PHP 8.2.15 (cli) (built: Jan 20 2024 14:16:39) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.2.15, Copyright (c) Zend Technologies
    with Zend OPcache v8.2.15, Copyright (c), by Zend Technologies
    with Xdebug v3.3.1, Copyright (c) 2002-2023, by Derick Rethans

Spelling mistake in french gmp_pow page

From manual page: https://php.net/function.gmp-pow

---

La puissance positive utiliser pour élever num.
=>
La puissance positive utilisée pour élever num.

Mis translation in french

From manual page: https://php.net/function.random-int

---

but if I click on contribute to documentation, the translation of the text is correct : "Generates cryptographic random integers that are suitable for use where unbiased results are critical, such as when shuffling a deck of cards for a poker game. "

mb_list_encodings() undefined even if mbstring extension is loaded

From manual page: https://php.net/function.mb-list-encodings

PHP version 7.4.33 64bit with in php.ini:
extension=ldap
extension=mbstring
extension=exif ; Must be after mbstring as it depends on it

• Fatal error function mb_list_encoding undefined
  [11-Dec-2022 16:05:21 UTC] PHP Fatal error: Uncaught Error: Call to undefined function  mb_list_encodings() in E:\wamp64\scripts\test.php:9
  The line 9 is:
  $known_codages = mb_list_encodings();

The result of:
$list = get_defined_functions();
is:
[11-Dec-2022 16:07:12 UTC] Array
(
[internal] => Array
(
[0] => zend_version
[1] => func_num_args
[...]
[1484] => mb_convert_encoding
[1485] => mb_detect_encoding
[1486] => mb_list_encodings
[1487] => mb_encoding_aliases

With $list = get_defined_functions(true);
we can see that the function mb_list_encodings is not disabled.

phpinfo() show that mbstring is activated :
mbstring
Multibyte Support enabled
Multibyte string engine libmbfl
HTTP input encoding translation disabled
libmbfl version 1.3.2

The function mb_convert_encoding is recognized and works perfectly.

Same problem happens with PHP 8.0.26, 8.1.13 or 8.2.0

Duplicate FR/EN examples in french "language.types.array" page

From manual page: https://php.net/language.types.array

Page: https://www.php.net/manual/fr/language.types.array.php
Examples 6 and 7 are the same example. The 6th is in French and the 7th is in English.
Can you delete the duplicate line, please? (line 283)

 Comme vous pouvez le voir, la dernière valeur "d" a été assignée à la clé 7. Ceci est du au fait que la dernière clé entière la plus grande utilisé auparavant était 6.

Exemple #6 Exemple complexe sur la modification de type et l'écrasement

Exemple #7 Complex Type Casting and Overwriting example

Cet exemple inclus toutes les variations de modification de type de clés et écrasements des éléments. 

Thank you.

Erreur de logique

From manual page: https://php.net/datetime.format

Il est marqué dans le tableau de référence:
G | Heure, au format 24h, sans les zéros initiaux | 0 à 23

Hors, c'est bien précisé "sans les zéros initiaux", tandis que l'exemple dis "0 à 23".
Rien de bien grave, mais ça reste une erreur.

Bonne continuation

Notice: Array to string conversion in C:\wamp64\www\products-dashboard-ui\dist\displayproduct.php

From manual page: https://php.net/index

--- Notice: Array to string conversion in C:\wamp64\www\products-dashboard-ui\dist\displayproduct.php on line 53

Wrong translation of UTC format on `gmdate` function

The current version of gmdate function display a wrong format (corresponding to UTC)

See https://github.com/php/doc-fr/blob/master/reference/datetime/functions/gmdate.xml#L8

Expected : "Formate une date/heure GMT/UTC"
But got : "Formate une date/heure GMT/CUT"

PHP et VSC

From manual page: https://php.net/faq.misc

Bonjour à tous,
Je n'arrive pas à mettre en route l'extension PHP server sur VSC. (le plugin s'est bien installé)
J'ai ce message :

En refermant VSC et en l'ouvrant, j'ai eu ça :

qui mène à ça

On m'a dit d'aller voir https://www.php.net/downloads.php
et de télécharger un des lien proposé ici :

J'en ai téléchargé 2 , mais lorsque je clique sur n'importe quel .exe, j'ai ça :

QQn a une solution ?

Bug PHP version for xPath method for XML

From manual page: https://php.net/simplexmlelement.xpath

---

On this page of the PHP doc, this example:

<?php
$string = <<<XML
<a>
 <b>
  <c>text</c>
  <c>stuff</c>
 </b>
 <d>
  <c>code</c>
 </d>
</a>
XML;

$xml = new SimpleXMLElement($string);

/* Search for <a><b><c> */
$result = $xml->xpath('/a/b/c');

while(list( , $node) = each($result)) {
    echo '/a/b/c: ',$node,"\n";
}

/* Relative paths also work... */
$result = $xml->xpath('b/c');

while(list( , $node) = each($result)) {
    echo 'b/c: ',$node,"\n";
}
?>

...doesn't work in PHP8+ because each method deleted in PHP v8

FANN is not working on Wamp

From manual page: https://php.net/fann.installation

---

After following the guide on https://www.php.net/manual/fr/fann.installation.php to use Fann on my wamp server (I use Windows, PHP 7.3.21 and the corresponding version of FANN and libfann) , Visual Studio Code doesn't detect FANN. I have an error telling my FANN-based functions are not defined but when I hover on them I have the description of what it is suppose to do.

Could somebody help me ?

erreur de traduction

From manual page: https://php.net/language.types.numeric-strings

https://www.php.net/manual/fr/language.types.numeric-strings.php
Ce texte est ecrit en anglais et non en francais,alors uqe le lien est indique en francais .
La bise au chat

PHP mail() function arguments names in French documentation

From manual page: https://php.net/function.mail

---

The two last arguments of the function prototype have the same name in the French documentation ($additional_params twice) :

https://www.php.net/manual/fr/function.mail.php

The first one should be $additional_headers as in the English documentation :

https://www.php.net/manual/en/function.mail.php

ma classe

From manual page: https://php.net/ref.filesystem

---

class Files{
public function FileCreatWriteNotRead(string $FileName, string $TypeOpenFile, string $MessageWriteInFile){
$File = fopen($FileName, $TypeOpenFile);
fputs($File, $MessageWriteInFile);
fclose($File);
}
public function FileDelet(string $FileName){
unlink($FileName);
}
}

On dit : il requiert/elle requiert

https://www.php.net/manual/fr/language.types.type-juggling.php

On dit : il requiert/elle requiert
et pas : PHP ne requis pas

French translation repetition

From manual page: https://php.net/function.array-filter

---

The french translation for the "mode" parameter contain a repetition:
-> "Par défaut 0 par défaut qui passera la valeur comme seul argument de callback."
It could be:
-> "Par défaut 0 qui passera la valeur comme seul argument de callback."

Error on "u" modifier in French translation of PCRE pattern modifiers

Page affected

https://www.php.net/manual/fr/reference.pcre.pattern.modifiers.php

Error

The "u" modifier turns on Unicode features incompatible with Perl, as the english doc rightly says.

However the french documentation says that it turns them OFF, not on.

Original wording

Cette option désactive les fonctionnalités additionnelles de PCRE qui ne sont pas compatibles avec Perl. Le masque et la chaîne d'entrée sont traitées comme des chaînes UTF-8. Une chaîne d'entrée invalide entrainera aucune détection par les fonctions preg_*. Un masque invalide va lever une erreur de niveau E_WARNING. Les séquences UTF-8 de cinq et six octets sont invalides.

Suggested fix

Cette option active des fonctionnalités additionnelles de PCRE qui ne sont pas compatibles avec Perl. La chaîne d'entrée et le masque sont traités comme des chaînes UTF-8. Une chaîne d'entrée invalid aura pour conséquence une absence de correspondance dans les fonctions preg_*. Un masque invalide va lever une erreur de niveau E_WARNING. Les séquences UTF-8 de cinq et six octets sont considérées comme invalides.

Sentence cut in the middle in the French version for the rawurlencode function

From manual page: https://php.net/function.rawurlencode

See screenshots for more details !:

Faute de frappe

From manual page: https://php.net/function.array-map

L'expression "si un nombre insuffisant d'arguments sont fourni" doit être remplacée par "si un nombre insuffisant d'arguments est fourni".

Typing error in the documentation of the preg_match function (https://www.php.net/manual/fr/function.preg-match.php)

The word "survient." is repeated twice in the documentation of the return value.

This is not a serious enough error, but I still wanted to point it out so as not to confuse some people.

The doc fr:

The doc en:

Small typo in the Oracle OCI8 module requirements

Hi,

From manual page: https://php.net/oci8.requirements

I think there is a small typo in the Oracle OCI8 module requirements. In English we have:

In summary, Oracle Client 19, 18 and 12.2 can connect to Oracle Database 11.2 or greater.

while in French we have:

En résumé, Oracle Client 19, 18 et 12.2 peuvent se connecter à Oracle Database 10.2 ou supérieur.

so if the English documentation is right (I'm no Oracle specialist), we should have:

En résumé, Oracle Client 19, 18 et 12.2 peuvent se connecter à Oracle Database 11.2 ou supérieur.

I can open a PR to fix that if you wish.

Regards,

---

Nicolas

error on encoding by creating a new zip file

From manual page: https://php.net/class.ziparchive

---

Today I was trying create a file with this name "Liste des postes de distribution à la date du ".now()->format('d-m-Y H:i:s')" and because of the accent on "à" I faced an issue and I decide to report it

Typos at /ldap.examples-controls.php

doc-fr/reference/ldap/examples.xml

Line 71 in 14d787f

<title>Lier avec des information ppolicy</title>

doc-fr/reference/ldap/examples.xml

Line 93 in 14d787f

echo "Code d'erreur Ppolicy : ".$value['error'];

cannot save boolean false in Mysql database

From manual page: https://php.net/language.types.boolean

---

When I use an object containing a bool attribute, it is impossible to save the false value of the boolean in the database

Typo in FRENCH documentation

From manual page: https://php.net/function.mktime

Plural is missing "aux valeurs" (twice) // Le pluriel manque sur "au valeur" (deux fois)

L'année, peut être sur deux ou quatre chiffres, avec des valeurs allant de 0 à 69, correspondant au valeur 2000 à 2069 et 70 à 100, correspondant au valeur 1970 à 2000. Sur les systèmes où time_t un entier signé sur 32bits, ce qui est le plus courant de nos jours, la période valide pour year est quelque part près de 1901 et 2038.

L'année, peut être sur deux ou quatre chiffres, avec des valeurs allant de 0 à 69, correspondant aux valeurs 2000 à 2069 et 70 à 100, correspondant aux valeurs 1970 à 2000. Sur les systèmes où time_t un entier signé sur 32bits, ce qui est le plus courant de nos jours, la période valide pour year est quelque part près de 1901 et 2038.

Fibers - wrong example output

From manual page: https://php.net/language.fibers

---

There is a typo in the "Exemple #1 Utilisation de base" ouput . It should be in this order :

Valeur de la suspension de la fibre: fiber
Valeur utilisée pour reprendre la fibre: test

Typo in description of array_diff

From manual page: https://php.net/function.array-diff

---

In French the description for array_diff refers to array1 instead of array. The description should be:

array_diff() compare le tableau array avec un ou plusieurs tableaux et retourne les valeurs du tableau array qui ne sont pas présentes dans les autres tableaux.

Typo in "setlocale" function page

From manual page: https://www.php.net/manual/fr/function.setlocale.php

Dans les "Notes" :

"Les utilisateurs de Windows trouverons des informations utiles à propos du paramètre ..."

devrait être :

"Les utilisateurs de Windows trouveront des informations utiles à propos du paramètre ..."

---

Translation issue en french on PCRE

From manual page: https://php.net/book.pcre

---

In french translation, should not be "rationnelles" but "régulières"
"rationnelles" -> 2/3
"régulières" -> /^.*$/

ftp_nlist can also return null

From manual page: https://php.net/function.ftp-nlist

---

It happened to me today, in v7.4.7 :

$list = ftp_nlist(null, '/');
var_dump($list);

will result in

PHP Warning:  ftp_nlist() expects parameter 1 to be resource, null given in /var/www/ftp_nlist.php on line 2
NULL

I also confirmed this behavior in other php versions (5.3 and 7.2).
Although it is understandable, the documentation does not mention it and I expected to have false as return