PHP Htaccess Parser
, (*1)
A lightweight PHP htaccess parser, (*2)
Introduction
PHP Htaccess Parser is a small lightweight library that can parse (or tokenize, if you prefer) an apache .htaccess file. It was developed for personal use to safely read and manipulate .htaccess files., (*3)
Features
The parser supports:, (*4)
- Directives (example:
Options -MultiViews)
- Blocks and subBlocks (example:
<IfModule mod_headers.c>)
- Multiline statements (lines ended with
/)
- White lines
- Comments
Installation
You can install it by cloning the git repository or using composer., (*5)
Git clone
git clone https://github.com/tivie/php-htaccess-parser.git
Composer
Add these lines to your composer.json:, (*6)
{
"require": {
"tivie/htaccess-parser": "*"
}
}
or run the following command:, (*7)
php composer.phar require tivie/htaccess-parser
How it works
Each line of the file .htaccess file is parsed and then converted into one of the following tokens:, (*8)
Each token implements TokenInterface provides a simple api to read and modify its properties., (*9)
Tokens are aggregated in an HtaccessContainer that can be used to add, modify or remove Token objects and dumping it as plain text or json., (*10)
Quick Usage guide
Using PHP Htaccess Parser is very simple., (*11)
$file = new \SplFileObject('path/to/.htaccess');
$parser = new \Tivie\HtaccessParser\Parser();
$htaccess = $parser->parse($file);
You can then use $htaccess to manipulate .htaccess contents., (*12)
$block = new Block();
$htaccess[0] = $block;
For instance, to print the first token of the file:, (*13)
echo $htaccess[0];
Casting a Token or an HtaccessContainer object to string returns a string representation of that element that can be used to recreate the .htaccess file., (*14)
$output = (string) $htaccess;
file_put_content('.htaccess', $htaccess);
Components
The Parser
The Parser class is the main component of the library. Since it's constructor doesn't require any mandatory argument, initializing a Parser object is very simple:, (*15)
$parser = new \Tivie\HtaccessParser\Parser();
Parser Options
The parser's behavior can be changed through the following methods and/or options:, (*16)
Setting the file
The parser uses \SplFileObject to access files. You can set the appropriate file in the constructor, by calling setFile() or as the first parameter of $parser->parse, (*17)
$parser = new Parser(new \SplObjectStorage('/path/to/file'));
$parser->setFile(new \SplObjectStorage('/path/to/file'));
$parser->parse(new \SplObjectStorage('/path/to/file'));
Changing the container
By default, $parser->parse() returns an HtaccessContainer object (which extends ArrayObject) that contains the newly tokenized .htaccess file. You can change the returned object by calling setContainer()method:, (*18)
$parser->setContainer($myContainer);
$myContainer can be an array or an object that implements ArrayAccess., (*19)
Use arrays
Each Token is an object that implements the TokenInterface, which presents several useful methods. However, if you prefer, you can instruct the parser to use simple arrays instead by either:, (*20)
- calling the method
useArrays()
$parser->useArrays(true);
- using the flag
USE_ARRAYS with the parse method.
$parser->parse(null, USE_ARRAYS);
You can instruct the parser to ignore WhiteLines, CommentLines or both by:, (*21)
- calling the respective method
$parser->ignoreWhiteLines(true)
->ignoreComments(true);
- or set it as a flag in
$parser->parse
$parser->parse(null, IGNORE_WHITELINES|IGNORE_COMMENTS);
Rewind file
By default, prior to serialization, the Parser rewinds the file pointer to the beginning. You can override this by calling the rewindFile method., (*22)
$parser->rewindFile(false);
Extending the Parser
The Parser class provides API points that developers can override. For more information, you can check the code at https://github.com/tivie/php-htaccess-parser/blob/master/src/Parser.php, (*23)
HtaccessContainer Object
The default returned object (HtaccessContainer) implements ArrayAccess, so you can access the definitions as you would with an array. The keys of this array are numeric and ordered by their appearance in the original file., (*24)
Retrieving a Token
Since the Parser returns an array or an array like object, you can retrieve a specific token by its index:, (*25)
$firstToken = $htaccess[0];
You can also use the search method to find a specific token by its name:, (*26)
$modRewrite = $htaccess->search('modRewrite');
You can constrain the search to a specific token type., (*27)
$modRewrite = $htaccess->search('modRewrite', \Tivie\HtaccessParser\Token\TOKEN_BLOCK);
Modifying a Token
TokenInterface provides a common API that you can use to manipulate the tokens., (*28)
$token->setName('fooBar'); //Changes the name of the Token
$token->setArguments('foo', 'bar', 'baz'); //Changes the Token arguments
Keep in mind, however, that with some tokens, an array of arguments doesn't make much sense. For instance, Comments Tokens only expect 1 argument (the actual text of the comment) while WhiteLine Tokens expect none so extra arguments will be silently ignored., (*29)
Adding a Token
You can add a token by simply creating and appending it., (*30)
$newBlock = new Block('modRewrite');
$htaccess[] = $block;
You can also insert a Token into a specific index using insertAt:, (*31)
$newBlock = new Block('modRewrite');
$htaccess->insertAt(4, $newBlock);
Outputting htaccess
In order to output an .htaccess txt file, you can cast the HtaccessContainer to string and write the resulting string to a file:, (*32)
$output = (string) $htaccess;
file_put_content('.htaccess', $output);
You can also use the method txtSerialize to control how the output should be formatted:, (*33)
$output = $htaccess->ignoreWhiteLines(true)
->ignoreComments(false);
file_put_content('.htaccess', $output);
NOTE: Keep in mind that ignored elements in the parser won't be available to HtaccessContainer serialize methods., (*34)
Contribute
Feel free to contribute by forking or making suggestions., (*35)
Issue tracker: https://github.com/tivie/php-htaccess-parser/issues, (*36)
Source code: https://github.com/tivie/php-htaccess-parser, (*37)
License
PHP Htaccess Parser is released under Apache 2.0 license. For more information, please consult the LICENSE file in this repository or http://www.apache.org/licenses/LICENSE-2.0.txt., (*38)
Wallogit.com
