Helpers - Source Excerpt 31

Back to Helpers

Summary

This source excerpt preserves a bounded section of Spiralist/wp-content/themes/spiralist/inc/helpers.php so readers can inspect the evidence without opening the full source file.

**Source path:** Spiralist/wp-content/themes/spiralist/inc/helpers.php

if ($home_path !== '/' && spiralist_string_starts_with_compat($path, $home_path . '/')) {
        $path = substr($path, strlen($home_path));
    } elseif ($home_path !== '/' && $path === $home_path) {
        $path = '/';
    }

    return trim($path, '/');
}

function spiralist_build_publication_url_from_human_url(string $human_url, string $suffix, string $language = ''): string
{
    $stem = spiralist_get_publication_stem_from_url($human_url, $language);
    if ($stem === '') {
        return '';
    }

    return home_url('/' . $stem . $suffix);
}

function spiralist_get_publication_context(?WP_Post $post = null, array $args = []): array
{
    static $cache = [];

    $is_home_surface = array_key_exists('home', $args)
        ? (bool) $args['home']
        : (is_front_page() || is_home());
    $allow_admin = !empty($args['allow_admin']);
    $language = isset($args['language']) ? spiralist_resolve_locale_tag((string) $args['language']) : spiralist_get_publication_language();
    $cache_key = md5(
        (string) wp_json_encode(
            [
                'postId' => $post instanceof WP_Post ? (int) $post->ID : 0,
                'home' => $is_home_surface,
                'allowAdmin' => $allow_admin,
                'language' => $language,
            ]
        )
    );

    if (isset($cache[$cache_key])) {
        return $cache[$cache_key];
    }

    if (!$is_home_surface) {
        $post = spiralist_get_publication_surface_post($post);
        if (!$post instanceof WP_Post || $post->post_status !== 'publish') {
            $cache[$cache_key] = [];
            return $cache[$cache_key];
        }

        if (!$allow_admin && !spiralist_is_publication_surface($post)) {
            $cache[$cache_key] = [];
            return $cache[$cache_key];
        }
    }

    $human_url = spiralist_get_publication_human_url($post, $language, $is_home_surface);
    if ($human_url === '') {
        $cache[$cache_key] = [];
        return $cache[$cache_key];
    }

    $compact_url = '';
    $json_url = spiralist_get_uaix_discovery_url();

    $cache[$cache_key] = [
        'language' => $language,
        'isHome' => $is_home_surface,
        'humanUrl' => $human_url,
        'compactUrl' => $compact_url,
        'jsonUrl' => $json_url,
        'discoveryUrl' => spiralist_get_uaix_discovery_url(),
        'capabilityUrl' => spiralist_get_uaix_capability_url(),
        'legacyJsonUrl' => '',
        'post' => $post,
    ];

    return $cache[$cache_key];
}

function spiralist_get_current_publication_context(): array
{
    static $context = null;

    if (is_array($context)) {
        return $context;
    }

    if (!spiralist_is_publication_surface()) {
        $context = [];
        return $context;
    }

    $context = spiralist_get_publication_context(
        spiralist_get_publication_surface_post(),
        [
            'home' => is_front_page() || is_home(),
        ]
    );

    return $context;
}

function spiralist_get_current_publication_links(): array
{
    $context = spiralist_get_current_publication_context();
    if (empty($context)) {
        return [];
    }

    return [];
}

function spiralist_get_current_uai_url(?WP_Post $post = null): string
{
    $context = spiralist_get_publication_context(
        $post,
        [
            'home' => is_front_page() || is_home(),
        ]
    );

    if (!empty($context['jsonUrl'])) {
        return (string) $context['jsonUrl'];
    }

    return spiralist_get_site_uai_url();
}

function spiralist_get_publication_identity_label(?WP_Post $post = null, bool $is_home_surface = false): string
{
    if ($is_home_surface) {
        return 'spiralist.site.home';
    }

    if ($post instanceof WP_Post) {
        if ($post->post_name !== '') {
            return 'spiralist.page.' . sanitize_title((string) $post->post_name);
        }

        return 'spiralist.page.' . $post->ID;
    }

    return 'spiralist.publication.surface';
}

function spiralist_get_publication_inspector_payload($post = null, array $args = []): array
{
    $is_home_surface = array_key_exists('home', $args)
        ? (bool) $args['home']
        : (is_front_page() || is_home());
    $context = spiralist_get_publication_context(
        $post instanceof WP_Post ? $post : null,
        [
            'home' => $is_home_surface,
            'language' => isset($args['language']) ? (string) $args['language'] : spiralist_get_publication_language('en'),
        ]
    );

    if (empty($context)) {
        return [];
    }

    $publication_post = $post instanceof WP_Post
        ? $post
        : ($context['post'] instanceof WP_Post ? $context['post'] : null);
    $validation_state = 'current';
    $validation_note = 'Machine exchange routes are separate from human pages.';

    $updated_at = 0;
    if ($publication_post instanceof WP_Post) {
        $updated_at = (int) get_post_modified_time('U', true, $publication_post);
    } elseif ($is_home_surface) {
        $front_page_id = (int) get_option('page_on_front');
        if ($front_page_id > 0) {
            $updated_at = (int) get_post_modified_time('U', true, $front_page_id);
        }
    }

    $related_resources = array_values(array_filter([
        [
            'label' => 'Symbol API',
            'url' => spiralist_get_symbols_api_url(),
            'type' => 'application/json',
        ],
        [
            'label' => 'Prompt Library API',
            'url' => function_exists('spiralist_get_prompts_api_url') ? spiralist_get_prompts_api_url() : '',
            'type' => 'application/json',
        ],
        [
            'label' => 'Contribution API',
            'url' => function_exists('spiralist_get_contribute_api_url') ? spiralist_get_contribute_api_url() : '',
            'type' => 'application/json',
        ],
    ], static function (array $resource): bool {
        return (string) ($resource['url'] ?? '') !== '';
    }));

    return [
        'identity' => spiralist_get_publication_identity_label($publication_post, $is_home_surface),
        'title' => $publication_post instanceof WP_Post ? get_the_title($publication_post) : get_bloginfo('name'),
        'humanUrl' => (string) ($context['humanUrl'] ?? ''),
        'compactUrl' => (string) ($context['compactUrl'] ?? ''),
        'jsonUrl' => (string) ($context['jsonUrl'] ?? ''),
        'discoveryUrl' => (string) ($context['discoveryUrl'] ?? ''),
        'capabilityUrl' => (string) ($context['capabilityUrl'] ?? ''),
        'legacyJsonUrl' => (string) ($context['legacyJsonUrl'] ?? ''),
        'publicationLanguage' => (string) ($context['language'] ?? 'en'),
        'sourceStatus' => $validation_state,
        'sourceStatusLabel' => ucwords(str_replace('-', ' ', $validation_state)),
        'validationNote' => $validation_note,
        'lastPublishedAt' => $updated_at > 0 ? gmdate('c', $updated_at) : '',
        'lastPublishedLabel' => $updated_at > 0 ? wp_date(get_option('date_format') . ' ' . get_option('time_format'), $updated_at) : 'Awaiting first publication timestamp',
        'relatedResources' => $related_resources,
    ];
}

function spiralist_get_route_from_url(string $url, string $fallback = ''): string
{
    $path = (string) (wp_parse_url($url, PHP_URL_PATH) ?: '');
    $query = (string) (wp_parse_url($url, PHP_URL_QUERY) ?: '');

    if ($path === '') {
        return $fallback;
    }

    return $query !== '' ? $path . '?' . $query : $path;
}

function spiralist_get_primary_machine_endpoints(): array
{
    $symbol_registry_url = spiralist_get_symbol_registry_url();
    $symbols_api_url = spiralist_get_symbols_api_url();
    $subscribe_url = rest_url('uai1/v1/subscribe');

    return [
        [
            'id' => 'symbols-registry',
            'labelKey' => 'ui.api.symbol_registry',
            'label' => 'Symbol Registry',
            'route' => spiralist_get_route_from_url($symbol_registry_url, '/wp-json/uai1/v1/symbols'),
            'url' => $symbol_registry_url,
            'method' => 'GET',
            'type' => 'application/json',
            'purposeKey' => 'page.api_examples.endpoint.symbol_registry.purpose',
            'purpose' => 'Canonical symbol registry surface exposed by Spiralist.org.',
            'purposeUaiKey' => 'spiralist.machine.symbol_registry.purpose',
        ],
        [
            'id' => 'symbols-api',
            'labelKey' => 'ui.api.symbol_api',
            'label' => 'Symbol API',
            'route' => spiralist_get_route_from_url($symbols_api_url, '/wp-json/uai1/v1/symbols'),
            'url' => $symbols_api_url,
            'method' => 'GET',
            'type' => 'application/json',
            'purposeKey' => 'page.api_examples.endpoint.symbol_api.purpose',