DEV Community: Sebastian Schürmanns

Multilingual Websites Are Hard — AI Finally Makes Them Practical

Sebastian Schürmanns — Mon, 05 Jan 2026 14:34:07 +0000

I’ve been maintaining my open-source flat-file CMS Typemill for more than eight years. During all that time, one feature request never changed: When will Typemill support multilingual websites?

The reason it took so long is simple: multilingual support is one of the hardest features to implement in a flat-file CMS. That’s also why only a handful of flat-file CMSs really support multilingual websites today, such as Kirby, Statamic, Grav, or Automad.

Different architectures, different trade-offs

Flat-file CMSs solve multilingual websites in very different ways. Some systems, like Grav, store language variants directly inside the same page folder. This makes switching languages straightforward and keeps pages naturally connected.

Typemill, however, follows a different approach. It builds a full index of all pages to manage navigation, deeply nested content structures, and drag-and-drop ordering. This makes content structuring very flexible — but it also means that different languages cannot simply live side by side in the same folder.

Projects instead of folders

The solution I ended up with was introducing projects. Each project has:

Its own content space
Its own navigation
Its own logic and index

Projects were not originally designed for multilingual websites — they were an unplanned first step. It quickly turned out that they are useful in general. Since Typemill can also publish websites as PDF books or EPUB files, projects can also be used to manage multiple publications within a single installation.

For multilingual websites, projects turned out to be a natural fit. Each language becomes its own project — isolated, clean, and independently manageable — while still being part of the same system. All that’s needed is a global index that keeps track of how language variants are linked to each other.

The missing piece: AI translation

Even with a solid structure, one major problem remained: translation workflow.

Copying pages, translating articles, and updating metadata manually works for small websites. But it consumes a lot of time and quickly breaks down as a project grows.

One big advantage of flat-file CMSs compared to database-driven systems is their use of simple Markdown files. Markdown is also the native output format for nearly all LLM services and APIs. This makes integrating AI services into flat-file CMSs surprisingly straightforward. Using this advantage to automate translations is, frankly, a no-brainer.

Typemill already integrated AI services through a separate interface called Kixote. To fully automate translations, you simply activate a checkbox. When you create a new language page, Typemill copies the original content into the target language project and performs one additional step: it sends the content to an AI service and stores the translated response.

That’s it.

Currently, auto-translation only runs when a translation page is created. If the original content changes later, translations still need to be updated manually. But that’s a comparatively small next step.

Final thoughts

Multilingual support in flat-file CMSs has always been a hard problem — structurally, conceptually, and operationally. AI doesn’t solve every issue, but it removes the biggest pain point: repetitive manual work. In my view, if you’re building tools for content creators today, multilingual support should at least include an option to automate translations.

Watch the walkthrough

I created a short 5-minute demo video that shows how easy it is to set up a multilingual website with Typemill using this approach:

If you’re curious to learn more, visit the Typemill website:

https://typemill.net

Archiving Your ChatGPT History in Markdown

Sebastian Schürmanns — Fri, 01 Aug 2025 11:38:44 +0000

You probably know that you can download your whole chat history from ChatGPT, right? The export gives you a .zip file containing a massive JSON file and a big HTML file.

That’s fine for backup, but not great if you want to actually use your data — for example, to:

Search across past conversations
Organize chats by topic
Build a personal knowledge base
Feed chats into a RAG pipeline
Clean up conversations for documentation

So I built a plugin for Typemill, a small self-hosted CMS that stores content as Markdown files. The plugin lets you import your full ChatGPT archive and convert it into clean, editable Markdown pages.

The Setup: Typemill + Plugin

Typemill is a lightweight, open-source CMS built specifically for documentation and structured content. It stores each page as a Markdown file on your server — no database needed. It’s ideal for knowledge bases, manuals, or project notes. To get started, read the quick guide in the documentation.

You can then download the ChatGPT Archive plugin from the plugin page, put it into the plugin folder of Typemill, and activate it in the interface.

What the Plugin Does

Once you download your .zip archive from OpenAI, the plugin lets you:

Upload the archive directly from the Typemill backend
View and select individual conversations from the archive
Choose how to sort them (chronologically or by topic)
Convert selected chats into Markdown pages

The result: the chats are saved as editable Markdown pages in Typemill on your own server.

What’s Next?

You can run Typemill as a simple archive, or use the Markdown files for any other pipeline. You can also create a knowledge base based on your chats like this:

Move important chats into new folders and build your own private, structured knowledge base
Use Typemill’s AI interface (Kixote) to summarize or extract information from chats
Create a prompt library to reuse prompts across topics

This plugin is completely free and available here. If you’ve done something similar with other tools (like Obsidian, Notion, or static site generators), I’d love to hear how you approached it.

Let me know if you find it useful or run into issues!

Markdown Everywhere: Why Flat-File CMS Should Be on the Rise Again

Sebastian Schürmanns — Fri, 14 Feb 2025 14:32:40 +0000

Markdown: The Language of the AI Age

Markdown has quietly become the dominant format in the age of AI. Large Language Models (LLMs) process Markdown natively, making it the standard format for AI-generated content. From OpenAI’s ChatGPT to local LLMs, Markdown is the default for structured text, code snippets, and formatting.

Developers have long embraced Markdown for its simplicity and portability. Now, with AI-driven workflows becoming mainstream, Markdown is moving beyond tech communities and into broader content management.

The Decline of Flat-File CMS

Flat-File CMS had their golden era around 2020. They offered lightweight, database-free content management, making them ideal for small projects. However, their popularity waned as headless CMS and SaaS-based content platforms took over.

Many developers turned to API-driven solutions like Contentful or Strapi, prioritizing scalability and structured content delivery over simplicity. Meanwhile, traditional CMS like WordPress continued to dominate, even integrating REST and GraphQL APIs to stay relevant.

Why Flat-File CMS Could Make a Comeback

The landscape is shifting again, and several trends suggest Flat-File CMS might be due for a resurgence:

AI-Generated Content Needs a Simple Format

AI tools generate Markdown natively, making it easier to integrate Markdown-first CMS solutions into modern content workflows.
Privacy and Data Ownership

With increasing concerns about cloud-based services, self-hosted solutions are regaining interest. Flat-File CMS offers full control over content without vendor lock-in.
Speed and Efficiency

Flat-File CMS remains one of the fastest ways to serve content, especially for smaller websites.
No Dependencies, No Complexity

Unlike headless CMS that require a backend and API layers, Flat-File CMS work out of the box with just a filesystem and Markdown files.
Decentralized Content Creation

More teams are embracing Git-based workflows for content collaboration. Flat-File CMS aligns well with this trend, as Markdown files can be versioned and managed in Git repositories.

Some Great Flat-File CMS Options

Although Flat-File CMS are no longer trending like they once were, many have quietly evolved into powerful solutions. There are both feature-rich systems for advanced users and smaller niche projects for lightweight needs. Here are some of the best options:

Kirby CMS (Commercial) – A highly flexible and lightweight system with an excellent user interface and unlimited features. Ideal for professional web developers who prefer minimal dependencies and a well-designed UI.
Statamic CMS (Commercial) – A great choice for Laravel developers. Originally lightweight, but now a full-fledged CMS with advanced features like form builders, GraphQL, and REST APIs. If you worked with Expression Engine or Craft CMS - you will feel familiar because they have the same roots.
Grav CMS (Open Source) – The most well-known open-source Flat-File CMS with a large ecosystem of plugins and themes. While it may have missed some recent trends like built-in API or headless support, it still boasts the biggest community.
Typemill (Open Source + Premium) – My own project, actively developed for 8 years. While it doesn’t focus on layout flexibility, it works perfect for documentation, knowledge bases, and other informational websites. API support is included, and AI integration is in progress.
Automad (Open Source) – A visually stunning Flat-File CMS with impressive layout options. It feels like a lightweight, self-hosted website builder – perfect for design-centric projects.
Bludit (Open Source) – A great general-purpose Flat-File CMS, ideal for simple websites like portfolios. While development has slowed recently, it still offers everything needed for small-scale projects.
HTMLy (Open Source) – My favorite pick for small, ultra-simple blogs. It’s not a “5-minute setup” CMS – it’s a “5-second setup” CMS.
Yellow (Open Source) – A unique and quirky project that has been in active development for years. If you love niche, independent projects, check it out!

There are more Flat-File CMS out there, but these are my favorites. If you're curious, just explore – you'll find plenty of great options!

Open Source Needs a New Business Model – What if AI Could Help?

Sebastian Schürmanns — Wed, 12 Feb 2025 18:35:06 +0000

Maintaining an open-source project is tough. Finding a sustainable way to fund it? Even tougher.

I’ve been running Typemill, a small flat-file CMS for publishing documentation and handbooks, for eight years now. Last year, I introduced paid plugins as a way to support development. It hasn't worked well. Let’s be honest – competing with massive plugin ecosystems is nearly impossible for smaller projects.

But maybe a massive plugin ecosystem won’t even matter in the future.

What if we rethink the model?

When ChatGPT first launched, I immediately tried using it to generate Typemill plugins. It failed badly, probably because Typemill is too small and niche for the AI to understand.

But things are evolving.

AI-assisted software generation is already making waves – just look at Lovable and similar tools. These services are already shifting the paradigm from "buy" to "make" in many companies. Open-source software could serve as a perfect foundation for such custom solutions.

What if, instead of selling pre-built plugins, open-source projects offered AI-powered customization services?

Users get exactly what they need, tailored to their setup – without waiting for developers to create and sell the perfect plugin.
Open-source maintainers get a sustainable revenue stream beyond traditional donations or sponsorships.

If I Could Build the Perfect Service...

Imagine an AI-powered open-source development service that works like a software reseller (e.g., Paddle):

Maintainers set up an AI coding assistant, trained specifically for their project.
Users pay to access AI-generated customizations, making it easier to adapt the software to their needs.
The open-source project earns revenue while staying lean and flexible.

Could this work?

Honestly, I don’t know, and we are probably not at this point yet. But it feels like a model worth exploring. AI-assisted coding is improving fast, and this approach could make open-source projects more adaptable, financially viable, and easier to maintain.

What do you think? Have you seen services like this? Let’s discuss!

Crosspost to DEV community with Typemill

Sebastian Schürmanns — Thu, 07 May 2020 07:29:04 +0000

This article was originally published on trendschau.net, but you will probably read it on dev.to first. How come?

Some weeks ago a dev-user asked other members how they crosspost their markdown articles to the dev-platform. Since I develop a small flat-file cms called Typemill that works with markdown, I asked myself if it is worth to create a little plugin for such crossposts. I checked the dev-API, wrote about 200 lines of code and voila: The first crosspost is online.

This is a screenshot of the Typemill admin-ui for this article:

The plugin adds a new tab called "dev.to" to each article and in that tab you can manage the crosspost. You can activate the crosspost, you can choose between draft or publish and you can add tags or series. The plugin will synchronise the articles (and rewrite the image-urls) whenever you publish or update the article on Typemill. It will also store and display the response from dev.to and display a little preview.

It is pretty simple to create a plugin like this with Typemill:

All you need is a YAML-file, a small vue-component and a php-file with some logic.
With the YAML-file you can define the forms and fields for your tab.
With the vue-component you can render the tab and also add the vue-logic that you want.
With the php-file you can listen to the typemill-events (I wrote about the event-dispatcher here) and make the api calls.

Typemill is open source. Don't expect a high level system or a super robust and bug-free software: It is still a side project with a small community and we work hard to improve it with each release. If you have a close look to the GitHub repository: 8 more stars and we have 100 !!!

Explain RBAC vs ACL Like I'm Five

Sebastian Schürmanns — Thu, 12 Mar 2020 07:02:25 +0000

HeyHo DEVs,

I want to implement a permission system for my small flat file cms Typemill and I am not super sure, if I should follow RBAC or ACL. What the heck is the difference? I want to create roles like this:

"reader" (public access),
"member" with auth and access to "member" content
"customer" with auth and access to "paid" content
"author" with auth and access to his own articles
"editor" with auth and access to all articles, but no rights like publishing
"publisher" with publishing rights.
"admin" with access to admin settings.

Everything with enough flexibility.

So what should I use?

When and how did you learn to code?

Sebastian Schürmanns — Wed, 18 Sep 2019 14:48:03 +0000

I think coding carreers are still pretty diverse and that is what I love so much about it. I was always very bad in math and had not the self-confidence to start with coding, so I was some kind of late starter:

Starting: At the age of 35
Language: PHP
First steps with: The book "php for kids" and a video-tutorial on how to create a tumblr-like blog-platform :D

Explain How I Secure my First Web-Application Like I Am Five

Sebastian Schürmanns — Fri, 05 Jul 2019 08:47:05 +0000

Yes, I am your super nerdy child and proudly present you my first self-coded web application. Of course I want to publish it live and show it to all my kindergarden-friends. You are super proud, but you also want to prevent me from a security-nightmare with my first running web-application. Your child wouldn't be such a lovely nerd if it had not already duckduckgone some security-related terms. Now it is your turn to explain what it means, what it prevents from and how it works (super basically):

HTTPS
Input Validation
Authentication (oauth, JWT, more?)
Autorization
Security Headers
CSRF
CORS
CSP
Captcha
Honeypot

... and maybe you are missing some very basic random stuff that is important to know before I go live?

Creating a Block Editor with Markdown and Vue.js

Sebastian Schürmanns — Fri, 07 Dec 2018 10:25:17 +0000

Editing blocks of content is highly popular these days. WordPress is one of the last kids on the block, other content management systems like AEM or Magnolia follow the concept of content components since more than a decade now. So while I coded my small flat file cms called Typmill.net as a side project, I wondered if some kind of block editing could also bridge the gap between markdown and the not so tech-savvy mainstream-editors.

If you want to build a new editor-experience, then you can use one of the new editor-frameworks like prosemirror or slate, which also provide a realtime-wysiwyg-mode for markdown. However, I am not a professional software-developer and these frameworks are pretty complicated to start with. But I started to use Vue.js some month ago and so I decided to code my own block-editing-experience with Vue.sj from scratch. Don't expect a super high level frontend editor here, it is more like an experimental hacking and it is tightly coupled to Typemill, but the result might still be interesting:

The typemill block editor as of november 2018

It is a quite big project, so I cannot show much code here, but maybe some basic ideas of the block-editing with markdown.

Markdown are Blocks by Definition

I am not sure if you are aware that markdown works with blocks by definition, because markdown uses two linebreaks to separate each block (paragraph). So you can transform a valid and normalized markdown-file into a simple array of content blocks with just one line of PHP-code:

  $markdownArray = explode("\n\n", $markdown);

You have to deal with some edge-cases like code-blocks, but basically it is as simple as that.

A Backend Approach

With Vue.js you can fetch the markdown-array with an API in a JSON-format and then create your website in the frontend. I decided against that standard-way from two reasons:

I already use a highly interactive navigation built with vue, so the page renders very slow if you add the content-part on top of that.
If I transform markdown to html in the frontend, then I have to maintain and extend two libraries: one markdown-parser in the backend (I use parsedown with several extensions) and one in the frontend (vue markdown parser for example).

So I decided for an uncommon way and used the backend for most of the tasks. With a php-library like parsedown it is pretty easy to transform the markdown-blocks into html-blocks similar like this:

$parsedown  = new Parsedown();
$htmlArray = [];

foreach($markdownArray as $markdownBlock)
{
    $htmlArray[] = $parsedown->text($markdownBlock);    
}

In the frontend, I can print out each html-block with a simple loop. Rendering the page in the backend makes the initial page load pretty fast. At the same time, Vue.js enters the stage because I can print out each block into a vue component like this:

<?php foreach($htmlArray as $key => $htmlBlock): ?>

   <content-block>
    <div class="blox" @click.prevent="setData( $event )" data-id="<?php echo $key; ?>"><?php echo $htmlBlock; ?></div>
   </content-block>

<?php endforeach; ?>

The Vue-Part

The vue-part is pretty complex (and chaotic, sorry for that), so I cannot show code-examples but only explain the basic ideas. So basically I use three parts:

A vue app with some general tasks.
A content-component as a frame or wrapper for each content-block.
Dynamic components for each content-type (like paragraph, images and more).

The vue app loads the markdown-array in a JSON-format with an API-call after the page has loaded. I can connect the html on the page and the markdown in the vue-data with the ID now. I do this with the setData-method:

@click.prevent="setData( $event )"

With the data-id I can get the corresponding markdown part and use it in my content-component. You might think that this is a bit hacky, but I explained the reasons before...

The content-component is the frame that does all the general stuff: It gets the markdown-data from the vue-app for each block, it switches between the html-preview-mode and the markdown-edit-mode, and each content component has a button to save, cancel and delete a block. When I save the block, then I send the markdown-data to the backend. In the backend I store the block in the file (work with the ID again to get the appropriate block), transform the markdown block into html again and send it in the response back to the frontend.

The most exciting part are the dynamic component. This is the concept of vue, where you can switch a component dynamically:

<!-- Component changes when currentTabComponent changes -->
<component v-bind:is="currentTabComponent"></component>

Vue explains the concept here and also provides some fiddles to play with.

I use this concept to open different components for different content types. The basic content type is a text-paragraph and this opens in the standard textarea-component. But I just added another component for handling images and a lot more will follow. Handling images can become pretty painful in some content-management-systems, so I think I found a quite user-friendly way:

If you want to have a look (on typemill or github), then don't expect high level code, as I said I am a hobby-developer and not a professional.

Which Markdown Editor Do You Recommend For My Application?

Sebastian Schürmanns — Fri, 08 Jun 2018 07:01:51 +0000

Hey all, right now I am building a minimal flat file cms and I am looking for a nice markdown editor. There are two main requirements:

The cms is for non-techies, so the markdown-editor should have the option to bridge the gap with some kind of optional wysiwyg mode.
On server side I use extensions that support tags like [TOC] and integration of KaTeX, MathJax and other special stuff, so the markdown syntax of the editor should be extensible in some way.

Right now I thing about:

Slatejs: My favourite so far, similar to prosemirror but easier to start with (based on react).
Prosemirror: Looks good but learning curve is pretty high I think.
SimpleMDE: Pretty fast, more traditional and based on codemirror, but I don't think that it is easy to extend?
Tui: Looks good but also a bit obscure. Based on codemirror, too.

Which one would you recommend for my requirements?

How to engage people and find contributors for an open source project on github?

Sebastian Schürmanns — Mon, 02 Apr 2018 07:30:55 +0000

Yes, we all know that this is very hard, but maybe you have some tricks or strategies, or you have engaged in an open source project yourself and still remember, why?

How I Created my First Plugin-System

Sebastian Schürmanns — Fri, 16 Mar 2018 18:14:43 +0000

Hi all,

I am pretty sure that most of you have already written a plugin for a CMS or any other software. But did you ever think about creating your own plugin system for your own software project, so that others can plug into your software and enhance it without touching the core code? It is a bit more tricky than crafting a simple plugin. But it is way easier than you might think. And for me, it changed the way I code new projects forever.

How I Coded Projects Before

I am NOT a professional developer, but a product owner and historian (originally). I code projects just for fun, for distraction and for therapeutic reasons. I started with PHP at the age of 35 and I learned it with the book "PHP for Kids". Growing up mentally, I learned how to write a tumblr-like application with dirty old spaghetti code. It was already organized in a MVC way, but I still ran into the usual mess of chaotic and unmaintainable code. To solve these problems, I switched to object orientation and namespacing, I started to use the PHP-microframework Slim and I familiarized myself with GitHub and Composer. Everything was organized in models, controllers, classes, methods, configuration files and external libraries, so there was a gleam of order in all that chaos. But this still does not help in certain situations ...

Asking the Right Questions

This situation popped up with my little side-project called Typemill, that should become a simple flat-file-cms for writers once it is grown up. For a real CMS I had to find a way to let other coders enhance my system with plugins, addons, extensions or whatever you want to call it. So I asked some search engines ...

... and I was pretty astonished, that all these search engines don't know much about "plugin systems" at all. Poor answers are usually a result of wrong questions. So I digged deeper and found out, that plugin systems follow special programming patterns (and to be honest, I didn't care much about programming patterns before). There are several patterns for plugin systems (read Anthony Ferraras article about patterns for plugins), but the most common pattern is the "mediator pattern". And the mediator pattern is also used for something called "event driven programming" and "event dispatching".

I am familiar with "events" in JavaScript, but I didn't know, that you can use "events" in server side code, too. In fact, not only content management systems use events for their plugin systems, but most of the frameworks like Zend, Laravel and others provide a build-in event system out of the box.

How I Tried to Understand Event Systems

I tried to wrap my head around "event systems" by comparing them with IFTTT: If this happens, than do that. In fact, you can describe all plugins with a simple and human readable IFTTT-logic like this:

If the application has generated a html-page, then add a newsletter subscription form to the page (oh nooo, don't do that, we all hate them!!!!)

You can even go a step further and describe the logic with a simple array like this:

['onHtmlLoaded' => 'addSubscriptionFormMethod']

The key of the array (left side) is the name of the event and the value of the array (right side) is the name of your method. So if the event on the left side happens, then the methods of the right side should be called. If this than that. Pretty simple.

To get this simple logic to work, you need to create a special script often called "Event Dispatcher". But before you start coding, think about using one of the excellent libraries out there.

Working With The EventDispatcher

An event dispatcher is not too complicated and there are some very lightweight implementations with about 100 lines of code. What they do is always the same: They create and manage an array of event-names and event-listeners like shown above. The event-listeners are callables (method-names). So if you know the event-name, than it is no problem to call the subscribed methods with a handy php-function like call_user_func() or call_user_func_array(). And that is exactly what all these event dispatchers do.

The most widespread EventDispatcher-library is the Symfony Event Dispatcher. It provides something like this:

It manages the described array of event-names and callables.
It allows you to add new "listeners" or "subscribers" to this array. The "listeners" or "subsribers" are your plugins.
It allows you to "fire" (or "dispatch") events in your application, so that all the subscribers (plugin-method) for this event get called.

You can check the dispatcher-class of Symfony (just 240 lines) and you will be surprised how simple everything is.

Initiate the Dispatcher

We will create our little newsletter-plugin now to demonstrate the dispatcher with a real life example. Let's install the Symfony EventDispatcher with GitHub and Composer and then initiate it somewhere at the beginning of our code (for example in the beginning of an index.php file):

use Symfony\Component\EventDispatcher\EventDispatcher;

$dispatcher = new EventDispatcher();

Now we can work with the EventDispatcher. We will do it in the following steps:

We will define a new event called "onHtmlLoaded".
We will fire the event in your application.
We will write a newsletter-plugin that subscribes to this event.
We will get, manipulate and return data with the plugin.

Define An Event

Before you can use your own events in the Symfony EventDispatcher you have to define them. A new event can be defined with an empty class like this:

namespace Typemill\Events;

use Symfony\Component\EventDispatcher\Event;

class onHtmlLoaded extends Event
{

}

All new events have to extend the base "Event" of Symfony. Later, we will define some helpful methods in this class, but for now an empty class is enough.

To keep your code organized, it is a good idea to create a new folder called "events" to collect all event definitions in a central place.

Fire The Event

Let's go back to our application and fire the new event. This can be done with a single line of code.

For our newsletter plugin, we want to fire the event right after the HTML-content is loaded. In Typemill, I use the parsedown-library to transform the markdown-text into html. So I add this simple line of code:

$contentHTML = $parsedown->text($contentMarkdown);

$dispatcher->dispatch('onHtmlLoaded', new Typemill\Events\onHtmlLoaded());

The dispatch-method accepts two arguments: The name of the event and the event object. That is all. Now the event dispatcher uses the internal array and calls all plugin-methods, that have subscribed to this event.

But wait, there are no plugins yet. So let us create our newsletter-plugin now.

The Newsletter-Plugin: Subscribe to Events

I created a new "plugin"-folder for all plugins and in there I created a folder called "newsletter". The class for our newsletter-plugin looks like this:

namespace Plugins\Newsletter;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Typemill\Events\onHtmlReady;

class Newsletter
{
    public static function getSubscribedEvents()
    {
        return array('onHtmlLoaded' => 'myNewsletterMethod');
    }

    public function myNewsletterMethod()
    {
        die('I will add the newsletter to the html-page one day');
    }
}

And finally there is the array, that we have mentioned at the beginning of this article. And this array looks exactly the same: The name of the event is on the left side and the name of the plugin-method is on the right side. If this than that.

The method, that returns the array, is always getSubscribedEvents() and it has to be a public static method. The Symfony EventDispatcher will simply check all classes for the existence of this method and add the array to its central array of events and listeners or subscribers. It is as simple as that.

Load Your Plugins

The last step is still missing: We have to initialize our plugin-class and add it tho the dispatcher, otherwise the dispatcher does not know about its existence. We should load all plugins right at the beginning of our application and add a plugin to the dispatcher like this:

$dispatcher = new EventDispatcher();

....
....

$dispatcher->addSubscriber(new \Plugins\Newsletter());

Of course you don't want to add all plugins manually. For Typemill, I wrote a separate class, that scans all the plugin-folders, performs some checks and returns the fully qualified classnames, so that you can do something like this:

$dispatcher = new EventDispatcher();

...

$plugins = new Typemill\Plugins();
$pluginClassnames = $plugins->load();

foreach($pluginClassnames as $pluginClassname)
{
  $dispatcher->addSubscriber(new $pluginClassname());
}

Ok, I left out a lot of details, but this should be enough to get started.

Let us check what we have so far: If we visit a page in Typemill now, then the event "onHtmlReady" gets fired and the subscribed newsletter plugin get's called. Right now, the newsletter method simply kills the application and prints out the words "I will add the newsletter to the html-page one day".

It works. But it does not really feel like a cool plugin. So lets make it a bit more useful.

Manipulating Data With The Plugin

To create our newsletter-plugin, we want to get the html-content, add the newsletter subscription form and return everything to the application again.

To do this, we can simply add some getters and setters to the event class, that we have defined before. Let's do it this way:

namespace Typemill\Events;

use Symfony\Component\EventDispatcher\Event;

class onHtmlLoaded extends Event
{

    protected $data;

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

    public function getData()
    {
        return $this->data;
    }

    public function setData($data)
    {
        $this->data = $data;
    }
}

When we fire an event in our application, we can simply pass some data like this now:

$contentHTML = $parsedown->text($contentMarkdown);

$dispatcher->dispatch('onHtmlLoaded', new Typemill\Events\onHtmlLoaded($contentHTML));

And finally we can access and return the data in our newsletter plugin like this:

class Newsletter
{

    public static function getSubscribedEvents()

    {
        return array('onHtmlLoaded' => 'myNewsletterMethod');

    }

    public function myNewsletterMethod($data)
    {
        $content = $data->getData(); 

        $content .= '<p>I am the newsletter subscription form</p>';

        $data->setData($content);
    }

}

We have added our newsletter form to the content and returned everything to the application. The final trick is, that our application uses the manipulated data from now on. And this can be done as simple as that:

$contentHTML = $parsedown->text($contentMarkdown);

$contentHTML = $dispatcher->dispatch('onHtmlLoaded', new Typemill\Events\onhtmlLoaded($contentHTML))->getData();

Voila, the application will now send everything to the Twig template engine and display the page to the user. And we have added a newsletter-form to this page without touching any core file of the application. Our first plugin is done!

Events and Your Application's Life Cycle

In real life you want to provide a lot of entry points to your application, so that client coders can manipulate different data in a lot of steps. So your event-system will usually follow the life cycle of your application and fire events in each step of the life cicle. For Typemill, it looks similar to this:

The application loads all settings.
The application loads all plugins.
The application loads a template engine like Twig.
The application routes to a controller, that creates the page.
The controller loads the requested content file.
The controller transforms the markdown content into HTML.
The controller collects some other data (e.g. for a navigation).
The controller sends all the data to the template engine.
The template engine displays the page to the user.

The smaller the steps, the greater the flexibility.

You Just Created Your Own Plugin System

The code above is pretty rough and not much more than you can already read in the documentation of the symfony event dispatcher itself. And if you want to create a really useful plugin system, you have to add a lot of details: How should all these plugins get loaded? How can users configure your plugins? Which useful methods should you add to a basic plugin class? How can you add new routes to your application with a plugin?

A lot of open questions, but the basics are done. And for me it was really helpful to find all these ressources and examples. If you want to create your own plugin systems, you can check some real life implementations out there (I used Grav, Leafpub and many others to find my own way to integrate a plugin system into Typemill).

But even if you don't want to create your own plugin system, then this kind of event driven programming is still a great way to decouple your code and to bring a bit more order into the chaos of a new code-project.