Subversion Repositories php-qbpwcf

# Example: Plugin system

In this example I will show you how to create a generic plugin system with
événement where plugins can alter the behaviour of the app. The app is a blog.
Boring, I know. By using the EventEmitter it will be easy to extend this blog
with additional functionality without modifying the core system.

The blog is quite basic. Users are able to create blog posts when they log in.
The users are stored in a static config file, so there is no sign up process.
Once logged in they get a "new post" link which gives them a form where they
can create a new blog post with plain HTML. That will store the post in a
document database. The index lists all blog post titles by date descending.
Clicking on the post title will take you to the full post.

## Plugin structure

The goal of the plugin system is to allow features to be added to the blog
without modifying any core files of the blog.

The plugins are managed through a config file, `plugins.json`. This JSON file
contains a JSON-encoded list of class-names for plugin classes. This allows
you to enable and disable plugins in a central location. The initial
`plugins.json` is just an empty array:
```json
[]
```

A plugin class must implement the `PluginInterface`:
```php
interface PluginInterface
{
    function attachEvents(EventEmitterInterface $emitter);
}
```

The `attachEvents` method allows the plugin to attach any events to the
emitter. For example:
```php
class FooPlugin implements PluginInterface
{
    public function attachEvents(EventEmitterInterface $emitter)
    {
        $emitter->on('foo', function () {
            echo 'bar!';
        });
    }
}
```

The blog system creates an emitter instance and loads the plugins:
```php
$emitter = new EventEmitter();

$pluginClasses = json_decode(file_get_contents('plugins.json'), true);
foreach ($pluginClasses as $pluginClass) {
    $plugin = new $pluginClass();
    $pluginClass->attachEvents($emitter);
}
```

This is the base system. There are no plugins yet, and there are no events yet
either. That's because I don't know which extension points will be needed. I
will add them on demand.

## Feature: Markdown

Writing blog posts in HTML sucks! Wouldn't it be great if I could write them
in a nice format such as markdown, and have that be converted to HTML for me?

This feature will need two extension points. I need to be able to mark posts
as markdown, and I need to be able to hook into the rendering of the post body
and convert it from markdown to HTML. So the blog needs two new events:
`post.create` and `post.render`.

In the code that creates the post, I'll insert the `post.create` event:
```php
class PostEvent
{
    public $post;

    public function __construct(array $post)
    {
        $this->post = $post;
    }
}

$post = createPostFromRequest($_POST);

$event = new PostEvent($post);
$emitter->emit('post.create', [$event]);
$post = $event->post;

$db->save('post', $post);
```

This shows that you can wrap a value in an event object to make it mutable,
allowing listeners to change it.

The same thing for the `post.render` event:
```php
public function renderPostBody(array $post)
{
    $emitter = $this->emitter;

    $event = new PostEvent($post);
    $emitter->emit('post.render', [$event]);
    $post = $event->post;

    return $post['body'];
}

<h1><?= $post['title'] %></h1>
<p><?= renderPostBody($post) %></p>
```

Ok, the events are in place. It's time to create the first plugin, woohoo! I
will call this the `MarkdownPlugin`, so here's `plugins.json`:
```json
[
    "MarkdownPlugin"
]
```

The `MarkdownPlugin` class will be autoloaded, so I don't have to worry about
including any files. I just have to worry about implementing the plugin class.
The `markdown` function represents a markdown to HTML converter.
```php
class MarkdownPlugin implements PluginInterface
{
    public function attachEvents(EventEmitterInterface $emitter)
    {
        $emitter->on('post.create', function (PostEvent $event) {
            $event->post['format'] = 'markdown';
        });

        $emitter->on('post.render', function (PostEvent $event) {
            if (isset($event->post['format']) && 'markdown' === $event->post['format']) {
                $event->post['body'] = markdown($event->post['body']);
            }
        });
    }
}
```

There you go, the blog now renders posts as markdown. But all of the previous
posts before the addition of the markdown plugin are still rendered correctly
as raw HTML.

## Feature: Comments

TODO

## Feature: Comment spam control

TODO