---
name: convert-template-to-php
description: Use when converting a static HTML template into this project's PHP theme header/footer and page integration while preserving playground/content page structures and using existing data/helpers.
---

# Convert Template To PHP

Convert the supplied static template into PHP theme files. Default target:

- `src/templates/<theme>/header.php`
- `src/templates/<theme>/footer.php`

Ask before editing. Do not improvise missing sections, data sources, routes, states, helper calls, or asset behavior.

## Questions

Ask unanswered questions together:

- Template source files and target theme directory?
- Is the target structure closer to `cotowers`, `schoolco`, or neither?
- Which routes need validation?
- Which dynamic sections must be active now?
- Guest, logged-in, GM/admin, client-mode, and mobile states required?
- Should existing sidebar, social, slider, ranking, cart, and payment areas be enabled?
- Which assets and external scripts are approved?
- Should missing HTML sections remain static placeholders or be connected to existing helpers?

If a requested HTML section has no clear project data/helper, stop and ask.

## Required References

Read:

- `Docs/skills/create-full-template/SKILL.md`
- `Docs/knowledge/01-code-conventions.md`
- `Docs/knowledge/02-architecture.md`
- `Docs/api/template-components.md`
- `Docs/api/form-components.md`
- `src/index.php`
- `src/pages/routes.php`
- `src/settings/helpers.php`
- `src/core/templates/components-base.template.php`
- `src/core/templates/components-form-base.template.php`
- `src/pages/public/playground/playground.view.php`
- `Docs/skills/create-full-template/playground-html-ref.html`
- `Docs/knowledge/05-content-management.md`
- `src/core/modules/Content/templates/news-category-cards.php`

Theme conversion references:

- `src/templates/cotowers/header.php`
- `src/templates/cotowers/footer.php`
- `src/templates/schoolco/header.php`
- `src/templates/schoolco/footer.php`
- `src/templates/conquerhub-2026/header.php`
- `src/templates/conquerhub-2026/footer.php`
- `src/templates/conquerhub-2026/components.template.php`
- `src/templates/conquerhub-2026/components-form.template.php`

Do not inspect other files under `src/templates/cotowers/`, `src/templates/schoolco/`, or `src/templates/conquerhub-2026/` unless the user explicitly approves it.

## Conversion Rules

1. Keep the supplied HTML structure, classes, IDs, and visual design.
2. Replace only dynamic areas with existing PHP expressions, loops, helpers, or component methods.
3. Keep static HTML where no approved data source exists.
4. Preserve page-content structures from the playground and CMS content contract.
5. Do not create custom data-config arrays, new data abstractions, or speculative helpers.
6. Do not modify core components, models, routes, or database code unless explicitly requested.
7. Keep HTML comments marking each converted dynamic section.
8. Escape only according to the existing local convention.
9. Keep JavaScript and CSS asset paths relative to `THEME_URI` or existing project paths.
10. Keep header/footer wrapper tags balanced for home and non-home branches.

## Bootstrap And Head

Use the existing helpers:

```php
<?php ComponentsTemplate::printMetaTags(); ?>
<?php ComponentsTemplate::importCommonCSS(); ?>
```

Add approved theme CSS after common CSS. Preserve the source template's viewport, language attribute, favicon, fonts, and external assets only when approved.

Common dynamic values:

- `THEME` selects the active theme.
- `THEME_URI` prefixes theme assets.
- `WEB_URL` is the site base URL.
- `LANGUAGE` is the active language path.
- `ComponentsTemplateBase::getHTMLClass()` supplies the admin HTML class when used by the source theme.

## Body And Admin Bar

Keep the source body classes/IDs. When the target includes the GM bar, use the existing guard immediately after `<body>`:

```php
<?php
if (isAdminAccount()) {
  require_once CORE . 'admin-bar/admin-bar.php';
  renderAdminBar();
}
?>
```

Do not duplicate or redesign the admin-bar renderer in the theme.

## Header Data

### Primary Menu

Use `HEADER_SECTIONS` and preserve the existing visibility rules:

```php
<?php foreach (HEADER_SECTIONS as $url => $data) {
  if ('register' === $url && ACCOUNT_NAME) {
    continue;
  }
  if ('account-panel' === $url && !ACCOUNT_NAME) {
    continue;
  }
  ?>
  <a href="<?php echo LANGUAGE; ?>/<?php echo $url; ?>">
    <?php echo __($data['label']); ?>
  </a>
<?php } ?>
```

Keep the supplied template's surrounding `li`, menu, and link classes.

### Languages

Only render language links when multiple languages are available:

```php
<?php if (AVAILABLE_LANGUAGES && count(AVAILABLE_LANGUAGES) > 1) {
  foreach (AVAILABLE_LANGUAGES as $key => $name) { ?>
    <a href="<?php echo languagePageUrl($key); ?>">
      <img alt="<?php echo $name; ?>" src="...">
    </a>
<?php }
} ?>
```

Use `languagePageUrl($key)`. Do not manually rebuild content slugs or discard query parameters.

### Account State

Use existing constants and data:

- `ACCOUNT_NAME`: guest/account state
- `ACCOUNT_DATA`: authenticated account row
- `GM_STATE`: GM threshold
- `isAdminAccount()`: admin guard
- `LOADING_IN_CLIENT`: client-rendering mode
- `IS_HOME`: home-page branch

Do not query account data from the theme when an existing controller/header variable already provides it.

## Online And Game Data

Only load values required by the supplied template:

- Cotowers header: `$Online = EntitiesModel::onlinePlayers();`, displayed in `.serverInfo__online`.
- Schoolco header: `$online = EntitiesModel::onlinePlayers();` and `$totalPlayers = EntitiesModel::count();`, displayed in `.onlineBlock` and `.onlineReg-block-player`.
- Do not add `EntitiesModel::count()` when the target has no total-account section.
- Do not invent additional game queries for decorative sections.

Page-specific data belongs to its page/controller. For rankings, use the existing ranking page variables and flow; do not load ranking data from a generic header unless the supplied template explicitly contains an existing ranking include/mount.

## Theme-Specific Header Sections

### Cotowers Pattern

Preserve the supplied conditional sections when selected:

- `.topPanel` with `HEADER_SECTIONS`, language links, guest login, or account panel.
- `.wrapper > header` with `.sparks`, `.leaves`, optional aperture timer, `.headerBlock`, `.headerButtons`, download, online counter, and registration/account action.
- `IS_HOME && !LOADING_IN_CLIENT` header information: `.headerInfo`, `.headerInfo-slider`, `.swiper-container.slider`, `.swiper-wrapper`, slides, `.headerInfo-buttons`, donation/vote/social links.
- `main` and `.tabs.tabs-n.newsTabs`.
- Home branch: `.tabs-content.active > .container-home > .news.news-block-left > .panel.panel-news`.
- Non-home branch: `.blockStat > .blockStat-1 > .container-home-1`, then the sidebar mount and `.page-content.page-content-2`.

Keep the existing conditional wrapper closures in the footer.

### Schoolco Pattern

Preserve the supplied sections when selected:

- `<html lang="...">`, responsive viewport, approved font/CSS assets, and `body.bg-3`.
- `.wrapper > header > .topPanel > .topPanel-wrapper` with `.topPanel-left`, `.nav`, `.nav-item`, `.nav-link`, language links, and authenticated sign-out.
- Header logo, `.online`, `.onlineBlock`, `.onlineReg`, `.onlineReg-block-player`, and `.download`.
- `main.main > aside` sidebar and `.content` page mount.
- Guest sidebar login form using existing login route fields.
- Authenticated sidebar player/account blocks using existing `$userProfile`, `getEnabledPages($userPanelPages)`, `$adminPanelPages`, and GM checks only when that source section is retained.
- Social block `.socHome` and its approved social URL guards.

Do not copy these sections into a different target unless the user selects them.

### ConquerHub Pattern

- `.site-header.topbar` with brand cluster (`.hub-link`, `.brand-divider`, `.server-nav-logo`), `details.topbar-mobile-menu` / `summary.mobile-toggle`, `primary-nav` with `HEADER_SECTIONS`, `.header-actions` (`select.language-select`, hub, discord, download, account/login button), and `.topbar-mobile-drawer`.
- Theme style stylesheet selected in PHP via `const TEMPLATE_INFO = ['themeStyle' => 'umbra']` (or fallback `'umbra'`) linking `assets/css/themes/{$themeStyle}.css`. External `theme.js` is omitted; CSS handles mobile drawer, hover/focus dropdowns, and CMS `generic.js` handles accordions.
- Home branch: `.hero`, `<main><div class="container">`, `.dashboard-quick-grid.single-column-quick` (server time, online players via `EntitiesModel::onlinePlayers()`, next event), `.single-story`, and `.intro-grid` with download client and discord actions.
- Non-home branch: `<main class="page-main"><div class="container">`.
- Footer: 4-column `.container.footer-grid` (brand/note, support, information, server stats) and `.footer-bottom` copyright.

## Footer Data And Scripts

### Menu And Copyright

When the source has a footer menu, loop `FOOTER_SECTIONS` with the same register/account visibility rules used by `HEADER_SECTIONS`. Use existing values for copyright:

- `date('Y')`
- `SERVER_NAME`
- Existing project credit/link

Keep the source footer classes and logo/social wrappers.

### Shared Runtime

Near the end of the footer, preserve:

```php
<?php
ComponentsTemplate::showFloatingFooter();
ComponentsTemplate::importCommonJS();
?>
```

Add approved theme scripts after `importCommonJS()`. Do not manually duplicate page scripts already enqueued by `loadPageJS()`.

The source themes differ:

- Cotowers loads Swiper/global scripts and closes the login modal/overlay structure.
- Schoolco loads its EOS/jquery, validation, app, Swiper, Slick, and global scripts.

Keep only scripts required by the converted template and approved by the user.

## Theme Translations

- Theme-level translations in `src/templates/<theme>/translations/{lang}.php` (e.g., `es.php`, `pt.php`, `br.php`).
- Loaded via `THEME_PATH . 'translations/' . LANGUAGE . '.php'` in `helpers.php`.
- Merge pattern:
  ```php
  $locales[LANGUAGE] = array_merge($locales[LANGUAGE] ?? [], [
    'Original string' => 'Translated string',
  ]);
  ```
- `br.php` alias:
  ```php
  require_once __DIR__ . '/pt.php';
  $locales['br'] = $locales['pt'];
  ```

## Component Overrides

Themes can override methods in `components.template.php` and `components-form.template.php`:

- `ComponentsTemplate::StartBlock($sectionName)`: can add `.auth-card` when `$sectionName` is in `['login', 'register', 'forgotpassword']`.
- `ComponentsTemplate::PageTitle($title)`: `<h1 class="top">...</h1>` matching theme display typography.
- `FormComponents::showProduct`: add `.product__image--default` when image is empty or `default.svg`.
- `.cart-payment-methods`: first column width/max-width constrained to 175px (`th:first-child`, `td:first-child`).

## Page Content

The page body must preserve the current content contracts:

- Playground cards, categories, subcategories, and data attributes from the reference.
- Forms, plain controls, blocks, buttons, accordions, fields, and tables from the component references.
- CMS category/node structures from `Docs/knowledge/05-content-management.md` and its current templates:
  - News category: `.content-category-news > article.blog-item > .blog-content > .entry-header > h3 > a + .content-node-image + .blog-story.short-story`
  - Cards category: `.news-list.content-category-cards > article.news-card > .news-date + h3 > a + p.text-muted`
  - Dropdown category: `.faqs.content-category-dropdown > .accordion > .accordion__box-title + .accordion__box-content`
  - Content node: `.panel.panel-content-article > .content-node-image.content-article-image + .content-article-body`
- Ranking, profile, guild, player-icon, store, and cart structures already documented by the playground.

Do not include production CMS templates or database-backed renderers in a static playground.

## Validation

Before finishing, ask if any ambiguity remains. Then check:

1. `php -l` on changed PHP files.
2. Home and non-home wrapper balance.
3. Guest, authenticated, GM/admin, and client-mode branches requested by the user.
4. Header/footer menu visibility and language URLs.
5. Online/player sections only where configured.
6. Existing page content classes and hierarchy against the playground/content references.
7. All theme assets and scripts resolve through the correct paths.
8. `git diff --check`.

Do not claim a database-backed page works without the required runtime/configuration.