APR (Adaptive Page Renderer)

APR is a modular, server-driven UI framework for PHP 8+.

Developers define pages in .apr.json files, and APR renders HTML/CSS/JS by loading component plugins dynamically.

Directory Structure

APR/
  core/
    AprEngine.php
    AssetBundler.php
    CacheManager.php
    LayoutManager.php
    PartialLoader.php
    PluginLoader.php
    PluginRegistry.php
    Renderer.php
    SecurityValidator.php
    TemplateCompiler.php
    ThemeManager.php
  cli/
    apr
  cache/
    pages/
    templates/
    plugins_registry.json
  layouts/
    default.html
  partials/
    navbar.html
    footer.html
  themes/
    default/
      layouts/
      partials/
      plugins/
      styles/
  plugins/
    <component>/
      <type>/
        plugin.json
        plugin.php (optional)
        routes.php (optional)
        template.html or template.php
        component.php (optional)
        style.css
        script.js
        api.php (optional)
  pages/
    home.apr.json
  public/
    apr.php
    apr.min.js
    apr.css
  schema/
    apr.schema.json
  schemas/
    apr-page.schema.json
  docs/
    components.md

Clone And Run Locally

1. Clone the repository:

git clone https://github.com/aprea-a/APR.git
cd APR

2. Start a local PHP server:

php -S localhost:8000 -t public

3. Open APR demo pages:

• http://localhost:8000/apr.php?page=home
• http://localhost:8000/apr.php?page=full_test
• http://localhost:8000/index.php
• http://localhost:8000/apr-plugin-api/contact-form

4. Embed APR in any HTML page:

<link rel="stylesheet" href="/apr.css">
<script src="/apr.min.js" defer></script>
<div apr-page="/pages/home.apr.json"></div>

Override Props At Runtime

You can pass overrides to apr.php as JSON:

/apr.php?page=home&overrides={"components":{"carousel":{"theme":"light"}}}

Supported override scopes:

• * for global defaults
• components.<componentName>
• types.<componentName:typeName>
• ids.<componentId>

Production Features

• Compiled plugin templates (cache/templates) for faster runtime rendering
• Page output cache with configurable TTL (APR_CACHE_TTL)
• Plugin registry cache (cache/plugins_registry.json) for fast plugin lookup
• Layout system via page layout key and /layouts templates
• Partial templates via {{> partial_name}} from /partials
• Theme override resolution from /themes/<theme>/...
• Plugin asset bundling with deduplication and optional production minification
• Plugin compatibility checks (apr_min_version) and dependency validation
• Optional plugin signature verification (APR_VERIFY_SIGNATURE=true)
• Security hardening for plugin file scanning and recursion limits
• Debug mode metrics (APR_DEBUG=true) with render timing and cache status
• Plugin backend support (component.php, template.php, api.php)
• Plugin bootstrap support (plugin.php, routes.php, hooks, custom component registration)
• Central component registry API (APR::registerComponent)
• Automatic plugin API route registration under /apr-plugin-api/<route>
• Schema validation before render using /schema/apr.schema.json
• Cache key invalidation tied to source file hash + plugin signatures

APR Runtime API

APR::config(['dev' => true]);

APR::registerComponent([
  'component' => 'content',
  'type' => 'hero',
  'render' => 'plugins/content/hero/component.php'
]);

APR::registerRoute('custom/ping', static function () {
  return ['status' => 200, 'json' => ['status' => 'ok']];
});

APR::registerHook('after_component_render', static function ($html) {
  return $html;
});

CLI

php cli/apr build
php cli/apr cache:clear
php cli/apr plugins:list
php cli/apr plugins:scan
php cli/apr components:list
php cli/apr components:info content/hero
php apr-cli.php create:plugin PluginName
php apr-cli.php create:component ComponentName
php apr-cli.php clear:cache

Create A New Component Plugin

1. Create a new folder:

plugins/<component>/<type>/

2. Add required files:

• plugin.json
• template.html or template.php
• style.css

3. Optional files:

• script.js
• plugin.php
• routes.php
• component.php
• api.php
• assets/

4. Example plugin.json:

{
  "name": "My Component",
  "component": "content",
  "type": "my_component",
  "version": "1.0.0",
  "apr_min_version": "1.0.0",
  "dependencies": [],
  "props": {
    "id": "apr-my-component",
    "title": "Hello APR"
  }
}

5. Rebuild registry and compile templates:

php cli/apr plugins:scan
php cli/apr build

6. Use it in a page:

{
  "component": "content",
  "type": "my_component",
  "props": {
    "title": "Rendered by APR"
  }
}

7. If api.php exists, call it through:

/apr-plugin-api/<type-slug>

Contributing

1. Fork the repository and create a feature branch.
2. Keep changes modular and backward compatible with existing .apr.json and plugins.
3. Run local checks:

php cli/apr plugins:scan
php cli/apr build
find . -name "*.php" -print0 | xargs -0 -n 1 php -l

4. Open a pull request with clear component/theme examples.
5. Contributions are licensed under MIT. Preserve existing license attribution: Copyright (c) 2026 Gabriele Aprea.