joseconti/Klytos Helper Functions

Klytos Helper Functions Reference

When to Use This Skill

Use this reference whenever you need to call a Klytos core function from a plugin, a custom template, or any PHP code running inside the CMS. All functions are prefixed with klytos_ and are available globally after boot.

These functions are loaded by App::boot() BEFORE plugins, so they are available in every plugin's init.php.

---

Hook Wrappers

Actions (fire-and-forget events)

klytos_add_action(string $hook, callable $callback, int $priority = 10): void

Register a callback for an action hook. Lower priority = runs earlier. Default: 10.

klytos_do_action(string $hook, mixed ...$args): void

Fire an action hook, executing all registered callbacks with the provided arguments.

klytos_remove_action(string $hook, callable $callback): bool

Remove a specific callback from an action hook. Returns true if removed.

klytos_has_action(string $hook): bool

Check if any callbacks are registered for an action hook.

Filters (modify and return data)

klytos_add_filter(string $hook, callable $callback, int $priority = 10): void

Register a callback that receives, modifies, and returns a value.

klytos_apply_filters(string $hook, mixed $value, mixed ...$args): mixed

Pass a value through all registered filter callbacks. Each callback receives the value and returns its modified version.

klytos_remove_filter(string $hook, callable $callback): bool

Remove a specific callback from a filter hook.

klytos_has_filter(string $hook): bool

Check if any callbacks are registered for a filter hook.

Bulk Removal

klytos_remove_all_actions(string $hook): void

Remove ALL callbacks from an action hook. Use with caution.

klytos_remove_all_filters(string $hook): void

Remove ALL callbacks from a filter hook. Use with caution.

Debugging / Introspection

klytos_did_action(string $hook): int

Check how many times an action has been fired in this request.

klytos_get_fired_actions(): array

Get all actions that have been fired. Returns ['hook' => fire_count, ...].

klytos_get_registered_hooks(): array

Get all registered hooks and callback counts. Returns ['actions' => [...], 'filters' => [...]].

Example

// Register an action
klytos_add_action('page.after_save', function (array $page, string $action): void {
    klytos_log('info', "Page {$page['slug']} was {$action}d");
});

// Register a filter
klytos_add_filter('page.content', function (string $html): string {
    return '<div class="wrapper">' . $html . '</div>';
});

IMPORTANT: ALWAYS use the global klytos_* functions. NEVER use Hooks:: class methods directly. The Hooks class is an internal engine — all code must use the klytos_* wrappers.

---

Core Service Accessors

klytos_app(): App

Get the App singleton instance. Provides access to all managers and services.

klytos_storage(): StorageInterface

Get the storage layer (FileStorage or DatabaseStorage). Use this for all data operations.

klytos_auth(): Auth

Get the authentication manager. Provides session management, CSRF, bearer tokens, OAuth.

---

Configuration

klytos_config(string $key, mixed $default = null): mixed

Read a configuration value using dot-notation. Examples:

• klytos_config('site_name') -> 'My Site'
• klytos_config('admin_language', 'en') -> 'es'
• klytos_config('social.twitter') -> '@handle'

klytos_set_config(string $key, mixed $value): void

Write a configuration value. Top-level keys only (no dot-notation for writing). Use sparingly — most plugin settings should use klytos_set_option() instead.

klytos_version(): string

Get the current Klytos version. Returns semantic version string (e.g. '0.11.0').

---

URL Helpers

klytos_url(string $path = ''): string

Generate a full URL relative to the Klytos site root.

klytos_admin_url(string $path = ''): string

Generate a full admin URL.

klytos_plugin_url(string $pluginId, string $path = ''): string

Get the public URL for a plugin's assets directory.

klytos_plugin_path(string $pluginId, string $path = ''): string

Get the absolute filesystem path for a plugin's directory.

---

Context Checks

klytos_is_admin(): bool   // True if in admin panel context
klytos_is_mcp(): bool     // True if MCP API request
klytos_is_cli(): bool     // True if command line

Usage Pattern

if (klytos_is_mcp()) {
    // MCP-specific logic (return JSON)
} elseif (klytos_is_admin()) {
    // Admin panel logic (render HTML)
}

---

User & Permissions

klytos_current_user(): ?array

Get the currently authenticated user. Returns null if not logged in. Returns: ['id' => string, 'username' => string, 'role' => string, 'email' => string]

klytos_has_permission(string $permission): bool

Check if the current user has a specific permission. Owner role has ALL permissions.

Built-in Permissions

| Permission | Roles Allowed | |---|---| | pages.view | owner, admin, editor, viewer | | pages.create | owner, admin, editor | | pages.edit | owner, admin, editor | | pages.delete | owner, admin | | theme.manage | owner, admin | | menu.manage | owner, admin | | blocks.manage | owner, admin | | templates.manage | owner, admin | | templates.approve | owner | | build.run | owner, admin | | assets.manage | owner, admin, editor | | tasks.create | owner, admin, editor | | tasks.manage | owner, admin | | users.manage | owner | | mcp.manage | owner, admin | | site.configure | owner, admin | | plugins.manage | owner | | analytics.view | owner, admin, editor | | forms.manage | owner, admin | | webhooks.manage | owner, admin | | updates.manage | owner |

Extending Permissions from a Plugin

klytos_add_filter('auth.capabilities', function (array $capabilities): array {
    $capabilities['my_plugin.manage'] = ['owner', 'admin'];
    $capabilities['my_plugin.view']   = ['owner', 'admin', 'editor'];
    return $capabilities;
});

---

Options API (Plugin Settings)

klytos_get_option(string $key, mixed $default = null): mixed
klytos_set_option(string $key, mixed $value): void
klytos_delete_option(string $key): bool
klytos_option_exists(string $key): bool

Option Sensitivity (Encryption Classification)

klytos_register_option(string $key, bool|string $sensitive = false, array $meta = []): void
klytos_get_option_sensitivity(string $key): bool|string|null

Declare data sensitivity so Klytos encrypts options appropriately:

• true — Always encrypted (API keys, tokens, secrets)
• 'user_data' — Encrypted from medium level (emails, IPs, GDPR data)
• false — Only encrypted at professional level (default)

Convention: 'plugin_id.setting_name' (e.g. 'my-gallery.columns').

---

Meta API (Entity Metadata)

klytos_get_meta(string $collection, string $entityId, string $key): mixed
klytos_set_meta(string $collection, string $entityId, string $key, mixed $value): void
klytos_delete_meta(string $collection, string $entityId, string $key): bool
klytos_get_all_meta(string $collection, string $entityId): array

---

Time & Timezone API

klytos_timezone(): \DateTimeZone              // Site's timezone object (cached)
klytos_timezone_string(): string              // IANA timezone string (e.g. 'Europe/Madrid')
klytos_timezone_offset(): int                 // UTC offset in seconds (DST-aware)
klytos_timezone_reset_cache(): void           // Clear timezone cache after config change
klytos_now_utc(): string                      // Current UTC time as ISO 8601
klytos_now_local(): string                    // Current local time as ISO 8601
klytos_time(): int                            // Current Unix timestamp (filterable via 'time.now')
klytos_gmdate( string $fmt, ?int $ts ): string          // Format in UTC
klytos_date( string $fmt, ?int $ts ): string             // Format in local timezone
klytos_format_datetime( string $iso, string $fmt ): string // Format ISO string for display
klytos_utc_to_local( string $utc, string $fmt ): string  // UTC to local conversion
klytos_local_to_utc( string $local, string $fmt ): string // Local to UTC conversion
klytos_datetime_to_timestamp( string $dt ): int           // ISO string to Unix timestamp
klytos_timestamp_to_datetime( int $ts ): string           // Unix timestamp to ISO 8601 UTC
klytos_timezone_list(): array                              // Grouped IANA timezones for UI

Rule: store in UTC (klytos_now_utc()), display in local (klytos_format_datetime()). Never use bare date(). See klytos-time skill for full details.

Source: core/helpers-time.php, core/timezone-cache.php

---

Action Scheduler API

klytos_schedule_single_action(int $timestamp, string $hook, array $args = [], string $group = ''): string
klytos_schedule_recurring_action(int $timestamp, int $intervalSeconds, string $hook, array $args = [], string $group = ''): string
klytos_cancel_scheduled_action(string $actionId): bool
klytos_unschedule_all_actions(string $hook, array $args = [], string $group = ''): int
klytos_next_scheduled_action(string $hook, array $args = [], string $group = ''): ?int
klytos_is_scheduled_action(string $hook, array $args = [], string $group = ''): bool

---

Route & Admin Page Registration

klytos_register_route( string $pattern, array $config ): void

Register a dynamic route from a plugin. Config requires callback (callable) and type ('page', 'api', 'webhook'). Optional: method (default 'GET'), template, title, auth (false|'frontend'|'admin'), capability. See core/route-manager.php.

klytos_register_admin_page( string $pluginId, array $page ): void

Register a plugin admin page with sidebar entry. The $page array requires id (maps to plugins/{pluginId}/admin/{id}.php) and title. Optional: icon, position (85-89), capability, children (sub-pages). Routes through admin/plugin-page.php.

Internationalization (i18n)

klytos_register_translations(string $pluginId, string $langDir): void
__(string $key, array $replacements = []): string

---

Logging

klytos_log(string $level, string $message, array $context = [], string $source = 'core'): void

PSR-3 levels: emergency, alert, critical, error, warning, notice, info, debug. Requires Developer Mode active. For plugin sources, plugin must have logging enabled. Logs written to data/logs-{random}/debug-YYYY-MM-DD.log with daily rotation and 5MB file-size splitting.

Level-specific helpers (all accept $message, $context = [], $source = 'core'):

klytos_log_emergency(), klytos_log_alert(), klytos_log_critical(),
klytos_log_error(), klytos_log_warning(), klytos_log_notice(),
klytos_log_info(), klytos_log_debug()

Unconditional Logging (Fatal Errors)

$app->getLogger()->writeAlways(string $level, string $message, array $context = [], string $source = 'core'): void

Bypasses Developer Mode and per-plugin checks. Used by the shutdown handler for fatal errors that MUST always be logged. Not intended for normal application logging — use klytos_log_*() for that.

Fatal Error Shutdown Handler

Registered in admin/bootstrap.php via register_shutdown_function. Catches PHP fatal errors (E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR, E_USER_ERROR) that occur after boot and logs them unconditionally to both PHP error_log() and Klytos logs via Logger::writeAlways().

---

Utility Functions (Helpers class)

Helpers::sanitizeSlug(string $slug): string      // "Cafe & Musica" -> "cafe-musica"
Helpers::transliterate(string $text): string      // e->e, u->u, n->n
Helpers::smartTruncate(string $text, int $max = 160): string
Helpers::now(): string                            // ISO 8601 timestamp
Helpers::randomHex(int $bytes = 32): string       // Secure random hex
Helpers::generateBearerToken(): string            // 64-char hex token
Helpers::hashToken(string $token): string         // SHA-256 hash

---

Shortcodes API (v0.26.0)

klytos_add_shortcode(string $tag, callable $callback, string $description = ''): void

Register a shortcode [tag]. Callback: (array $attrs, string $content, string $tag) → string.

klytos_do_shortcode(string $content): string

Process all registered shortcodes in a string.

klytos_shortcode_exists(string $tag): bool

Check if a shortcode tag is registered.

Transients API (v0.26.0)

klytos_set_transient(string $key, mixed $value, int $ttl = 3600): bool
klytos_get_transient(string $key): mixed      // returns false on miss
klytos_delete_transient(string $key): bool

Temporary data storage with auto-expiration. Wraps CacheManager with transient: prefix.

HTTP API (v0.26.0)

klytos_http(): \Klytos\Core\HttpClient
klytos_http_get(string $url, array $args = []): array
klytos_http_post(string $url, mixed $body = null, array $args = []): array

Returns: ['status' => int, 'headers' => array, 'body' => string, 'error' => ?string].

Dashboard Widgets API (v0.26.0)

klytos_register_dashboard_widget(string $id, string $title, callable $callback, int $position = 50, ?string $capability = null): void
klytos_unregister_dashboard_widget(string $id): void
klytos_get_dashboard_widgets(): array

Register widgets in the admin.dashboard.init action.

Maintenance Mode (v0.26.0)

klytos_is_maintenance_mode(): bool

---

Storage Interface

$storage = klytos_storage();
$storage->read(string $collection, string $id): array
$storage->write(string $collection, string $id, array $data): void
$storage->delete(string $collection, string $id): bool
$storage->exists(string $collection, string $id): bool
$storage->list(string $collection, array $filters = []): array
$storage->count(string $collection, array $filters = []): int
$storage->search(string $collection, string $query, array $fields = []): array
$storage->transaction(callable $fn): mixed

---

Source Files

• Global helpers: core/helpers-global.php
• Utility class: core/helpers.php
• App singleton: core/app.php
• Storage interface: core/storage-interface.php