Introduce Plugin Architecture and Extract Multilanguage as Optional Plugin

[elektrischerwalfisch]

Context

flatMark currently handles multilingual behavior via two separate config files (config-basic.php and config-multilang.php).
This works, but it tightly couples core routing and language features, and makes extension harder than necessary.

We want to introduce a lightweight plugin architecture so features can be enabled optionally instead of being hardwired into core behavior.

Goal

Define and implement a minimal plugin system where:

• Core flatMark remains lean and single-language by default
• Multilanguage support is moved into an optional plugin
• Additional features can be added as plugins later

First Milestone

Extract current multilingual logic into a plugin, while preserving existing behavior for multilingual setups.

Open Question

Shortcodes are currently implemented in theme-level functions.php.
It needs to be evaluated## Context

flatMark currently handles multilingual behavior via two separate config files (config-basic.php and config-multilang.php).
This works, but it tightly couples core routing and language features, and makes extension harder than necessary.

We want to introduce a lightweight plugin architecture so features can be enabled optionally instead of being hardwired into core behavior.

Goal

Define and implement a minimal plugin system where:

• Core flatMark remains lean and single-language by default
• Multilanguage support is moved into an optional plugin
• Additional features can be added as plugins later

First Milestone

Extract current multilingual logic into a plugin, while preserving existing behavior for multilingual setups.

Open Question

Shortcodes are currently implemented in theme-level functions.php.
It needs to be evaluated whether shortcodes should:

• stay theme-specific, or
• become an optional plugin (or hybrid model)

This issue includes analysis criteria but does not require shortcode migration yet.

Proposed Architecture (Draft)

Plugin Folder Structure

• plugins/
  • multilang/
    • plugin.php
    • README.md

Optional later:

• plugins/shortcodes/

Minimal Plugin Contract

Each plugin exposes a simple bootstrap entrypoint, for example:

return function (array $context): array {
    // read/update request context
    return $context;
};

The core decides plugin order and passes a shared context (request URI parts, config, resolved page, metadata hooks, etc.).

Core Integration

• Add plugin loading in index.php
• Add config key for enabled plugins, e.g.:

$enabledPlugins = ['multilang'];

• If plugin is disabled, core remains single-language

Scope

In Scope

• Define plugin loading mechanism (small and explicit)
• Add plugins/multilang and move multilingual routing there
• Keep current URLs and behavior compatible with existing multilingual sites
• Document plugin activation in README
• Provide migration notes from config-multilang.php usage

Out of Scope

• Full shortcode migration to plugins
• Advanced plugin lifecycle/events system
• Dependency manager for plugins
• Backward-compatibility for custom forks that patch internals directly

Acceptance Criteria

• Plugin architecture is implemented and documented
• multilang works as optional plugin
• Single-language mode works without multilang plugin enabled
• Existing multilingual URL behavior remains compatible
• Config surface is simpler than current two-config approach
• README includes plugin setup and migration notes

Test Plan

• No plugin enabled: single-language routes resolve correctly
• multilang enabled: /en/... and /de/... routes resolve correctly
• Browser language redirect behavior matches current expectations
• 404 handling works in both single-language and multilingual modes
• Invalid plugin name fails clearly (config error)

Shortcode Evaluation Criteria (Follow-up)

When deciding whether to move shortcodes into plugin(s), evaluate:

• Theming concerns vs content/runtime concerns
• Reusability across themes
• Performance and complexity overhead
• Backward compatibility with existing theme-based shortcodes

Background / Motivation

A plugin-first approach keeps flatMark maintainable and modular:

• Core stays minimal

• Features become optional and composable

• Future extensions (multilang, search, sitemap, shortcodes, etc.) become easier to implement and maintain
  whether shortcodes should:

• stay theme-specific, or

• become an optional plugin (or hybrid model)

This issue includes analysis criteria but does not require shortcode migration yet.

Proposed Architecture (Draft)

Plugin Folder Structure

• plugins/
  • multilang/
    • plugin.php
    • README.md

Optional later:

• plugins/shortcodes/

Minimal Plugin Contract

Each plugin exposes a simple bootstrap entrypoint, for example:

return function (array $context): array {
    // read/update request context
    return $context;
};

The core decides plugin order and passes a shared context (request URI parts, config, resolved page, metadata hooks, etc.).

Core Integration

• Add plugin loading in index.php
• Add config key for enabled plugins, e.g.:

$enabledPlugins = ['multilang'];

• If plugin is disabled, core remains single-language

Scope

In Scope

• Define plugin loading mechanism (small and explicit)
• Add plugins/multilang and move multilingual routing there
• Keep current URLs and behavior compatible with existing multilingual sites
• Document plugin activation in README
• Provide migration notes from config-multilang.php usage

Out of Scope

• Full shortcode migration to plugins
• Advanced plugin lifecycle/events system
• Dependency manager for plugins
• Backward-compatibility for custom forks that patch internals directly

Acceptance Criteria

• Plugin architecture is implemented and documented
• multilang works as optional plugin
• Single-language mode works without multilang plugin enabled
• Existing multilingual URL behavior remains compatible
• Config surface is simpler than current two-config approach
• README includes plugin setup and migration notes

Test Plan

• No plugin enabled: single-language routes resolve correctly
• multilang enabled: /en/... and /de/... routes resolve correctly
• Browser language redirect behavior matches current expectations
• 404 handling works in both single-language and multilingual modes
• Invalid plugin name fails clearly (config error)

Shortcode Evaluation Criteria (Follow-up)

When deciding whether to move shortcodes into plugin(s), evaluate:

• Theming concerns vs content/runtime concerns
• Reusability across themes
• Performance and complexity overhead
• Backward compatibility with existing theme-based shortcodes

Background / Motivation

A plugin-first approach keeps flatMark maintainable and modular:

• Core stays minimal
• Features become optional and composable
• Future extensions (multilang, search, sitemap, shortcodes, etc.) become easier to implement and maintain