Skip to content

Commit 205dba6

Browse files
codemashercodemasher
committed
✨
1 parent 4176c20 commit 205dba6

File tree

1 file changed

+56
-64
lines changed

1 file changed

+56
-64
lines changed

‎README.md

Lines changed: 56 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,63 @@
1+
# chillerlan/php-bbcode
2+
3+
A recursive regexp [BBCode](http://en.wikipedia.org/wiki/BBCode) parser for PHP 7+ using [preg_replace_callback()](http://php.net/preg_replace_callback),
4+
based on an example by [MrNiceGuy](http://www.developers-guide.net/forums/member/69,mrniceguy) on
5+
[developers-guide.net](http://www.developers-guide.net/c/152-bbcode-parser-mit-noparse-tag-selbst-gemacht.html).
6+
Handles nested tags as well as matching brackets and doesn't stumble across invalid tags.
7+
18
[![version][packagist-badge]][packagist]
29
[![license][license-badge]][license]
310
[![Travis][travis-badge]][travis]
411
[![Coverage][coverage-badge]][coverage]
512
[![Scrunitizer][scrutinizer-badge]][scrutinizer]
6-
[![CodeClimate][codeclimate-badge]][codeclimate]
7-
[![GitterChat][gitter-badge]][gitter]
8-
9-
[packagist-badge]: https://img.shields.io/packagist/v/chillerlan/bbcode.svg
10-
[packagist]: https://packagist.org/packages/chillerlan/bbcode
11-
[license-badge]: https://img.shields.io/packagist/l/chillerlan/bbcode.svg
12-
[license]: https://github.com/codemasher/php-bbcode/blob/master/LICENSE
13-
[travis-badge]: https://img.shields.io/travis/codemasher/php-bbcode.svg
14-
[travis]: https://travis-ci.org/codemasher/php-bbcode
15-
[coverage-badge]: https://img.shields.io/codecov/c/github/codemasher/php-bbcode.svg
16-
[coverage]: https://codecov.io/github/codemasher/php-bbcode
17-
[scrutinizer-badge]: https://img.shields.io/scrutinizer/g/codemasher/php-bbcode.svg
18-
[scrutinizer]: https://scrutinizer-ci.com/g/codemasher/php-bbcode
19-
[codeclimate-badge]: https://img.shields.io/codeclimate/github/codemasher/php-bbcode.svg
20-
[codeclimate]: https://codeclimate.com/github/codemasher/php-bbcode
21-
[gitter-badge]: https://img.shields.io/gitter/room/nwjs/nw.js.svg
22-
[gitter]: https://gitter.im/chillerlan/bbcode
23-
24-
# chillerlan/bbcode
25-
26-
A recursive regexp [BBCode](http://en.wikipedia.org/wiki/BBCode) parser using [preg_replace_callback()](http://php.net/preg_replace_callback),
27-
based on an example by [MrNiceGuy](http://www.developers-guide.net/forums/member/69,mrniceguy) on
28-
[developers-guide.net](http://www.developers-guide.net/c/152-bbcode-parser-mit-noparse-tag-selbst-gemacht.html).
29-
Handles nested tags aswell as matching brackets and doesn't stumble across invalid tags.
30-
31-
## Requirements
32-
- PHP 7 ([PHP 5.6+ compatible branch](https://github.com/codemasher/php-bbcode/tree/php5))
33-
34-
----
35-
36-
## Documentation
37-
### API
38-
The API docs can be found [over here on github.io](http://codemasher.github.io/docs/) (auto generated from the
39-
source, using [phpDocumentor](http://www.phpdoc.org/)).
40-
41-
### BBCode docs
42-
A documentation of the included BBCodes is planned and will be available on [the wiki](https://github.com/codemasher/php-bbcode/wiki).
43-
44-
### Installation
45-
#### Using [composer](https://getcomposer.org)
46-
47-
*Terminal*
48-
```sh
49-
composer require chillerlan/bbcode:dev-master
50-
```
51-
52-
*composer.json*
13+
[![Packagist downloads][downloads-badge]][downloads]
14+
[![PayPal donate][donate-badge]][donate]
15+
16+
[packagist-badge]: https://img.shields.io/packagist/v/chillerlan/php-bbcode.svg?style=flat-square
17+
[packagist]: https://packagist.org/packages/chillerlan/php-bbcode
18+
[license-badge]: https://img.shields.io/github/license/chillerlan/php-bbcode.svg?style=flat-square
19+
[license]: https://github.com/chillerlan/php-bbcode/blob/master/LICENSE
20+
[travis-badge]: https://img.shields.io/travis/chillerlan/php-bbcode.svg?style=flat-square
21+
[travis]: https://travis-ci.org/chillerlan/php-bbcode
22+
[coverage-badge]: https://img.shields.io/codecov/c/github/chillerlan/php-bbcode.svg?style=flat-square
23+
[coverage]: https://codecov.io/github/chillerlan/php-bbcode
24+
[scrutinizer-badge]: https://img.shields.io/scrutinizer/g/chillerlan/php-bbcode.svg?style=flat-square
25+
[scrutinizer]: https://scrutinizer-ci.com/g/chillerlan/php-bbcode
26+
[downloads-badge]: https://img.shields.io/packagist/dt/chillerlan/php-bbcode.svg?style=flat-square
27+
[downloads]: https://packagist.org/packages/chillerlan/php-bbcode/stats
28+
[donate-badge]: https://img.shields.io/badge/donate-paypal-ff33aa.svg?style=flat-square
29+
[donate]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WLYUNAT9ZTJZ4
30+
31+
# Requirements
32+
- PHP 7+ ([PHP 5.6+ compatible branch](https://github.com/chillerlan/php-bbcode/tree/php5))
33+
34+
# Documentation
35+
## BBCode docs
36+
A documentation of the included BBCodes is planned and will be available soon™ on [the wiki](https://github.com/chillerlan/php-bbcode/wiki).
37+
38+
## Installation
39+
**requires [composer](https://getcomposer.org)**
40+
41+
### *composer.json*
42+
(note: replace `dev-master` with a [version boundary](https://getcomposer.org/doc/articles/versions.md#summary))
5343
```json
5444
{
5545
"require": {
5646
"php": ">=7.0.3",
57-
"chillerlan/bbcode": "dev-master"
47+
"chillerlan/php-bbcode": "dev-master"
5848
}
5949
}
6050
```
6151

62-
#### Manual installation
63-
Download the desired version of the package from [master](https://github.com/codemasher/php-bbcode/archive/master.zip) or
64-
[release](https://github.com/codemasher/php-bbcode/releases) and extract the contents to your project folder.
65-
Point the namespace `chillerlan/bbcode` to the folder `src` of the package.
52+
### Manual installation
53+
Download the desired version of the package from [master](https://github.com/chillerlan/php-bbcode/archive/master.zip) or
54+
[release](https://github.com/chillerlan/php-bbcode/releases) and extract the contents to your project folder. After that:
55+
- run `composer install` to install the required dependencies and generate `/vendor/autoload.php`.
56+
- if you use a custom autoloader, point the namespace `chillerlan\Database` to the folder `src` of the package
6657

6758
Profit!
6859

69-
### Usage
60+
## Usage
7061
First of all, you'll need to import the needed classes of course:
7162
```php
7263
namespace MyProject;
@@ -75,7 +66,7 @@ use chillerlan\bbcode\Parser;
7566
use chillerlan\bbcode\ParserOptions;
7667
```
7768

78-
#### Parser options
69+
### Parser options
7970
In order to create a `Parser` instance, you'll first want to create an instance of `ParserOptions` and alter it if needed.
8071
However, this step is optional (meta, eh?).
8172
```php
@@ -91,7 +82,7 @@ $options->allowed_tags = ['mybbcode', 'somebbcode', 'whatever'];
9182
$options->allow_all = false;
9283
```
9384

94-
#### Parser
85+
### Parser
9586
Now we're ready to create the `Parser`:
9687
```php
9788
$bbcode = new Parser($options);
@@ -120,8 +111,8 @@ $module_tags = array_keys($bbcode->getTagmap(), MyAwesomeModule::class);
120111

121112
That's all!
122113

123-
### Extend the parser
124-
#### Base module
114+
## Extend the parser
115+
### Base module
125116
In order to create your own modules, you'll first need an empty base module which contains
126117
all basic settings and methods for each module. To do so, you'll need to extend
127118
`\chillerlan\bbcode\Modules\BaseModuleAbstract` . There's really not much to do, the only and most
@@ -148,7 +139,7 @@ class MyAwesomeBaseModule extends BaseModuleAbstract{
148139
}
149140
```
150141

151-
#### Encoder module
142+
### Encoder module
152143
Now that we have our base module, we're able to create the encoder module, where the actual transform happens.
153144
Each encoder module extends a base module depending on output type (`MyAwesomeBaseModule` here)
154145
and implements `\chillerlan\bbcode\Modules\ModuleInterface`. The property `$tags` and the method `__transform()` are mandatory.
@@ -194,7 +185,7 @@ class MyAwesomeModule extends Simpletext implements ModuleInterface{
194185
}
195186
```
196187

197-
#### Parser extension
188+
### Parser extension
198189
The parser features an extension which allows you to alter the bbcode during the parsing process,
199190
namely before and after the main parser unit runs. If you want to create your own parser extension,
200191
just implement `\chillerlan\bbcode\ParserExtensionInterface`, set it in the parser options and you're done.
@@ -226,15 +217,16 @@ class MyAwesomeParserExtension implements ParserExtensionInterface{
226217

227218
}
228219
```
229-
#### Language
230-
231-
### Notes
220+
### Language
221+
- @todo
222+
223+
## Notes
232224
The parser may cause some high CPU load, depending on the input. You should never consider to use it somewhere
233225
in your output subsystem - not even with strong caching. Encode on input - you'll want a preview anyway. ;)
234226

235227
You may also run into several bugs. In fact, the BBCoder is essentially a tool to squeeze out any PCRE related bug in PHP known to man (and perhaps unknown). Have fun! ;)
236-
[It is highly recommended to use these php.ini settings](https://github.com/codemasher/php-bbcode/blob/master/travis-php.ini), especially to disable the PCRE JIT in PHP7 which is a troublemaker.
228+
[It is highly recommended to use these php.ini settings](https://github.com/chillerlan/php-bbcode/blob/master/travis-php.ini), especially to disable the PCRE JIT in PHP7 which is a troublemaker.
237229
In case you happen to run into a PCRE related bug, i ask you to open an issue over here along with the bbcode which caused the error and further information.
238230

239-
### Disclaimer!
231+
## Disclaimer!
240232
I don't take responsibility for molten CPUs, smashed keyboards, broken HTML etc.. Use at your own risk!

0 commit comments

Comments
 (0)