php shlex
1.0.0
Shlex est une extension PHP écrite en C. Cette extension implémente les fonctionnalités de la bibliothèque shlex en Python. Afin de familiariser les utilisateurs avec l'extension Shlex, la classe implémentée par l'extension est fondamentalement la même que la bibliothèque python shlex en termes de noms de propriétés et de méthodes. La documentation de l'interface est également modifiée à partir de la documentation de l'interface de la bibliothèque Python Shlex.
Le Shlex facilite l'écriture d'analyseurs lexicaux pour des syntaxes simples ressemblant à celles du shell Unix. Cela sera souvent utile pour écrire des mini-langages ou pour analyser des chaînes entre guillemets.
phpize
./configure
make && make install
Le système Windows n'est actuellement pas pris en charge.
Divisez la chaîne s en utilisant une syntaxe de type shell.
array shlex_split( string|resource|null $s [, bool $comments = false [, bool $posix = true ]] )
Divisez la chaîne s en utilisant une syntaxe de type shell.
Note:
Since the shlex_split() function instantiates a shlex instance, passing null for s will read the string to split from standard input.
Si comments est faux (valeur par défaut), l'analyse des commentaires dans la chaîne donnée sera désactivée (en définissant l'attribut commenters de l'instance shlex sur la chaîne vide).
Cette fonction fonctionne en mode POSIX par défaut, mais utilise le mode non-POSIX si l'argument posix est faux.
Renvoie un tableau de chaînes divisées.
<?php
$s = "foo#bar";
$ret = shlex_split($s, true);
var_dump($ret);
?>
L'exemple ci-dessus affichera :
array(1) {
[0] =>
string(3) "foo"
}
Renvoie une version échappée par le shell de la chaîne s.
string shlex_quote( string $s )
La chaîne à échapper.
La valeur renvoyée est une chaîne qui peut être utilisée en toute sécurité comme jeton dans une ligne de commande shell, dans les cas où vous ne pouvez pas utiliser de liste.
<?php
// If the output is executed, it will cause the index.php file to be deleted.
$filename = "somefile; rm -rf index.php";
$command = sprintf("ls -l %s", $filename);
echo $command;
echo "n";
// shlex_quote() blocked the vulnerability
$command = sprintf("ls -l %s", shlex_quote($filename));
echo $command;
echo "n";
// remote connection
$remoteCommand = sprintf("ssh home %s", shlex_quote($command));
echo $remoteCommand;
echo "n";
?>
L'exemple ci-dessus affichera :
ls -l somefile; rm -rf index.php
ls -l 'somefile; rm -rf index.php'
ssh home 'ls -l '"'"'somefile; rm -rf index.php'"'"''
Une instance ou une instance de sous-classe Shlex est un objet analyseur lexical.
Shlex implements Iterator {
/* Properties */
public resource|null $instream = null;
public string|null $infile = null;
private bool|null $posix = null;
public string|null $eof = null;
public string $commenters = '#';
public string $wordchars = 'abcdfeghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_';
public string $whitespace = " trn";
public bool $whitespaceSplit = false;
public string $quotes = ''"';
public string $escape = '\';
public string $escapedquotes = '"';
private string $state = ' ';
private array $pushback = [];
public int $lineno = 1;
public int $debug = 0;
public string $token = '';
private array $filestack = [];
public string|null $source = null;
public string|null $punctuationChars = null;
private array|null $_punctuationChars = null;
/* Methods */
public void function __construct( [ string|resource|null $instream = null [, string|null $infile = null [, bool $posix = false [, string|bool|null $punctuationChars = false ]]]]);
public void function __destruct( void );
public void function key( void );
public void function next( void );
public void function rewind( void );
public string|null function current( void );
public bool function valid( void );
public void function pushToken( string $tok );
public void function pushSource( string|resource $newstream, string|null $newfile = null );
public void function popSource( void );
public string|null|ShlexException function getToken( void );
public string|null|ShlexException function readToken( void );
public array function sourcehook( string $newfile );
public string function errorLeader( string $infile = null, int|null $lineno = null );
}
Le flux d'entrée à partir duquel cette instance Shlex lit les caractères.
Le nom du fichier d'entrée actuel, tel qu'initialement défini au moment de l'instanciation de la classe ou empilé par des requêtes sources ultérieures. Il peut être utile d'examiner cela lors de la construction de messages d'erreur.
Jeton utilisé pour déterminer la fin du fichier. Celui-ci sera défini sur la chaîne vide (''), en mode non-POSIX, et sur null en mode POSIX.
Chaîne de caractères reconnue comme commentaire débutant. Tous les caractères du début du commentaire à la fin de la ligne sont ignorés. Inclut uniquement « # » par défaut.
La chaîne de caractères qui s'accumulera dans des jetons à plusieurs caractères. Par défaut, inclut tous les caractères alphanumériques et traits de soulignement ASCII. En mode POSIX, les caractères accentués du jeu Latin-1 sont également inclus. Si ponctuationChars n'est pas vide, les caractères ~-./*?=, qui peuvent apparaître dans les spécifications de nom de fichier et les paramètres de ligne de commande, seront également inclus dans cet attribut, et tous les caractères qui apparaissent dans punktationChars seront supprimés des wordchars s'ils le sont. y être présent.
Caractères qui seront considérés comme des espaces et ignorés. Les espaces délimitent les jetons. Par défaut, inclut l'espace, la tabulation, le saut de ligne et le retour chariot.
Si c'est vrai, les jetons ne seront divisés qu'en espaces. Ceci est utile, par exemple, pour analyser les lignes de commande avec Shlex, en obtenant des jetons de la même manière que les arguments du shell. Si cet attribut est vrai, ponctuationChars n'aura aucun effet et le fractionnement se produira uniquement sur les espaces. Lors de l'utilisation de ponctuationChars, qui est destiné à fournir une analyse plus proche de celle implémentée par les shells, il est conseillé de laisser whitespaceSplit sur false (la valeur par défaut).
Caractères qui seront considérés comme des guillemets de chaîne. Le jeton s'accumule jusqu'à ce que le même guillemet soit rencontré à nouveau (ainsi, différents types de guillemets se protègent mutuellement comme dans le shell.) Par défaut, inclut les guillemets simples et doubles ASCII.
Des personnages qui seront considérés comme des évasions. Ceci ne sera utilisé qu'en mode POSIX et inclut simplement '' par défaut.
Caractères entre guillemets qui interpréteront les caractères d'échappement définis dans escape. Ceci n'est utilisé qu'en mode POSIX et inclut uniquement '"' par défaut.
Numéro de ligne source (nombre de nouvelles lignes vues jusqu'à présent plus un).
Si cet attribut est numérique et 1 ou plus, une instance Shlex imprimera une sortie de progression détaillée sur son comportement. Si vous avez besoin de l'utiliser, vous pouvez lire le code source du module pour connaître les détails.
Le tampon de jetons. Il peut être utile d'examiner cela lors de la détection d'exceptions.
Cet attribut est nul par défaut. Si vous lui attribuez une chaîne, cette chaîne sera reconnue comme une demande d'inclusion au niveau lexical similaire au mot-clé source dans divers shells. Autrement dit, le jeton immédiatement suivant sera ouvert en tant que nom de fichier et l'entrée sera extraite de ce flux jusqu'à EOF, moment auquel la méthode fclose() de ce flux sera appelée et la source d'entrée redeviendra le flux d'entrée d'origine. Les requêtes source peuvent être empilées sur n’importe quel nombre de niveaux.
Caractères qui seront considérés comme de la ponctuation. Les séries de caractères de ponctuation seront renvoyées sous la forme d'un seul jeton. Notez cependant qu'aucune vérification de validité sémantique ne sera effectuée : par exemple, '>>>' pourrait être renvoyé comme un jeton, même s'il n'est pas reconnu comme tel par les shells.
Constructeur
public void function Shlex::__construct( [ string|resource|null $instream = null [, string|null $infile = null [, bool $posix = false [, string|bool|null $punctuationChars = false ]]]])
L'argument instream, s'il est présent, spécifie où lire les caractères. Il doit s'agir d'une variable de type ressource (peut être lue par fread()) ou d'une chaîne. Si aucun argument n'est donné, l'entrée proviendra de php://stdin.
Le deuxième argument facultatif est une chaîne de nom de fichier, qui définit la valeur initiale de l'attribut infile. Si l’argument instream est nul, alors cet argument infile est toujours nul.
L'argument posix définit le mode opérationnel : lorsque posix est faux (par défaut), l'instance Shlex fonctionnera en mode de compatibilité. Lorsqu'il fonctionne en mode POSIX, Shlex essaiera d'être aussi proche que possible des règles d'analyse du shell POSIX.
L'argument ponctuationChars fournit un moyen de rendre le comportement encore plus proche de la façon dont les véritables shells analysent. Cela peut prendre plusieurs valeurs : la valeur par défaut, false. S'il est défini sur true, alors l'analyse des caractères ();<>|& est modifiée : toute série de ces caractères (considérés comme des caractères de ponctuation) est renvoyée sous la forme d'un seul jeton. S'il est défini sur une chaîne de caractères non vide, ces caractères seront utilisés comme caractères de ponctuation. Tous les caractères de l'attribut wordchars qui apparaissent dans ponctuationChars seront supprimés de wordchars.
Aucune valeur n'est renvoyée.
<?php
$instance = new Shlex("a && b || c", null, false, "|");
$list = [];
foreach ($instance as $value) {
$list[] = $value;
}
var_dump($list);
?>
L'exemple ci-dessus affichera :
array(6) {
[0] =>
string(1) "a"
[1] =>
string(1) "&"
[2] =>
string(1) "&"
[3] =>
string(1) "b"
[4] =>
string(2) "||"
[5] =>
string(1) "c"
}
Destructeur
public void function Shlex::__destruct( void )
Utilisé pour libérer les objets ressources détenus par les objets Shlex. En interne, fclose() est appelée pour fermer le descripteur de fichier.
Aucun paramètre.
Aucune valeur n'est renvoyée.
Aucun exemple.
Il n’y a aucune utilité pratique pour la méthode key de l’interface Iterator.
public void function Shlex::key( void )
Aucun paramètre.
Aucune valeur n'est renvoyée.
Aucun exemple.
Il n'y a aucune utilité pratique pour la méthode suivante de l'interface Iterator.
public void function Shlex::next( void )
Aucun paramètre.
Aucune valeur n'est renvoyée.
Aucun exemple.
Il n’y a aucune utilité pratique pour la méthode de rembobinage de l’interface Iterator.
public void function Shlex::rewind( void )
Aucun paramètre.
Aucune valeur n'est renvoyée.
Aucun exemple.
Renvoie la valeur du jeton lue par Shlex cette itération.
public string|null function Shlex::current( void )
Aucun paramètre.
Renvoie la valeur du jeton lue par Shlex cette itération.
Aucun exemple.
Déterminez si cette itération est valide.
public bool function Shlex::valid( void )
Aucun paramètre.
Valide si true est renvoyé, false n'est pas valide.
Note:
Due to the implementation of this class, iteratively reading the next element is also called inside the method. So the next() method is invalid.
Aucun exemple.
Poussez l'argument sur la pile de jetons.
public void function Shlex::pushToken( string $tok )
Le paramètre poussé.
Aucune valeur n'est renvoyée.
Aucun exemple.
Poussez un flux source d’entrée sur la pile d’entrée.
public void function Shlex::pushSource( string|resource $newstream, string|null $newfile = null );
Le flux source d’entrée en cours de transmission.
Si l'argument du nom de fichier est spécifié, il sera ensuite disponible pour être utilisé dans les messages d'erreur. Il s'agit de la même méthode utilisée en interne par la méthode sourcehook().
Aucune valeur n'est renvoyée.
Aucun exemple.
Extrayez la dernière source d'entrée poussée de la pile d'entrée. Il s'agit de la même méthode utilisée en interne lorsque le lexer atteint EOF sur un flux d'entrée empilé.
public void function Shlex::popSource( void )
Aucun paramètre.
Aucune valeur n'est renvoyée.
Aucun exemple.
Renvoyez un jeton.
public string|null|ShlexException function Shlex::getToken( void )
Aucun paramètre.
Si les jetons ont été empilés à l'aide de pushToken(), retirez un jeton de la pile. Sinon, lisez-en un dans le flux d’entrée. Si la lecture rencontre une fin de fichier immédiate, eof est renvoyé (la chaîne vide ('') en mode non-POSIX et null en mode POSIX).
Aucun exemple.
Lisez un jeton brut.
public string|null|ShlexException function Shlex::readToken( void )
Lisez un jeton brut. Ignorez la pile de refoulement et n'interprétez pas les requêtes source. (Ceci n'est généralement pas un point d'entrée utile et n'est documenté ici que par souci d'exhaustivité.)
Aucun paramètre.
Renvoie un jeton brut.
Aucun exemple.
public array function Shlex::sourcehook( string $newfile )
Lorsque Shlex détecte une requête source (voir source ci-dessous), cette méthode reçoit le jeton suivant comme argument et devrait renvoyer un tableau d'un nom de fichier et un objet de type fichier ouvert.
Normalement, cette méthode supprime d’abord toutes les guillemets de l’argument. Si le résultat est un chemin d'accès absolu, ou s'il n'y a pas eu de requête source précédente en vigueur, ou si la source précédente était un flux (comme php://stdin), le résultat est laissé tel quel. Sinon, si le résultat est un chemin d'accès relatif, la partie répertoire du nom du fichier immédiatement avant celui-ci sur la pile d'inclusion source est ajoutée au début (ce comportement est similaire à la façon dont le préprocesseur C gère #include "file.h").
Le résultat des manipulations est traité comme un nom de fichier et renvoyé comme premier composant du tuple, fopen() étant appelé pour produire le deuxième composant. (Remarque : il s'agit de l'ordre inverse des arguments lors de l'initialisation de l'instance !)
Ce hook est exposé afin que vous puissiez l'utiliser pour implémenter des chemins de recherche de répertoire, l'ajout d'extensions de fichiers et d'autres hacks d'espace de noms. Il n'y a pas de hook 'close' correspondant, mais une instance shlex appellera la méthode fclose() du flux d'entrée source lorsqu'elle retournera EOF.
Pour un contrôle plus explicite de l'empilement des sources, utilisez les méthodes pushSource() et popSource().
chemin du fichier.
Renvoie un tableau d'un nom de fichier et d'un objet de type fichier ouvert.
Aucun exemple.
Renvoie un leader du message d'erreur au format d'une étiquette d'erreur du compilateur Unix C.
public string function Shlex::errorLeader( string $infile = null, int|null $lineno = null )
Cette méthode génère un message d'erreur au format d'étiquette d'erreur du compilateur Unix C ; le format est '"%s", ligne %d: ', où %s est remplacé par le nom du fichier source actuel et %d par le numéro de ligne d'entrée actuel (les arguments facultatifs peuvent être utilisés pour les remplacer) .
Cette commodité est fournie pour encourager les utilisateurs de Shlex à générer des messages d'erreur dans le format standard analysable compris par Emacs et d'autres outils Unix.
Le nom du fichier source actuel.
Le numéro de ligne d’entrée actuel.
Renvoie un leader du message d'erreur au format d'une étiquette d'erreur du compilateur Unix C.
Aucun exemple.
Classe d'exception de Shlex
Cette classe est principalement utilisée pour les exceptions levées lorsque la classe Shlex effectue une erreur en interne.
ShlexException extends Exception {}
<?php
throw new ShlexException('No escaped character');
?>
