Developer FAQ

Comment devenir un contributeur PEAR et comment accéder à PEAR via cvs ?

Tout est décrit ici.

J'ai écrit en C un module PHP. Quelles sont les règles pour l'inclure à PEAR ?

Le projet PECL (un avantage inattendu de PEAR) est l'endroit où sont publiées les extensions C pour PHP.

Pourquoi PEAR est séparé dans pear/ et pear-core/ ?

Les premiers éléments de PEAR étaient contenus dans le répertoire pear-core/ (once php-src/pear) et donc étaient intégrés à chaque nouvelle version de PHP.

Pour les versions futures de PEAR, ce mode de fonctionnement n'est plus envisageable car PEAR est devenu trop gros pour l'intégrer à toutes les nouvelles versions de PHP. Il a donc été décidé de commiter tous les nouveaux documents dans le répertoire PEAR. Les autres éléments qui restent dans le répertoire php-src/pear vont être déplacées dans la nouvelle arborescence prochainement. Seul le code du gestionnaire de paquet PEAR va restés intégré automatiquement à chaque release de PHP.

Pourquoi le structure de pear/ et pear-core/ ne sont pas les mêmes ?

La structure des répertoires de pear-core/ correspond à celle de l'arborescence de l'installation ( par défaut /usr/local/lib/php), et est organisée comme une simple hiérarchie. Quoi qu'il en soit, la structure de pear/ est basé sur le paquetage auquel le fichier appartient. La localisation finale de chaque fichier est indépendante de l'endroit où il se trouve dans le paquet. Toutes ces informations sont définies dans le fichier de description du paquetage.

Pourquoi une arborescence à plat plutôt qu'en profondeur ?

Dans CVS, le code PEAR est organisé par paquets plutôt que de façon hiérarchique. Par exemple, si vous souhaitez utiliser la classe XML_RPC, vous devez inclure le fichier "XML/RPC.php". Logiquement, on pourrait penser que dans le cvs ce fichier se trouve dans pear/XML/RPC.php, mais ce n'est pas le cas. XML_RPC est un paquetage indépendant qui dispose de sa structure propre dans le CVS. Dans ce cas précis, le fichier est localisé dans pear/XML_RPC/RPC.php. Le fichier de description du paquetage (package.xml) est utilisé pour dire où les fichiers seront finalement installés.

La raison pour laquelle le CVS est organisé de cette façon est que cela rend l'administration des paquetages plus facile.

Est-ce que je peux commiter un module expérimental/instable ?

Oui. Cependant, assurez vous de bien noter le statut expérimental/instable de ce projet dans la documentation. Le meilleur endroit pour le faire est le fichier package.xml dans la balise <status>. Les valeurs pour cette balise sont :

alpha

Premières étapes du développement. Tout peut encore changer sans prévenir.

beta

L'API ne devrait normalement pas changer. Le logiciel est utilisable mais peut comporter des bogues.

devel

Une version pour les autres développeurs qui voudraient accéder au code pour tester, participer ou donner des retours.

stable

Le logiciel a été testé, l'API est fixée, la documentation est écrite. Il s'agit de la version recommandée aux utilisateurs pour un environnement de production.

snapshot

un snapshot du CVS daté.

Suis-je censé ajouter des exemples ou tester les fichiers de mon paquet et où dois-je les sauvegarder ?

Les exemples sont bienvenus, particulièrement si votre classe à une API complexe. Cependant les exemples ne sont qu'une part de la documentation. Préférez un travail sur la documentation plutôt qu'une création d'exemples. Les exemples doivent être stockés dans le sous répertoire docs dans l'arborescence du paquet.

Les scripts de tests sont recommandés quand votre classe, pour être compilée, requiert que des extensions/programmes soient installés ou fonctionnent correctement. Enregistrez-les dans le sous répertoire 'tests'.

Est-ce que différents paquets ou classes avec des fonctionnalités similaires sont autorisées ?

Il n'y a pas de problèmes à ce que certains paquets soient concurrents. Cependant nous voulons éviter de nous retrouver avec une multitude de classes faisant la même chose mais avec des noms différents.

Premièrement, faîtes une vérification : Pourquoi est-ce que je veux vraiment commiter un nouveau paquet ? Les mauvaises raisons sont "Pour avoir mon nom dans PEAR" ou "Je ne comprends rien à la classe existante".

Par contre, s'il manque des fonctionnalités ce peut être une bonne raison d'ajouter une nouvelle classe. Dans ce cas avant de tout recoder, regardez si vous ne pourriez pas étendre la classe existante. Si ce n'est pas possible alors vous avez une bonne raison de commiter une nouvelle classe. "Que ce ne soit pas possible" signifie que vous ne pouvez pas ajouter vos fonctionnalités sans changer les bases de la classe existante.

Si vous écrivez une nouvelle classe, essayez de garder autant que possible une compatibilité avec l'API des classes existantes. éventuellement, réfléchissez à créer un wrapper (même si celui-ci demande de la mémoire) qui permettra une migration plus facile.

Si vous commitez une classe concurrente vous devez l'annoncer sur la liste de diffusion des développeurs PEAR !

Un paquetage que j'utilise inclut un paquetage dont j'ai également besoin. Dois-je l'inclure une seconde fois ?

Oui. Vous devez inclure tous les différents paquets dont vous avez besoin. Incluez-les avec les fonctions require_once() ou include_once() même s'ils sont inclus par un autre paquet.

Quelles licences sont autorisées dans PEAR/PECL?

Actuellement, PEAR support les licences suivantes :

  • PHP License

  • Apache License

  • LGPL

  • BSD style

  • MIT License

Les autres licences peuvent être ajoutées à cette liste au cas-par-cas. Merci de prendre contact avec la liste de diffusion des développeurs PEAR pour cela.

Les licenses autorisées sont choisies pour permettre l'intégration dans les sources fermées, les sources ouvertes mais aussi les applications commerciales. La seule limitation est que les crédits doivent rester dans les sources. Pour la LGPL, la license nécessite en plus que toutes les modifications au code source doivent être mises aussi sous LGPL.

De plus en plus, des personnes se plaignent de l'utilisation de paquets PEAR sous la license PHP dans du code GPL. Dans une discussion sur ce sujet, le créateur de PHP, Rasmus Lerdorf, a exprimé le sentiment suivant :

Tout dépend de ce que signifie le liage. La license PHP est très proche de la license Apache et ainsi, vous ne pouvez lier de la même façon du code GPL à Apache...

Voir http://www.apache.org/licenses/LICENSE-1.1.

La license PHP a été choisie pour correspondre à la license Apache car Apache et PHP sont trop fermés l'un l'autre.

L'arrachage de cheveux sur le liage et ces dérivations est présent depuis le début. Ma position est que vous pouvez fournir des composants PEAR sous license PHP sur le même CD ou dans le même fichier compressé que du code GPL car je le vois comme du travail d'agrégat. Ceci change si vous prenez du code PEAR, que vous le modifiez et que vous le copiez/collez directement dans votre propre code. Alors, ce travail passe d'un travail d'agrégat vers un travail dérivé. Mais le but des composants PEAR est d'être utilisés sous une forme d'agrégat. La license PHP vous autorise de l'utiliser aussi sous une forme dérivée mais alors, vous devez choisir une autre license que GPL pour ce travail.

La FSF a une FAQ sur l'agrégation ici : http://www.fsf.org/licensing/licenses/gpl-faq.html#MereAggregation

Ce texte traite de la compilation de logiciel, des exécutables et des espaces mémoires qui ne peuvent pas vraiment s'appliquer ici. Si vous ne désirez pas utiliser un composant PEAR comme agrégation, alors il est logique que vous ne pouvez pas non plus faire des appels à Apache dans votre code, donc, vous devez stipuler que personne ne peut utiliser votre code avec Apache. Je pense que c'est une extrème interprétation que quasi-personne ne partage ici...

En résumé, je ne vois pas d'issue ici. À suivre...

Notez que pour les extensions PECL qui sont liées à PHP, la licence utilisée doit être compatible avec la licence PHP. Cela signifie que vous ne pouvez pas rendre une extension PECL GPL sans violer la GPL. Notez aussi que si vous développez une extension qui lie une libraire GPL, vous violerez la GPL. Si vous devez utiliser une librairie GPL, demandez à son auteur l'autorisation d'utiliser sa bibliothèque sous une license compatible.

La license de tous les paquets PEAR/PECL peut être trouvée en haut de chaques fichiers du code source, sous la balise <license> du fichier de description du paquet (package.xml) mais aussi sur la page d'acceuil du paquet.

Pourquoi le standard de codage PEAR insiste sur l'indentation sur un seul espace ?

Utiliser des espaces et éviter les tabulations est la seule façon de s'assurer que les parties de codes seront affichées de la même manière sur tous les éditeurs ou visionneuses. De nombreux éditeurs associent la tabulation à 4 espaces mais d'autres terminaux ou visionneuses les associent à 8 espaces. Exemple:

printf("%s",
       $arg);

Ici, il y a 7 espaces avant "$args". Si ce code a été écrit dans un éditeur pour qui une tabulation représente 4 espaces, il sera stocké en tant qu'une tabulation et 3 espaces. Maintenant, si un autre développeur édite le même fichier dans un éditeur pour qui une tabulation représente 8 espaces, il ressemblera à cela :

printf("%s",
           $arg);

De même, considérer ce code écrit avec une tabulation représentant 8 espaces :

    if ($foo &&
        $bar) {
    }

Si vous le visualisez dans un éditeur pour qui une tabulation représente 4 espaces, il ressemblera à ceci :

    if ($foo &&
    $bar) {
    }

La communauté PEAR étant composée de très nombreuses personnes utilisant une multitude de systèmes et éditeurs, l'utilisation des tabulations n'est tout bonnement pas adaptée. L'utilisation des espaces est quant à elle plus universelle.

Jamie Zawinski a également écrit un article à ce sujet..

Il existe également un outil nommé Astyle qui convertit votre code au bon format.

FAQ Utilisateurs (Previous) FAQ Documentation/traduction (Next)
Last updated: Sun, 29 Aug 2010 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

Note by: doconnor
Astyle is alright, but the latest thing we use is PHP_CodeSniffer.