Architecture & Core Development

For people changing the core, doing deep customisation or contributing. YeCha favours readable source over magic: no container, no build step — a request enters index.php and flows through plain PHP calls.

On this page

Request lifecycle

Browser → rewrite → index.php
  1. config.inc.php + core/bootstrap.php (constants, autoload, session)
  2. Plugins::boot()              load enabled plugins (hooks / pages / admin menus)
  3. Router::resolve($path)       kind + parameters
  4. Page-cache lookup (home/post/meta_list/… are cacheable)
  5. Front::home() / Front::post() / Front::metaList() …
     query → Markdown::render() / Changelog::render() → $main / $side / $toc
  6. View renders themes/<id>/views/layout.php (nav, sidebar, versioned assets)
  7. Hooks::run('front.shell', …) → emit HTML

/admin/ is a separate entry point with the same structure plus Auth and Csrf checks.

Core classes

FileResponsibility
index.php / admin/index.phpSingle front/back entry and dispatch
core/Router.phpPath parsing, reserved words, out-of-range page detection
core/Front.phpData + render assembly for home, posts, taxonomies, archives, search
core/Db.phpPDO wrapper, ye_ prefix, prepared statements
core/View.phpTheme resolution, view fallback, View::asset()
core/Markdown.phpMarkdown → HTML (escape first, anchors, tables, data-lang fences)
core/Changelog.phpStructured timeline renderer for /changelog (since 1.2.5)
core/Nav.phpSingle navigation source for top/foot/dropdowns
core/Lang.php / Poly.php / ZhTw.phpUI strings, content translations, Simplified↔Traditional
Plugins.php / Hooks.php / Upgrade.phpPlugin boot, action bus, migrations
Cache.phpFile cache (pages / blocks)
Csrf.php / Auth.php / Uc.phpTokens, auth, user centre
Mail.php / Feed.php / Market.phpMail, RSS/sitemap, market
Str.php / helpers.php / version.phpString helpers, global helpers, version constant

Routing order

Router::resolve() matches top-down, first hit wins:

  1. Empty path → home (with /page/N/)
  2. /healthz
  3. Language segment (only when Poly::on() and the language is enabled — recursive /en/, /ja/…)
  4. /category/…, /tag/…, index pages, /archives/YYYY[/MM][/page/N]
  5. /search, /login, /register, /logout, /count, /feed, /sitemap.xml, /pages, /user/…
  6. Business prefixes mall / site / ai (404 when the plugin is off)
  7. docs, changelog clean URLs → content pages
  8. /{slug}.html → post or page
  9. Plugin pages /{slug}[/...]
  10. Everything else → 404

Router::RESERVED words cannot be used as content slugs. Out-of-range and malformed page tokens (page/0, page/abc) return 404; the rule lives only in Router::pageBeyond() to avoid duplicate pages with self-referencing canonicals.

Schema & indexes

TablePurpose
ye_contentsPosts/pages (type, status, slug, content_format, published_at, deleted_at, …)
ye_poly_contentsTranslations (group_id, lang, status, manual_override, …)
ye_metasCategories/tags (type, name, names_i18n, slug_i18n, precomputed count)
ye_relationshipsContent ↔ term
ye_optionsSite options
ye_users / ye_commentsUsers, comments
ye_views / ye_attachmentsView counter details, media
ye_migrationsMigration history

Key points:

  • Every front-end list filters type='post' AND status='publish' AND deleted_at IS NULL; copy this condition in new queries.
  • count is precomputed — never add a (SELECT COUNT(*) FROM ye_relationships …) subquery to list views (removed from the xinglan / wenshu themes in 1.2.0).
  • Home post total uses Front::postsTotal(): ye_options.stats.posts_total (O(1)) → cache (3600s) → live COUNT fallback.
  • Deep pagination uses the ye_meta_page_bounds keyset fast path; Traditional Chinese (tw) joined it in 1.2.4, with a safe fallback when the subset is smaller than limit.
  • See install/schema.sql and tools/optimize-indexes.php; always EXPLAIN before changing a query.

Multilingual

  • Language is a URL prefix (/en/…), not a cookie; Poly::on() / Poly::enabled() gate parsing.
  • Poly::row($baseId, $lang) for content, Poly::termName() / Poly::termUrl() for terms; missing translations fall back to the base language.
  • UI strings live in lang/*.php and are read with __('key'); add every key to all language packs.
  • Full guide: i18n & AI translation.

Cache

LocationContentFlush when
var/cache/pages/full-page cachecontent, theme or menu changes
var/cache/blocks/sidebar/block cachesidebar or plugin changes
var/home-static/baked home pages (incl. /en/)home, theme or analytics changes

Use Cache::flush('pages') / Cache::flush('blocks'). Details: operations → cache.

Coding rules

  • PHP 8.1+, declare(strict_types=1); classes in core/, global helpers in helpers.php.
  • Server-side rendering: main content must be visible in the HTML source; JavaScript only enhances interactions, never renders primary lists/details.
  • Escape all output with e(); prepared statements only; table names through Db::t(); writes need Csrf::field() + Csrf::check().
  • No secrets in source, repo or logs; DEBUG=true only locally and temporarily.
  • php -l before and after; smoke-test home, a content page, admin, sitemap and feed with curl.
  • Mind line endings: some files are CRLF (e.g. plugins/market/showcase.php). Bulk patch scripts must not convert a whole file to LF or the diff explodes.

Debug & performance

php -l core/Front.php
php -r 'chdir("/www/wwwroot/yecha.org"); require "config.inc.php"; require "core/bootstrap.php"; Cache::flush("pages");'
curl -s -o /dev/null -w '%{http_code} %{time_total}s\n' -H 'Host: example.com' http://127.0.0.1/

Follow instrument → measure → isolate → fix → re-measure. Start with EXPLAIN and slow-log fingerprints, then isolate SQL, PHP-FPM concurrency, cache ordering, OPcache, asset size and image dimensions. See operations → performance.

Release

There are two changelog sources — update both:

  1. Root CHANGELOG.md: full developer record (root cause / fix / criteria / verification / deploy / rollback).
  2. Live /changelog is a database content page (ye_contents.slug=changelog) rendered by core/Changelog.php; its English translation is in ye_poly_contents. Update both on every release.
  3. Bump YC_VERSION in core/version.php.
  4. Follow RELEASE.md: changelog check → feature-completeness check → package (git archive <tag>; gzip is non-deterministic, compare content SHA after decompressing) → GitHub tag + Release + tar asset → final verification.
  5. Flush page caches (/changelog sends Cache-Control: no-cache, so no CDN purge is needed).

Release headings must stay ## YYYY-MM-DD · YeCha <version> · <title>; the home page "Latest updates" block parses that exact format.