elgglib.php

Go to the documentation of this file.

<?php

use Elgg\Http\ResponseBuilder;

function elgg() {
    return _elgg_services()->dic;
}

function forward($location = "", $reason = 'system') {
    if (headers_sent($file, $line)) {
        throw new \SecurityException("Redirect could not be issued due to headers already being sent. Halting execution for security. "
            . "Output started in file $file at line $line. Search http://learn.elgg.org/ for more information.");
    }

    _elgg_services()->responseFactory->redirect($location, $reason);
    exit;
}

function elgg_set_http_header($header, $replace = true) {
    if (!preg_match('~^HTTP/\\d\\.\\d~', $header)) {
        list($name, $value) = explode(':', $header, 2);
        _elgg_services()->responseFactory->setHeader($name, ltrim($value), $replace);
    }
}

function elgg_register_js($name, $url, $location = 'head', $priority = null) {
    return elgg_register_external_file('js', $name, $url, $location, $priority);
}

function elgg_define_js($name, $config) {
    $src = elgg_extract('src', $config);

    if ($src) {
        $url = elgg_normalize_url($src);
        _elgg_services()->amdConfig->addPath($name, $url);
    }

    // shimmed module
    if (isset($config['deps']) || isset($config['exports'])) {
        _elgg_services()->amdConfig->addShim($name, $config);
    }
}

function elgg_unregister_js($name) {
    return elgg_unregister_external_file('js', $name);
}

function elgg_load_js($name) {
    elgg_load_external_file('js', $name);
}


function elgg_require_js($name) {
    _elgg_services()->amdConfig->addDependency($name);
}

function elgg_unrequire_js($name) {
    _elgg_services()->amdConfig->removeDependency($name);
}

function elgg_get_loaded_js($location = 'head') {
    return elgg_get_loaded_external_files('js', $location);
}

function elgg_register_css($name, $url, $priority = null) {
    return elgg_register_external_file('css', $name, $url, 'head', $priority);
}

function elgg_unregister_css($name) {
    return elgg_unregister_external_file('css', $name);
}

function elgg_load_css($name) {
    elgg_load_external_file('css', $name);
}

function elgg_get_loaded_css() {
    return elgg_get_loaded_external_files('css', 'head');
}

function elgg_register_external_file($type, $name, $url, $location, $priority = 500) {
    return _elgg_services()->externalFiles->register($type, $name, $url, $location, $priority);
}

function elgg_unregister_external_file($type, $name) {
    return _elgg_services()->externalFiles->unregister($type, $name);
}

function elgg_load_external_file($type, $name) {
    _elgg_services()->externalFiles->load($type, $name);
}

function elgg_get_loaded_external_files($type, $location) {
    return _elgg_services()->externalFiles->getLoadedFiles($type, $location);
}

function elgg_get_file_list($directory, $exceptions = [], $list = [], $extensions = null) {

    $directory = \Elgg\Project\Paths::sanitize($directory);
    if ($handle = opendir($directory)) {
        while (($file = readdir($handle)) !== false) {
            if (!is_file($directory . $file) || in_array($file, $exceptions)) {
                continue;
            }

            if (is_array($extensions)) {
                if (in_array(strrchr($file, '.'), $extensions)) {
                    $list[] = $directory . $file;
                }
            } else {
                $list[] = $directory . $file;
            }
        }
        closedir($handle);
    }

    return $list;
}

function count_messages($register = "") {
    return elgg()->system_messages->count($register);
}

function system_message($message) {
    elgg()->system_messages->addSuccessMessage($message);
    return true;
}

function register_error($error) {
    elgg()->system_messages->addErrorMessage($error);
    return true;
}

function elgg_get_system_messages() {
    return elgg()->system_messages->loadRegisters();
}

function elgg_set_system_messages(\Elgg\SystemMessages\RegisterSet $set) {
    elgg()->system_messages->saveRegisters($set);
}

function elgg_register_event_handler($event, $object_type, $callback, $priority = 500) {
    return _elgg_services()->events->registerHandler($event, $object_type, $callback, $priority);
}

function elgg_unregister_event_handler($event, $object_type, $callback) {
    return _elgg_services()->events->unregisterHandler($event, $object_type, $callback);
}

function elgg_clear_event_handlers($event, $object_type) {
    _elgg_services()->events->clearHandlers($event, $object_type);
}

function elgg_trigger_event($event, $object_type, $object = null) {
    return elgg()->events->trigger($event, $object_type, $object);
}

function elgg_trigger_before_event($event, $object_type, $object = null) {
    return elgg()->events->triggerBefore($event, $object_type, $object);
}

function elgg_trigger_after_event($event, $object_type, $object = null) {
    return elgg()->events->triggerAfter($event, $object_type, $object);
}

function elgg_trigger_deprecated_event($event, $object_type, $object = null, $message = null, $version = null) {
    return elgg()->events->triggerDeprecated($event, $object_type, $object, $message, $version);
}

function elgg_register_plugin_hook_handler($hook, $type, $callback, $priority = 500) {
    return elgg()->hooks->registerHandler($hook, $type, $callback, $priority);
}

function elgg_unregister_plugin_hook_handler($hook, $entity_type, $callback) {
    elgg()->hooks->unregisterHandler($hook, $entity_type, $callback);
}

function elgg_clear_plugin_hook_handlers($hook, $type) {
    elgg()->hooks->clearHandlers($hook, $type);
}

function elgg_trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) {
    return elgg()->hooks->trigger($hook, $type, $params, $returnvalue);
}

function elgg_trigger_deprecated_plugin_hook($hook, $type, $params = null, $returnvalue = null, $message = null, $version = null) {
    return elgg()->hooks->triggerDeprecated($hook, $type, $params, $returnvalue, $message, $version);
}

function elgg_get_ordered_hook_handlers($hook, $type) {
    return elgg()->hooks->getOrderedHandlers($hook, $type);
}

function elgg_get_ordered_event_handlers($event, $type) {
    return elgg()->events->getOrderedHandlers($event, $type);
}

function elgg_log($message, $level = \Psr\Log\LogLevel::NOTICE) {
    return _elgg_services()->logger->log($level, $message);
}

function elgg_dump($value) {
    _elgg_services()->logger->dump($value);
}

function elgg_get_version($human_readable = false) {
    static $version, $release;
    
    if (!isset($version) || !isset($release)) {
        $path = \Elgg\Application::elggDir()->getPath('version.php');
        if (!is_file($path)) {
            return false;
        }
        include $path;
    }
    
    return $human_readable ? $release : $version;
}

function elgg_deprecated_notice($msg, $dep_version, $backtrace_level = 1) {
    $backtrace_level += 1;
    return _elgg_services()->deprecation->sendNotice($msg, $dep_version, $backtrace_level);
}

function elgg_http_build_url(array $parts, $html_encode = true) {
    // build only what's given to us.
    $scheme = isset($parts['scheme']) ? "{$parts['scheme']}://" : '';
    $host = isset($parts['host']) ? "{$parts['host']}" : '';
    $port = isset($parts['port']) ? ":{$parts['port']}" : '';
    $path = isset($parts['path']) ? "{$parts['path']}" : '';
    $query = isset($parts['query']) ? "?{$parts['query']}" : '';
    $fragment = isset($parts['fragment']) ? "#{$parts['fragment']}" : '';

    $string = $scheme . $host . $port . $path . $query . $fragment;

    if ($html_encode) {
        return htmlspecialchars($string, ENT_QUOTES, 'UTF-8', false);
    } else {
        return $string;
    }
}

function elgg_add_action_tokens_to_url($url, $html_encode = false) {
    $url = elgg_normalize_url($url);
    $components = parse_url($url);

    if (isset($components['query'])) {
        $query = elgg_parse_str($components['query']);
    } else {
        $query = [];
    }

    if (isset($query['__elgg_ts']) && isset($query['__elgg_token'])) {
        return $url;
    }

    // append action tokens to the existing query
    $query['__elgg_ts'] = time();
    $query['__elgg_token'] = generate_action_token($query['__elgg_ts']);
    $components['query'] = http_build_query($query);

    // rebuild the full url
    return elgg_http_build_url($components, $html_encode);
}

function elgg_http_remove_url_query_element($url, $element) {
    return elgg_http_add_url_query_elements($url, [$element => null]);
}

function elgg_http_add_url_query_elements($url, array $elements) {
    $url_array = parse_url($url);

    if (isset($url_array['query'])) {
        $query = elgg_parse_str($url_array['query']);
    } else {
        $query = [];
    }

    foreach ($elements as $k => $v) {
        if ($v === null) {
            unset($query[$k]);
        } else {
            $query[$k] = $v;
        }
    }

    // why check path? A: if no path, this may be a relative URL like "?foo=1". In this case,
    // the output "" would be interpreted the current URL, so in this case we *must* set
    // a query to make sure elements are removed.
    if ($query || empty($url_array['path'])) {
        $url_array['query'] = http_build_query($query);
    } else {
        unset($url_array['query']);
    }
    $string = elgg_http_build_url($url_array, false);

    // Restore relative protocol to url if missing and is provided as part of the initial url (see #9874)
    if (!isset($url['scheme']) && (substr($url, 0, 2) == '//')) {
        $string = "//{$string}";
    }
    
    return $string;
}

function elgg_http_url_is_identical($url1, $url2, $ignore_params = ['offset', 'limit']) {
    if (!is_string($url1) || !is_string($url2)) {
        return false;
    }
    
    $url1 = elgg_normalize_url($url1);
    $url2 = elgg_normalize_url($url2);

    if ($url1 == $url2) {
        return true;
    }

    $url1_info = parse_url($url1);
    $url2_info = parse_url($url2);

    if (isset($url1_info['path'])) {
        $url1_info['path'] = trim($url1_info['path'], '/');
    }
    if (isset($url2_info['path'])) {
        $url2_info['path'] = trim($url2_info['path'], '/');
    }

    // compare basic bits
    $parts = ['scheme', 'host', 'path'];

    foreach ($parts as $part) {
        if ((isset($url1_info[$part]) && isset($url2_info[$part]))
        && $url1_info[$part] != $url2_info[$part]) {
            return false;
        } elseif (isset($url1_info[$part]) && !isset($url2_info[$part])) {
            return false;
        } elseif (!isset($url1_info[$part]) && isset($url2_info[$part])) {
            return false;
        }
    }

    // quick compare of get params
    if (isset($url1_info['query']) && isset($url2_info['query'])
    && $url1_info['query'] == $url2_info['query']) {
        return true;
    }

    // compare get params that might be out of order
    $url1_params = [];
    $url2_params = [];

    if (isset($url1_info['query'])) {
        if ($url1_info['query'] = html_entity_decode($url1_info['query'])) {
            $url1_params = elgg_parse_str($url1_info['query']);
        }
    }

    if (isset($url2_info['query'])) {
        if ($url2_info['query'] = html_entity_decode($url2_info['query'])) {
            $url2_params = elgg_parse_str($url2_info['query']);
        }
    }

    // drop ignored params
    foreach ($ignore_params as $param) {
        if (isset($url1_params[$param])) {
            unset($url1_params[$param]);
        }
        if (isset($url2_params[$param])) {
            unset($url2_params[$param]);
        }
    }

    // array_diff_assoc only returns the items in arr1 that aren't in arrN
    // but not the items that ARE in arrN but NOT in arr1
    // if arr1 is an empty array, this function will return 0 no matter what.
    // since we only care if they're different and not how different,
    // add the results together to get a non-zero (ie, different) result
    $diff_count = count(array_diff_assoc($url1_params, $url2_params));
    $diff_count += count(array_diff_assoc($url2_params, $url1_params));
    if ($diff_count > 0) {
        return false;
    }

    return true;
}

function elgg_http_get_signed_url($url, $expires = false) {
    return _elgg_services()->urlSigner->sign($url, $expires);
}

function elgg_http_validate_signed_url($url) {
    return _elgg_services()->urlSigner->isValid($url);
}

function elgg_signed_request_gatekeeper() {

    if (\Elgg\Application::isCli()) {
        return;
    }

    if (!elgg_http_validate_signed_url(current_page_url())) {
        throw new \Elgg\HttpException(elgg_echo('invalid_request_signature'), ELGG_HTTP_FORBIDDEN);
    }
}

function elgg_extract($key, $array, $default = null, $strict = true) {
    if (!is_array($array) && !$array instanceof ArrayAccess) {
        return $default;
    }

    if ($strict) {
        return (isset($array[$key])) ? $array[$key] : $default;
    } else {
        return (isset($array[$key]) && !empty($array[$key])) ? $array[$key] : $default;
    }
}

function elgg_extract_class(array $array, $existing = [], $extract_key = 'class') {
    $existing = empty($existing) ? [] : (array) $existing;

    $merge = (array) elgg_extract($extract_key, $array, []);

    array_splice($existing, count($existing), 0, $merge);

    return array_values(array_unique($existing));
}

function elgg_call(int $flags, Closure $closure) {
    return _elgg_services()->invoker->call($flags, $closure);
}

function elgg_sort_3d_array_by_value(&$array, $element, $sort_order = SORT_ASC, $sort_type = SORT_LOCALE_STRING) {

    $sort = [];

    foreach ($array as $v) {
        if (isset($v[$element])) {
            $sort[] = strtolower($v[$element]);
        } else {
            $sort[] = null;
        }
    };

    return array_multisort($sort, $sort_order, $sort_type, $array);
}

function ini_get_bool($ini_get_arg) {
    $temp = strtolower(ini_get($ini_get_arg));

    if ($temp == '1' || $temp == 'on' || $temp == 'true') {
        return true;
    }
    return false;
}

function elgg_get_ini_setting_in_bytes($setting) {
    // retrieve INI setting
    $val = ini_get($setting);

    // convert INI setting when shorthand notation is used
    $last = strtolower($val[strlen($val) - 1]);
    if (in_array($last, ['g', 'm', 'k'])) {
        $val = substr($val, 0, -1);
    }
    $val = (int) $val;
    switch ($last) {
        case 'g':
            $val *= 1024;
            // fallthrough intentional
        case 'm':
            $val *= 1024;
            // fallthrough intentional
        case 'k':
            $val *= 1024;
    }

    // return byte value
    return $val;
}

function is_not_null($string) {
    if (($string === '') || ($string === false) || ($string === null)) {
        return false;
    }

    return true;
}

function _elgg_services() {
    // This yields a more shallow stack depth in recursive APIs like views. This aids in debugging and
    // reduces false positives in xdebug's infinite recursion protection.
    return Elgg\Application::$_instance->_services;
}

function _elgg_ajax_page_handler($segments) {
    elgg_ajax_gatekeeper();

    if (count($segments) < 2) {
        return elgg_error_response("Ajax pagehandler called with invalid segments", REFERRER, ELGG_HTTP_BAD_REQUEST);
    }

    if ($segments[0] === 'view' || $segments[0] === 'form') {
        if ($segments[0] === 'view') {
            if ($segments[1] === 'admin') {
                // protect admin views similar to all admin pages that are protected automatically in the admin_page_handler
                elgg_admin_gatekeeper();
            }
            // ignore 'view/'
            $view = implode('/', array_slice($segments, 1));
        } else {
            // form views start with "forms", not "form"
            $view = 'forms/' . implode('/', array_slice($segments, 1));
        }

        $ajax_api = _elgg_services()->ajax;
        $allowed_views = $ajax_api->getViews();

        // cacheable views are always allowed
        if (!in_array($view, $allowed_views) && !_elgg_services()->views->isCacheableView($view)) {
            return elgg_error_response("Ajax view '$view' was not registered", REFERRER, ELGG_HTTP_FORBIDDEN);
        }

        if (!elgg_view_exists($view)) {
            return elgg_error_response("Ajax view '$view' was not found", REFERRER, ELGG_HTTP_NOT_FOUND);
        }

        // pull out GET parameters through filter
        $vars = [];
        foreach (_elgg_services()->request->query->keys() as $name) {
            $vars[$name] = get_input($name);
        }

        if (isset($vars['guid'])) {
            $vars['entity'] = get_entity($vars['guid']);
        }

        if (isset($vars['river_id'])) {
            $vars['item'] = elgg_get_river_item_from_id($vars['river_id']);
        }

        $content_type = '';
        if ($segments[0] === 'view') {
            $output = elgg_view($view, $vars);

            // Try to guess the mime-type
            switch ($segments[1]) {
                case "js":
                    $content_type = 'text/javascript;charset=utf-8';
                    break;
                case "css":
                    $content_type = 'text/css;charset=utf-8';
                    break;
                default :
                    if (_elgg_services()->views->isCacheableView($view)) {
                        $file = _elgg_services()->views->findViewFile($view, elgg_get_viewtype());
                        $content_type = (new \Elgg\Filesystem\MimeTypeDetector())->getType($file, 'text/html');
                    }
                    break;
            }
        } else {
            $action = implode('/', array_slice($segments, 1));
            $output = elgg_view_form($action, [], $vars);
        }

        if ($content_type) {
            elgg_set_http_header("Content-Type: $content_type");
        }

        return elgg_ok_response($output);
    }

    return false;
}

function _elgg_is_valid_options_for_batch_operation($options, $type) {
    if (empty($options) || !is_array($options)) {
        return false;
    }

    // at least one of these is required.
    $required = [
        // generic restraints
        'guid', 'guids'
    ];

    switch ($type) {
        case 'metadata':
            $metadata_required = [
                'metadata_name', 'metadata_names',
                'metadata_value', 'metadata_values'
            ];

            $required = array_merge($required, $metadata_required);
            break;

        case 'annotations':
        case 'annotation':
            $annotations_required = [
                'annotation_owner_guid', 'annotation_owner_guids',
                'annotation_name', 'annotation_names',
                'annotation_value', 'annotation_values'
            ];

            $required = array_merge($required, $annotations_required);
            break;

        case 'river':
            // overriding generic restraints as guids isn't supported in river
            $required = [
                'id', 'ids',
                'subject_guid', 'subject_guids',
                'object_guid', 'object_guids',
                'target_guid', 'target_guids',
                'annotation_id', 'annotation_ids',
                'view', 'views',
            ];
            break;
        
        default:
            return false;
    }

    foreach ($required as $key) {
        // check that it exists and is something.
        if (isset($options[$key]) && $options[$key]) {
            return true;
        }
    }

    return false;
}

function _elgg_walled_garden_init() {
    if (!_elgg_config()->walled_garden) {
        return;
    }

    elgg_register_css('elgg.walled_garden', elgg_get_simplecache_url('walled_garden.css'));

    elgg_register_plugin_hook_handler('register', 'menu:walled_garden', '_elgg_walled_garden_menu');

    if (_elgg_config()->default_access == ACCESS_PUBLIC) {
        elgg_set_config('default_access', ACCESS_LOGGED_IN);
    }

    elgg_register_plugin_hook_handler('access:collections:write', 'all', '_elgg_walled_garden_remove_public_access', 9999);

    if (!elgg_is_logged_in()) {
        // override the front page
        elgg_register_route('index', [
            'path' => '/',
            'resource' => 'walled_garden',
        ]);
    }
}

function _elgg_walled_garden_menu($hook, $type, $return_value, $params) {
    
    if (current_page_url() === elgg_get_site_url()) {
        return;
    }
    
    $return_value[] = \ElggMenuItem::factory([
        'name' => 'home',
        'href' => '/',
        'text' => elgg_echo('walled_garden:home'),
        'priority' => 10,
    ]);

    return $return_value;
}

function _elgg_walled_garden_remove_public_access($hook, $type, $accesses) {
    if (isset($accesses[ACCESS_PUBLIC])) {
        unset($accesses[ACCESS_PUBLIC]);
    }
    return $accesses;
}

function _elgg_init() {
    
    elgg_register_plugin_hook_handler('head', 'page', function($hook, $type, array $result) {
        $result['links']['manifest'] = [
            'rel' => 'manifest',
            'href' => elgg_normalize_url('/manifest.json'),
        ];

        return $result;
    });

    if (_elgg_config()->enable_profiling) {
        elgg_register_plugin_hook_handler('output', 'page', [\Elgg\Profiler::class, 'handlePageOutput'], 999);
    }

    elgg_register_plugin_hook_handler('commands', 'cli', '_elgg_init_cli_commands');
}

function _elgg_init_cli_commands(\Elgg\Hook $hook) {
    $defaults = [
        \Elgg\Cli\SimpletestCommand::class,
        \Elgg\Cli\DatabaseSeedCommand::class,
        \Elgg\Cli\DatabaseUnseedCommand::class,
        \Elgg\Cli\CronCommand::class,
        \Elgg\Cli\FlushCommand::class,
        \Elgg\Cli\PluginsListCommand::class,
        \Elgg\Cli\PluginsActivateCommand::class,
        \Elgg\Cli\PluginsDeactivateCommand::class,
    ];

    return array_merge($defaults, (array) $hook->getValue());
}

function _elgg_register_routes() {
    $conf = \Elgg\Project\Paths::elgg() . 'engine/routes.php';
    $routes = \Elgg\Includer::includeFile($conf);

    foreach ($routes as $name => $def) {
        elgg_register_route($name, $def);
    }
}

function _elgg_register_actions() {
    $conf = \Elgg\Project\Paths::elgg() . 'engine/actions.php';
    $actions = \Elgg\Includer::includeFile($conf);
    
    $root_path = \Elgg\Project\Paths::elgg();

    foreach ($actions as $action => $action_spec) {
        if (!is_array($action_spec)) {
            continue;
        }
        
        $access = elgg_extract('access', $action_spec, 'logged_in');
        $handler = elgg_extract('controller', $action_spec);
        if (!$handler) {
            $handler = elgg_extract('filename', $action_spec);
            if (!$handler) {
                $handler = "$root_path/actions/{$action}.php";
            }
        }
        
        elgg_register_action($action, $handler, $access);
    }
}

function _elgg_api_test($hook, $type, $value, $params) {
    $value[] = ElggTravisInstallTest::class;
    $value[] = ElggCoreHelpersTest::class;
    $value[] = ElggCoreRegressionBugsTest::class;
    $value[] = ElggBatchTest::class;
    return $value;
}

return function(\Elgg\EventsService $events, \Elgg\HooksRegistrationService $hooks) {
    $events->registerHandler('init', 'system', '_elgg_init');
    $events->registerHandler('init', 'system', '_elgg_walled_garden_init', 1000);

    $hooks->registerHandler('unit_test', 'system', '_elgg_api_test');
};