Theme Development

public/themes/your-theme/
├── theme.ini              # Theme metadata (REQUIRED)
├── functions.php          # Thin loader for the modules below (REQUIRED)
├── functions-i18n.php     # t(), locale_url(), language_switcher(), ...
├── functions-nav.php      # front_navigation(), build_menu_tree(), ...
├── functions-post.php     # post retrieval, prepare_post_card(), theme_*_url(), ...
├── functions-media.php    # get_slideshow(), display_galleries(), thumbnails
├── functions-comments.php # total_comment(), block_csrf(), comments renderer
├── header.php             # HTML head, navigation, CSS assets
├── footer.php             # Scripts, footer content, cookie consent
├── home.php               # Homepage template
├── single.php             # Single post view (incl. password-protected posts)
├── page.php               # Static page template
├── category.php           # Category archive
├── tag.php                # Tag archive
├── archive.php            # Monthly archive
├── archives.php           # Archive index
├── blog.php               # Blog listing
├── search.php             # Search results page
├── sidebar.php            # Sidebar widgets
├── 404.php                # Error page (rendered by ThemeRenderer::render404())
├── privacy.php            # Privacy policy
├── cookie-consent.php     # GDPR banner (included by footer.php)
├── download.php           # Download info page
├── download_file.php      # File stream handler (no header/footer wrapper)
├── render-comments.php    # Legacy comments wrapper (markup in partials/)
├── index.php              # Kept for compatibility (NOT used for routing)
├── partials/              # Shared reusable markup
│   ├── card.php           # Post card (home + all listing templates)
│   ├── meta.php           # Author / date row for cards
│   ├── paginator.php      # Shared pagination wrapper
│   └── comments.php       # Comment list + load-more section
├── lang/                  # Translations (en always required, fallback language)
│   ├── en.json
│   ├── ar.json
│   ├── zh.json
│   ├── fr.json
│   ├── ru.json
│   ├── es.json
│   └── id.json
└── assets/                # CSS, JS, vendor, images
    ├── css/               # Source + .min.css production versions
    ├── js/                # Source + .min.js production versions
    ├── vendor/            # bootstrap, jquery, font-awesome, fancybox, popper.js, ...
    └── img/               # hero.jpg, placeholder.svg, favicon.ico, ...

[info]
theme_name = "My Custom Theme"
theme_designer = "Your Name"
theme_description = "Description of your theme"
theme_directory = "my-theme"

<?php
defined('SCRIPTLOG') || die('Direct access not permitted');

// NO call_theme_header() here - the system handles it
// Template content starts directly:
?>
<div class="container">
    <!-- Page content here -->
</div>
<?php
// NO call_theme_footer() here - the system handles it

// Translate a key; %param% placeholders are replaced from $params
t('sidebar.latest_posts.title');
t('search.found_results', ['count' => 3, 'keyword' => 'php']);

// Locale helpers
get_locale();            // e.g. 'en', 'ar', 'id'
available_locales();     // ['en', 'ar', 'zh', 'fr', 'ru', 'es', 'id']
is_rtl();                // true for Arabic
get_html_dir();          // 'ltr' or 'rtl'
locale_url('/path');     // locale-prefixed URL (permalink-aware)
get_language_name($locale, true);
language_switcher($args);

// Retrieval (prefer front_service() for new code)
featured_post();              // random headline post(s)
sticky_page();                // random sticky page
random_posts(0, 6);
latest_posts($limit, $position);
retrieve_blog_posts();
retrieve_detail_post($id);
posts_by_category($topicId);  // ['entries' => ..., 'pagination' => ...]
posts_by_tag($tag);
searching_by_tag($tag);
posts_by_archive($values);
archive_index();              // months + counts, grouped by year
retrieve_page($arg, $rewrite);

// Preparation: normalize once into escaped ViewModels
prepare_post_card($entry);    // PostViewModel for partials/card.php
prepare_page($entry);         // PageViewModel
prepare_archive($entry);      // ArchiveViewModel
prepare_sidebar();            // SidebarViewModel (latest, cats, archives, tags)

// Permalink-aware URL builders (never hard-code routes)
theme_post_url(['ID' => 5, 'post_slug' => 'slug']);
theme_page_url(['ID' => 2, 'post_slug' => 'about']);
theme_topic_url($row);
theme_tag_url($tag);
theme_archive_url($month, $year);
theme_search_url();           // {base}/search (permalinks ON) or {base}/ (OFF)

// Navigation (functions-nav.php; theme_navigation() lives in lib/utility/)
theme_navigation('public');   // raw ['items' => ..., 'parents' => ...]
front_navigation(0, $menu);   // builds MenuViewModel tree, renders HTML
build_menu_tree($items, $parents);
convert_menu_link($link, $permalinkEnabled);

// Comments (functions-comments.php) — state-changing forms need block_csrf()
total_comment($postId)['total'];   // returns ['total' => int], not an int
block_csrf();                      // hidden CSRF input
render_comments_section($postId, 0);

// Media (functions-media.php)
get_slideshow($limit = 5);
display_galleries($start, $limit);
get_post_thumbnail($post_img, $post_title, $img_alt = '');
get_download_page_data($identifier);   // UUID download lookup

// Shared core helpers (loaded by core, used in every template)
theme_escape_html($string);   // THE output-escaping boundary
front_service();              // shared FrontService (replaces FrontHelper)
theme_dir();                  // current theme directory URL
app_url(); app_sitename(); app_tagline();
make_date($timestamp);        // display only — never in form <input> values

// Simple featured image (thumbnail)
invoke_frontimg($media_filename, $image_thumb = true);

// Responsive <picture> with WebP fallback
invoke_responsive_image(
    $media_filename,
    $size = 'thumbnail',   // 'thumbnail' | 'medium' | 'large'
    $image_thumb = true,
    $alt = '',
    $class = 'img-fluid',
    $fetchpriority = false,
    $decoding = 'auto',
    $loading = 'auto'      // 'lazy' | 'eager' | 'auto' (no attribute when 'auto')
);

// Hero / LCP image (fetchpriority="high")
invoke_hero_image($media_filename, $fallback_url = '', $alt = '');

// Gallery thumbnail (lazy-loaded, for Fancybox links)
invoke_gallery_image($media_filename, $alt = '');

php tmp/minify.php

<?php defined('SCRIPTLOG') || die('Direct access not permitted'); ?>

<!-- Plain text: escape once -->
<?= theme_escape_html($post['post_title']); ?>
<a href="<?= theme_escape_html($postUrl); ?>"><?= theme_escape_html($post['post_title']); ?></a>

<!-- Already-sanitized HTML: print as-is, never escape twice -->
<?= $post_content; ?>   <!-- sanitized by htmLawed() in the service layer -->
<?= paragraph_l2br(safe_html(paragraph_trim($post['post_content']))); ?>

<!-- State-changing forms carry a CSRF token (search uses GET + honeypot instead) -->
<form method="post">
    <?= block_csrf(); ?>
</form>

<html lang="<?= get_locale(); ?>" dir="<?= get_html_dir(); ?>">

<?php if (is_rtl()): ?>
    <link rel="stylesheet" href="<?= theme_dir(); ?>assets/css/rtl.min.css">
<?php endif; ?>
<?php if (is_rtl()): ?>
    <script src="<?= theme_dir(); ?>assets/js/rtl.min.js" defer></script>
<?php endif; ?>