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
- Lifecycle · Core classes · Routing order · Schema & indexes · Multilingual · Cache · Coding rules · Debug & performance · Release
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
| File | Responsibility |
|---|---|
index.php / admin/index.php | Single front/back entry and dispatch |
core/Router.php | Path parsing, reserved words, out-of-range page detection |
core/Front.php | Data + render assembly for home, posts, taxonomies, archives, search |
core/Db.php | PDO wrapper, ye_ prefix, prepared statements |
core/View.php | Theme resolution, view fallback, View::asset() |
core/Markdown.php | Markdown → HTML (escape first, anchors, tables, data-lang fences) |
core/Changelog.php | Structured timeline renderer for /changelog (since 1.2.5) |
core/Nav.php | Single navigation source for top/foot/dropdowns |
core/Lang.php / Poly.php / ZhTw.php | UI strings, content translations, Simplified↔Traditional |
Plugins.php / Hooks.php / Upgrade.php | Plugin boot, action bus, migrations |
Cache.php | File cache (pages / blocks) |
Csrf.php / Auth.php / Uc.php | Tokens, auth, user centre |
Mail.php / Feed.php / Market.php | Mail, RSS/sitemap, market |
Str.php / helpers.php / version.php | String helpers, global helpers, version constant |
Routing order
Router::resolve() matches top-down, first hit wins:
- Empty path →
home(with/page/N/) /healthz- Language segment (only when
Poly::on()and the language is enabled — recursive/en/,/ja/…) /category/…,/tag/…, index pages,/archives/YYYY[/MM][/page/N]/search,/login,/register,/logout,/count,/feed,/sitemap.xml,/pages,/user/…- Business prefixes
mall/site/ai(404 when the plugin is off) docs,changelogclean URLs → content pages/{slug}.html→ post or page- Plugin pages
/{slug}[/...] - 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
| Table | Purpose |
|---|---|
ye_contents | Posts/pages (type, status, slug, content_format, published_at, deleted_at, …) |
ye_poly_contents | Translations (group_id, lang, status, manual_override, …) |
ye_metas | Categories/tags (type, name, names_i18n, slug_i18n, precomputed count) |
ye_relationships | Content ↔ term |
ye_options | Site options |
ye_users / ye_comments | Users, comments |
ye_views / ye_attachments | View counter details, media |
ye_migrations | Migration history |
Key points:
- Every front-end list filters
type='post' AND status='publish' AND deleted_at IS NULL; copy this condition in new queries. countis precomputed — never add a(SELECT COUNT(*) FROM ye_relationships …)subquery to list views (removed from thexinglan/wenshuthemes 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_boundskeyset fast path; Traditional Chinese (tw) joined it in 1.2.4, with a safe fallback when the subset is smaller thanlimit. - See
install/schema.sqlandtools/optimize-indexes.php; alwaysEXPLAINbefore 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/*.phpand are read with__('key'); add every key to all language packs. - Full guide: i18n & AI translation.
Cache
| Location | Content | Flush when |
|---|---|---|
var/cache/pages/ | full-page cache | content, theme or menu changes |
var/cache/blocks/ | sidebar/block cache | sidebar 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 incore/, global helpers inhelpers.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 throughDb::t(); writes needCsrf::field()+Csrf::check(). - No secrets in source, repo or logs;
DEBUG=trueonly locally and temporarily. php -lbefore 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:
- Root
CHANGELOG.md: full developer record (root cause / fix / criteria / verification / deploy / rollback). - Live
/changelogis a database content page (ye_contents.slug=changelog) rendered bycore/Changelog.php; its English translation is inye_poly_contents. Update both on every release. - Bump
YC_VERSIONincore/version.php. - 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. - Flush page caches (
/changelogsendsCache-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.