README

A set of core features for Hacon WordPress themes.

hacon/theme-core is a PSR-4 Composer library that provides the shared building blocks used across Hacon WordPress themes: a singleton module system, reusable services, a component templating layer, AJAX form handling, and a large set of WordPress/utility helper functions.

Package: hacon/theme-core
Namespace: Hacon\ThemeCore\
Type: library (autoloaded into a theme)
License: MIT

Installation

Install into a theme via Composer:

composer require hacon/theme-core

Then load Composer's autoloader from the theme bootstrap (e.g. functions.php):

require_once get_template_directory() . '/vendor/autoload.php';

Autoloading is configured in composer.json:

PSR-4: Hacon\ThemeCore\ → src/
Files: src/load-functions.php is auto-required and bootstraps all helpers + service helpers/shortcuts folders.

On load, load-functions.php recursively includes every PHP file under src/Helpers, then includes any helpers/ and shortcuts/ folders found under src/Services. This makes the global helper and shortcut functions available everywhere.

Concepts

Theme Modules

Each feature is a Theme Module — a singleton extending ThemeModule (which implements ThemeModuleInterface). Modules are initialized once with an optional config array:

use Hacon\ThemeCore\ThemeModules\ThemeAssetsLoader\ThemeAssetsLoader;

ThemeAssetsLoader::initModule([
    'enqueFrontendCSS' => ['assets/css/app.css'],
    'enqueFrontendJS'  => ['assets/js/app.js'],
    'disableDefaultWPAssetsForFrontend' => ['jquery'],
]);

initModule(array $config = []) constructs the singleton (passing $config to the constructor) and calls init(). Calling it again is a no-op. getInstance() returns the live instance. Cloning and unserializing are blocked.

Configuration

ConfigurationService reads config files from the theme's config/ directory using dot notation. It tries config/<name>.php (returning an array) first, then config/<name>.json.

// Reads config/telegram.php → ['botToken' => '...', 'chatId' => '...']
$token = getThemeСonfig('telegram.botToken', '');

Note: the global shortcut is getThemeСonfig() (see shortcut). Passing null as the key returns the service instance.

Component Templating

Render PHP component templates with HTML attributes and props via ComponentRenderService:

// Preferred API
render_component_template('button', '/components/button/button.php', ['class' => 'btn'], ['label' => 'Send']);

// Deprecated — use render_component_template() instead
component('button', ['class' => 'btn'], ['label' => 'Send']);

HTML attribute helpers (HtmlAttributesService) are exposed as assembleHtmlAttributes() and arrayToHtmlAttributes().

Available Modules

Module	Purpose
`ThemeAssetsLoader`	Register/enqueue CSS & JS per context (frontend, admin, block editor, inline, lazy); strip default WP assets
`ACF`	Advanced Custom Fields integration / setup
`Polylang`	Polylang multilingual helpers and string registration
`ReCaptcha`	reCAPTCHA settings page + verification
`Seeders`	Data seeders, run via `?seeders=name,other` URL param
`FormOrdersPostType`	`form-orders` post type + admin export of form submissions
`GutenbergBlocksWhitelist`	Restrict allowed Gutenberg block types
`EnableSVG`	Allow safe SVG uploads
`FaviconInjector`	Inject favicons into head (frontend, admin, login)
`HotReload`	Dev hot-reload trigger script
`InternalNavigationPrefetch`	Prefetch internal links for faster navigation
`PageAutoTableOfContetns`	Auto table of contents from page headings
`PostColorTheme`	Per-post color theme + body class
`ScrollSaver`	Persist/restore scroll position
`PathPatternCache`	Cache resolved path patterns
`AdminMenuGroupsRegister`	Group admin menu items
`BodyWidthCssComputedVariable`	Expose body width as a CSS variable
`DocumentScrollbarWidthCssVariable`	Expose scrollbar width as a CSS variable
`PreventOnLoadCssTransitions`	Suppress CSS transitions on page load

Services

Service	Purpose
`ConfigurationService`	Dot-notation config access from theme `config/`
`ComponentRenderService`	Render component PHP templates with props & attributes
`HtmlAttributesService`	Build HTML attribute strings from arrays
`TelegramService`	Send messages to Telegram (used by form handler)
`CustomArchivePagesService`	Map custom pages to post-type archives
`PathPatternCacheManager`	Backing cache for `PathPatternCache`

Form Handling

FormAjaxHandler wires up an AJAX form action with reCAPTCHA, email + BCC delivery, Telegram notification, optional WP post creation, redirect, and custom submit handlers. Defaults (Telegram token/chat id) are pulled from theme config.

use Hacon\ThemeCore\Handlers\FormAjaxHandler\FormAjaxHandler;

$handler = new FormAjaxHandler('contact_form');
// configure fields, receivers, templates, redirect...

Helpers

Global functions auto-loaded from src/Helpers:

WordPress (Helpers/wordpress): getImageData, getCurrentPostID, registerAjaxAction, disableWpEmoji, disablePostsPostType, getLink, removePostTypeArchiveSlug, storeUploadInMediaGallery, disableComments, ultimateGetPost
Utils (Helpers/utils): decodeUnicodeContent, isPathActive, _dump, sanitizePhone, getThemeFileUri, getThemeFilePath, prettyLog, requireAll, PatternScanner

Project Layout

src/
├── load-functions.php        # bootstrap: include helpers + service shortcuts
├── Contracts/                # ThemeModuleInterface
├── ThemeModules/             # singleton feature modules (ThemeModule base)
├── Services/                 # config, templating, telegram, archives, caching
│   └── */shortcuts|helpers/  # global function shortcuts (auto-loaded)
├── Handlers/                 # FormAjaxHandler
├── Processors/               # AutoTableOfContentsProcessor
└── Helpers/                  # global WordPress + utility functions

Releasing

Tags drive releases. Run the helper to bump and push a tag (GitHub Actions creates the release):

./release.sh   # choose patch / minor / major

hacon / theme-core

Maintainers

Package info

Statistics

Security