1<?php
2/**
3 * Elgg page owner library
4 * Contains functions for managing page ownership and context
5 */
6
7/**
8 * Gets the guid of the entity that owns the current page.
9 *
10 * @see default_page_owner_handler() Used to guess the page owner if it's not been set.
11 *
12 * @param int $guid Optional parameter used by elgg_set_page_owner_guid().
13 *
14 * @return int The current page owner guid (0 if none).
15 * @since 1.8.0
16 */
17function elgg_get_page_owner_guid($guid = 0) {
18	$page_owner = _elgg_services()->pageOwner;
19	if ($guid === 0) {
20		return $page_owner->getPageOwnerGuid();
21	}
22
23	elgg_deprecated_notice(__METHOD__ . ' should not be used to set the page owner. Use elgg_set_page_owner_guid().', '3.1');
24
25	// calling function for BC
26	elgg_set_page_owner_guid($guid);
27
28	return $page_owner->getPageOwnerGuid();
29}
30
31/**
32 * Gets the owner entity for the current page.
33 *
34 * @return \ElggEntity|false The current page owner or false if none.
35 *
36 * @since 1.8.0
37 */
38function elgg_get_page_owner_entity() {
39	return _elgg_services()->pageOwner->getPageOwnerEntity();
40}
41
42/**
43 * Set the guid of the entity that owns this page
44 *
45 * @param int $guid The guid of the page owner
46 * @return void
47 * @since 1.8.0
48 */
49function elgg_set_page_owner_guid($guid) {
50	$page_owner = _elgg_services()->pageOwner;
51
52	if ((int) $guid >= 0) {
53		$page_owner->setPageOwnerGuid((int) $guid);
54		return;
55	}
56
57	// removes page owner
58	$page_owner->setPageOwnerGuid(0);
59}
60
61/**
62 * Sets the page context
63 *
64 * Views can modify their output based on the local context. You may want to
65 * display a list of blogs on a blog page or in a small widget. The rendered
66 * output could be different for those two contexts ('blog' vs 'widget').
67 *
68 * Pages that pass through the page handling system set the context to the
69 * first string after the root url. Example: http://example.org/elgg/bookmarks/
70 * results in the initial context being set to 'bookmarks'.
71 *
72 * The context is a stack so that for a widget on a profile, the context stack
73 * may contain first 'profile' and then 'widget'.
74 *
75 * If no context was been set, the default context returned is 'main'.
76 *
77 * @warning The context is not available until the page_handler runs (after
78 * the 'init, system' event processing has completed).
79 *
80 * @param string $context The context of the page
81 * @return bool
82 * @since 1.8.0
83 */
84function elgg_set_context($context) {
85	return _elgg_services()->request->getContextStack()->set($context);
86}
87
88/**
89 * Get the current context.
90 *
91 * Since context is a stack, this is equivalent to a peek.
92 *
93 * @return string|null
94 * @since 1.8.0
95 */
96function elgg_get_context() {
97	return _elgg_services()->request->getContextStack()->peek();
98}
99
100/**
101 * Push a context onto the top of the stack
102 *
103 * @param string $context The context string to add to the context stack
104 * @return void
105 * @since 1.8.0
106 */
107function elgg_push_context($context) {
108	_elgg_services()->request->getContextStack()->push($context);
109}
110
111/**
112 * Removes and returns the top context string from the stack
113 *
114 * @return string|null
115 * @since 1.8.0
116 */
117function elgg_pop_context() {
118	return _elgg_services()->request->getContextStack()->pop();
119}
120
121/**
122 * Check if this context exists anywhere in the stack
123 *
124 * This is useful for situations with more than one element in the stack. For
125 * example, a widget has a context of 'widget'. If a widget view needs to render
126 * itself differently based on being on the dashboard or profile pages, it
127 * can check the stack.
128 *
129 * @param string $context The context string to check for
130 * @return bool
131 * @since 1.8.0
132 */
133function elgg_in_context($context) {
134	return _elgg_services()->request->getContextStack()->contains($context);
135}
136
137/**
138 * Get the entire context stack (e.g. for backing it up)
139 *
140 * @return string[]
141 * @since 1.11
142 */
143function elgg_get_context_stack() {
144	return _elgg_services()->request->getContextStack()->toArray();
145}
146
147/**
148 * Set the entire context stack
149 *
150 * @param string[] $stack All contexts to be placed on the stack
151 * @return void
152 * @since 1.11
153 */
154function elgg_set_context_stack(array $stack) {
155	_elgg_services()->request->getContextStack()->fromArray($stack);
156}
157