protonlabs / libsieve-php
libsieve-php is a library to manage and modify sieve (RFC5228) scripts.
Installs: 56 649
Dependents: 0
Suggesters: 0
Security: 0
Stars: 21
Watchers: 24
Forks: 7
Open Issues: 4
Requires
- php: >=8.0
- ext-mbstring: *
- ext-simplexml: *
Requires (Dev)
- phpunit/phpunit: ^9
- protonlabs/php-coding-standard: ^4.0
- squizlabs/php_codesniffer: ^3.5
- vimeo/psalm: ^4.22
This package is auto-updated.
Last update: 2024-10-26 18:12:12 UTC
README
libsieve-php is a library to manage and modify sieve (RFC5228) scripts. It contains a parser for the sieve language (including extensions) and a client for the managesieve protocol.
This project is adopted from the discontinued PHP sieve library available at https://sourceforge.net/projects/libsieve-php.
Changes from the RFC
- The
date
and thecurrentdate
both allow forzone
parameter any string to be passed. This allows the user to enter zone names likeEurope/Zurich
instead of+0100
. The reason we allow this is because offsets like+0100
don't encode information about the daylight saving time, which is often needed.
Usage examples
The libsieve parses a sieve script into a tree. This tree can then be used to interpret its meaning.
Two example will be provided: one basic and one more complex.
Basic Example: Check if an extension is loaded
In this first example, we will check if a specific extension was loaded through a require node:
<?php use Sieve\SieveParser; class ExtensionCheckExample { /** @var \Sieve\SieveTree the tree, obtained from the SieveParser */ protected $tree; /** * Parser constructor. * * @param string $sieve the sieve script to read. */ public function __construct(string $sieve) { $parser = new SieveParser(); try { $parser->parse($sieve); } catch (\Sieve\SieveException $se) { throw new \Exception("The provided sieve script is invalid!"); } // we store the tree, because it contains all the information. $this->tree = $parser->GetParseTree(); } /** * Checks if an extension is loaded. * * @param string $extension * @return bool */ public function isLoaded(string $extension) { /** @var int $root_node_id */ $root_node_id = $this->tree->getRoot(); // The root is not a node, we can only access its children $children = $this->tree->getChildren($root_node_id); foreach ($children as $child) { // The child is an id to a node, which can be access using the following: $node = $this->tree->getNode($child); // is can be used to check the type of node. if ($node->is(\Sieve\SieveToken::IDENTIFIER) && $node->text === "require") { if ($this->checkChildren($this->tree->getChildren($child), $extension)) { return true; } } } return false; } /** * Checks the arguments given to a require node, to know if it includes * * @param $children * @param string $extension * @return bool */ private function checkChildren($children, string $extension): bool { if (is_array($children)) { // it's a string list, let's loop over them. foreach ($children as $child) { if ($this->checkChildren($child, $extension)) { return true; } } return false; } $node = $this->tree->getNode($children); return $node->is(\Sieve\SieveToken::QUOTED_STRING) && $extension === trim($node->text, '"'); } } // load a script, from the tests folder. $sieve = file_get_contents(__DIR__ . './tests/good/currentdate.siv'); $runner = new ExtensionCheckExample($sieve); var_dump($runner->isLoaded("variables"));
Complex Example: Dumping the tree
This second example will print back the sieve script from a parsed tree (note this could simply be done through
the method $tree->dump()
).
<?php use Sieve\SieveParser; use Sieve; class UsageExample { /** @var \Sieve\SieveTree the tree, obtained from the SieveParser */ protected $tree; /** * Parser constructor. * * @param string $sieve the sieve script to read. */ public function __construct(string $sieve) { $parser = new SieveParser(); try { $parser->parse($sieve); } catch (\Sieve\SieveException $se) { throw new \Exception("The provided sieve script is invalid!"); } // we store the tree, because it contains all the information. $this->tree = $parser->GetParseTree(); } /** * Displays the tree */ public function display() { /** @var int $root_node_id */ $root_node_id = $this->tree->getRoot(); // The root is not a node, we can only access its children $children = $this->tree->getChildren($root_node_id); $this->displayNodeList($children); } /** * Loop over a list of nodes, and display them. * * @param int[] $nodes a list of node ids. * @param string $indent */ private function displayNodeList(array $nodes, string $indent = '') { foreach ($nodes as $node) { $this->displayNode($node, $indent); } } /** * Display a node and its children. * * @param int $node_id the current node id. * @param string $indent */ private function displayNode(int $node_id, string $indent) { /** * @var \Sieve\SieveToken $node can be used to get info about a specific node. */ $node = $this->tree->getNode($node_id); // All the possible node types are listed as constants in the class SieveToken... switch ($node->type) { case \Sieve\SieveToken::SCRIPT_END: printf($indent . "EOS"); break; case Sieve\SieveToken::WHITESPACE: case Sieve\SieveToken::COMMENT: break; default: // the $node->type is a integer. It can be turned into an explicit string this way... $type = \Sieve\SieveToken::typeString($node->type); $open_color = ''; $end_color = ''; // The type of a node can be checked with the is method. Mask can be used to match several types. if ($node->is(\Sieve\SieveToken::QUOTED_STRING | Sieve\SieveToken::MULTILINE_STRING)) { // we want to put a specific color arround strings... $open_color = "\e[1;32;47m"; $end_color = "\e[0m"; } // The children of a node can be obtain through this method: $children = $this->tree->getChildren($node_id); // do whatever you want with a node and its children :) Here we are going to display them. printf("[%4d, %-10.10s (%5d) ]%s ${open_color}%s$end_color" . PHP_EOL, $node->line, $type, $node->type, $indent, $node->text); $this->displayNodeList($children, $indent . "\t"); } } } $sieve = file_get_contents(__DIR__ . '/tests/good/currentdate.siv'); $parser = new UsageExample($sieve); $parser->display();