1<?php
2/**
3 * Elgg tags
4 * Functions for managing tags and tag clouds.
5 */
6
7/**
8 * Takes in a comma-separated string and returns an array of tags
9 * which have been trimmed
10 *
11 * @param string $string Comma-separated tag string
12 *
13 * @return mixed An array of strings or the original data if input was not a string
14 */
15function string_to_tag_array($string) {
16	if (!is_string($string)) {
17		return $string;
18	}
19
20	$ar = explode(",", $string);
21	$ar = array_map('trim', $ar);
22
23	$ar = array_filter($ar, function($string) {
24		if (($string === '') || ($string === false) || ($string === null)) {
25			return false;
26		}
27
28		return true;
29	});
30
31	$ar = array_map('strip_tags', $ar);
32	$ar = array_unique($ar);
33	return $ar;
34}
35
36/**
37 * Get popular tags and their frequencies
38 *
39 * Accepts all options supported by {@see elgg_get_metadata()}
40 *
41 * Returns an array of objects that include "tag" and "total" properties
42 *
43 * @todo When updating this function for 3.0, I have noticed that docs explicitly mention
44 *       that tags must be registered, but it was not really checked anywhere in code
45 *       So, either update the docs or decide what the behavior should be
46 *
47 * @param array $options Options
48 *
49 * @option int      $threshold Minimum number of tag occurrences
50 * @option string[] $tag_names Names of registered tag names to include in search
51 *
52 * @return stdClass[]|false
53 * @since 1.7.1
54 */
55function elgg_get_tags(array $options = []) {
56	return _elgg_services()->metadataTable->getTags($options);
57}
58
59/**
60 * Registers a metadata name as containing tags for an entity.
61 * This is required if you are using a non-standard metadata name
62 * for your tags.
63 *
64 * Because tags are simply names of metadata, This is used
65 * in search to prevent data exposure by searching on
66 * arbitrary metadata.
67 *
68 * @param string $name Tag name
69 *
70 * @return bool
71 * @since 1.7.0
72 */
73function elgg_register_tag_metadata_name($name) {
74	return _elgg_services()->metadataTable->registerTagName($name);
75}
76
77/**
78 * Unregister metadata tag name
79 *
80 * @param string $name Tag name
81 *
82 * @return bool
83 * @since 3.0
84 */
85function elgg_unregister_tag_metadata_name($name) {
86	return _elgg_services()->metadataTable->unregisterTagName($name);
87}
88
89/**
90 * Returns an array of valid metadata names for tags.
91 *
92 * @return string[]
93 * @since 1.7.0
94 */
95function elgg_get_registered_tag_metadata_names() {
96	return _elgg_services()->metadataTable->getTagNames();
97}
98
99/**
100 * Tags init
101 *
102 * @return void
103 *
104 * @internal
105 */
106function _elgg_tags_init() {
107	// register the standard tags metadata name
108	elgg_register_tag_metadata_name('tags');
109}
110
111/**
112 * @see \Elgg\Application::loadCore Do not do work here. Just register for events.
113 */
114return function(\Elgg\EventsService $events, \Elgg\HooksRegistrationService $hooks) {
115	$events->registerHandler('init', 'system', '_elgg_tags_init');
116};
117