Passed
Push — master ( c0a3a7...3b84a4 )
by Jeroen
58:51
created

engine/lib/deprecated-3.0.php (11 issues)

1
<?php
2
3
use Elgg\Database\Entities;
4
5
/**
6
 * Removes a config setting.
7
 *
8
 * @param string $name The name of the field.
9
 *
10
 * @return bool Success or failure
11
 *
12
 * @see get_config()
13
 * @see set_config()
14
 *
15
 * @deprecated Use elgg_remove_config()
16
 */
17
function unset_config($name) {
18
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use elgg_remove_config().', '3.0');
19
	return elgg_remove_config($name);
20
}
21
22
/**
23
 * Add or update a config setting.
24
 *
25
 * Plugin authors should use elgg_set_config().
26
 *
27
 * If the config name already exists, it will be updated to the new value.
28
 *
29
 * @param string $name      The name of the configuration value
30
 * @param mixed  $value     Its value
31
 *
32
 * @return bool
33
 * @see unset_config()
34
 * @see get_config()
35
 * @access private
36
 *
37
 * @deprecated Use elgg_save_config()
38
 */
39
function set_config($name, $value) {
40
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use elgg_save_config().', '3.0');
41
	return elgg_save_config($name, $value);
42
}
43
44
/**
45
 * Gets a configuration value
46
 *
47
 * Plugin authors should use elgg_get_config().
48
 *
49
 * @param string $name      The name of the config value
50
 *
51
 * @return mixed|null
52
 * @see set_config()
53
 * @see unset_config()
54
 * @access private
55
 *
56
 * @deprecated Use elgg_get_config()
57
 */
58
function get_config($name) {
59
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use elgg_get_config().', '3.0');
60
	return elgg_get_config($name);
61
}
62
63
/**
64
 * Add an admin area section or child section.
65
 * This is a wrapper for elgg_register_menu_item().
66
 *
67
 * Used in conjuction with http://elgg.org/admin/section_id/child_section style
68
 * page handler. See the documentation at the top of this file for more details
69
 * on that.
70
 *
71
 * The text of the menu item is obtained from elgg_echo(admin:$parent_id:$menu_id)
72
 *
73
 * This function handles registering the parent if it has not been registered.
74
 *
75
 * @param string $section   The menu section to add to
76
 * @param string $menu_id   The unique ID of section
77
 * @param string $parent_id If a child section, the parent section id
78
 * @param int    $priority  The menu item priority
79
 *
80
 * @return bool
81
 * @since 1.8.0
82
 *
83
 * @deprecated Use elgg_remove_config()
84
 */
85
function elgg_register_admin_menu_item($section, $menu_id, $parent_id = null, $priority = 100) {
86
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use elgg_register_menu_item().', '3.0');
87
	// make sure parent is registered
88
	if ($parent_id && !elgg_is_menu_item_registered('page', $parent_id)) {
0 ignored issues
show
Bug Best Practice introduced by
The expression $parent_id of type null|string is loosely compared to true; this is ambiguous if the string can be empty. You might want to explicitly use !== null instead.

In PHP, under loose comparison (like ==, or !=, or switch conditions), values of different types might be equal.

For string values, the empty string '' is a special case, in particular the following results might be unexpected:

''   == false // true
''   == null  // true
'ab' == false // false
'ab' == null  // false

// It is often better to use strict comparison
'' === false // false
'' === null  // false
Loading history...
89
		elgg_register_admin_menu_item($section, $parent_id);
1 ignored issue
show
Deprecated Code introduced by
The function elgg_register_admin_menu_item() has been deprecated: Use elgg_remove_config() ( Ignorable by Annotation )

If this is a false-positive, you can also ignore this issue in your code via the ignore-deprecated  annotation

89
		/** @scrutinizer ignore-deprecated */ elgg_register_admin_menu_item($section, $parent_id);

This function has been deprecated. The supplier of the function has supplied an explanatory message.

The explanatory message should give you some clue as to whether and when the function will be removed and what other function to use instead.

Loading history...
90
	}
91
92
	// in the admin section parents never have links
93
	if ($parent_id) {
0 ignored issues
show
Bug Best Practice introduced by
The expression $parent_id of type null|string is loosely compared to true; this is ambiguous if the string can be empty. You might want to explicitly use !== null instead.

In PHP, under loose comparison (like ==, or !=, or switch conditions), values of different types might be equal.

For string values, the empty string '' is a special case, in particular the following results might be unexpected:

''   == false // true
''   == null  // true
'ab' == false // false
'ab' == null  // false

// It is often better to use strict comparison
'' === false // false
'' === null  // false
Loading history...
94
		$href = "admin/$parent_id/$menu_id";
95
	} else {
96
		$href = "admin/$menu_id";
97
	}
98
99
	$name = $menu_id;
100
	if ($parent_id) {
0 ignored issues
show
Bug Best Practice introduced by
The expression $parent_id of type null|string is loosely compared to true; this is ambiguous if the string can be empty. You might want to explicitly use !== null instead.

In PHP, under loose comparison (like ==, or !=, or switch conditions), values of different types might be equal.

For string values, the empty string '' is a special case, in particular the following results might be unexpected:

''   == false // true
''   == null  // true
'ab' == false // false
'ab' == null  // false

// It is often better to use strict comparison
'' === false // false
'' === null  // false
Loading history...
101
		$name = "$parent_id:$name";
102
	}
103
104
	return elgg_register_menu_item('page', [
105
		'name' => $name,
106
		'href' => $href,
107
		'text' => elgg_echo("admin:$name"),
108
		'context' => 'admin',
109
		'parent_name' => $parent_id,
110
		'priority' => $priority,
111
		'section' => $section
112
	]);
113
}
114
115
/**
116
 * Mark entities with a particular type and subtype as having access permissions
117
 * that can be changed independently from their parent entity
118
 *
119
 * @param string $type    The type - object, user, etc
120
 * @param string $subtype The subtype; all subtypes by default
121
 *
122
 * @return void
123
 *
124
 * @deprecated
125
 */
126
function register_metadata_as_independent($type, $subtype = '*') {
2 ignored issues
show
The parameter $subtype is not used and could be removed. ( Ignorable by Annotation )

If this is a false-positive, you can also ignore this issue in your code via the ignore-unused  annotation

126
function register_metadata_as_independent($type, /** @scrutinizer ignore-unused */ $subtype = '*') {

This check looks for parameters that have been defined for a function or method, but which are not used in the method body.

Loading history...
The parameter $type is not used and could be removed. ( Ignorable by Annotation )

If this is a false-positive, you can also ignore this issue in your code via the ignore-unused  annotation

126
function register_metadata_as_independent(/** @scrutinizer ignore-unused */ $type, $subtype = '*') {

This check looks for parameters that have been defined for a function or method, but which are not used in the method body.

Loading history...
127
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Metadata no longer is access bound.', '3.0');
128
}
129
130
/**
131
 * Determines whether entities of a given type and subtype should not change
132
 * their metadata in line with their parent entity
133
 *
134
 * @param string $type    The type - object, user, etc
135
 * @param string $subtype The entity subtype
136
 *
137
 * @return bool
138
 *
139
 * @deprecated
140
 */
141
function is_metadata_independent($type, $subtype) {
2 ignored issues
show
The parameter $type is not used and could be removed. ( Ignorable by Annotation )

If this is a false-positive, you can also ignore this issue in your code via the ignore-unused  annotation

141
function is_metadata_independent(/** @scrutinizer ignore-unused */ $type, $subtype) {

This check looks for parameters that have been defined for a function or method, but which are not used in the method body.

Loading history...
The parameter $subtype is not used and could be removed. ( Ignorable by Annotation )

If this is a false-positive, you can also ignore this issue in your code via the ignore-unused  annotation

141
function is_metadata_independent($type, /** @scrutinizer ignore-unused */ $subtype) {

This check looks for parameters that have been defined for a function or method, but which are not used in the method body.

Loading history...
142
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Metadata no longer is access bound.', '3.0');
143
144
	return false;
145
}
146
147
/**
148
 * Gets entities based upon attributes in secondary tables.
149
 *
150
 * @warning requires that the entity type be specified and there can only be one
151
 * type.
152
 *
153
 * @see elgg_get_entities
154
 *
155
 * @param array $options Array in format:
156
 *
157
 * 	attribute_name_value_pairs => ARR (
158
 *                                   'name' => 'name',
159
 *                                   'value' => 'value',
160
 *                                   'operand' => '=', (optional)
161
 *                                   'case_sensitive' => false (optional)
162
 *                                  )
163
 * 	                             If multiple values are sent via
164
 *                               an array ('value' => array('value1', 'value2')
165
 *                               the pair's operand will be forced to "IN".
166
 *
167
 * 	attribute_name_value_pairs_operator => null|STR The operator to use for combining
168
 *                                        (name = value) OPERATOR (name = value); default is AND
169
 *
170
 * @return \ElggEntity[]|mixed If count, int. If not count, array. false on errors.
171
 * @since 1.9.0
172
 * @throws InvalidArgumentException
173
 * @deprecated Use elgg_get_entities()
174
 */
175
function elgg_get_entities_from_attributes(array $options = []) {
176
    elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use elgg_get_entities.', '3.0');
177
178
    $options['metadata_name_value_pairs'] = elgg_extract('attribute_name_value_pairs', $options, []);
179
    $options['metadata_name_value_pairs_operator'] = elgg_extract('attribute_name_value_pairs_operator', $options, []);
180
181
    unset($options['attribute_name_value_pairs']);
182
    unset($options['attribute_name_value_pairs_operator']);
183
184
    return elgg_get_entities($options);
185
}
186
187
/**
188
 * Ban a user
189
 *
190
 * @param int    $user_guid The user guid
191
 * @param string $reason    A reason
192
 *
193
 * @return bool
194
 *
195
 * @deprecated Use \ElggUser->ban()
196
 */
197
function ban_user($user_guid, $reason = "") {
198
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use \ElggUser::ban()', '3.0');
199
200
	$user = get_user($user_guid);
201
	if (!$user) {
202
		return false;
203
	}
204
205
	return $user->ban($reason);
206
}
207
208
/**
209
 * Unban a user.
210
 *
211
 * @param int $user_guid Unban a user.
212
 *
213
 * @return bool
214
 *
215
 * @deprecated Use \ElggUser->unban()
216
 */
217
function unban_user($user_guid) {
218
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use \ElggUser::unban()', '3.0');
219
220
	$user = get_user($user_guid);
221
	if (!$user) {
222
		return false;
223
	}
224
225
	return $user->unban();
226
}
227
228
/**
229
 * Makes user $guid an admin.
230
 *
231
 * @param int $user_guid User guid
232
 *
233
 * @return bool
234
 *
235
 * @deprecated Use \ElggUser->makeAdmin()
236
 */
237
function make_user_admin($user_guid) {
238
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use \ElggUser::makeAdmin()', '3.0');
239
240
	$user = get_user($user_guid);
241
	if (!$user) {
242
		return false;
243
	}
244
245
	return $user->makeAdmin();
246
}
247
248
/**
249
 * Removes user $guid's admin flag.
250
 *
251
 * @param int $user_guid User GUID
252
 *
253
 * @return bool
254
 *
255
 * @deprecated Use \ElggUser->removeAdmin()
256
 */
257
function remove_user_admin($user_guid) {
258
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use \ElggUser::removeAdmin()', '3.0');
259
260
	$user = get_user($user_guid);
261
	if (!$user) {
262
		return false;
263
	}
264
265
	return $user->removeAdmin();
266
}
267
268
/**
269
 * Gets the validation status of a user.
270
 *
271
 * @param int $user_guid The user's GUID
272
 * @return bool|null Null means status was not set for this user.
273
 * @since 1.8.0
274
 *
275
 * @deprecated Use \ElggUser->isValidated()
276
 */
277
function elgg_get_user_validation_status($user_guid) {
278
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use \ElggUser::isValidated()', '3.0');
279
280
	$user = get_user($user_guid);
281
	if (!$user) {
282
		return false;
283
	}
284
285
	return $user->isValidated();
286
}
287
288
/**
289
 * Set the validation status for a user.
290
 *
291
 * @param int    $user_guid The user's GUID
292
 * @param bool   $status    Validated (true) or unvalidated (false)
293
 * @param string $method    Optional method to say how a user was validated
294
 * @return bool
295
 * @since 1.8.0
296
 *
297
 * @deprecated Use \ElggUser->setValidationStatus()
298
 */
299
function elgg_set_user_validation_status($user_guid, $status, $method = '') {
300
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use \ElggUser::setValidationStatus()', '3.0');
301
302
	$user = get_user($user_guid);
303
	if (!$user) {
304
		return false;
305
	}
306
307
	$user->setValidationStatus($status, $method);
308
	return true;
309
}
310
311
/**
312
 * Sets the last action time of the given user to right now.
313
 *
314
 * @param ElggUser|int $user The user or GUID
315
 * @return void
316
 *
317
 * @deprecated Use \ElggUser->setLastAction()
318
 */
319
function set_last_action($user) {
320
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use \ElggUser::setLastAction()', '3.0');
321
322
	if (!$user instanceof ElggUser) {
323
		$user = get_user($user);
324
	}
325
	if (!$user) {
326
		return;
327
	}
328
329
	$user->setLastAction();
330
}
331
332
/**
333
 * Sets the last logon time of the given user to right now.
334
 *
335
 * @param int $user_guid The user GUID
336
 * @return void
337
 *
338
 * @deprecated Use \ElggUser->setLastLogin()
339
 */
340
function set_last_login($user_guid) {
341
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use \ElggUser::setLastLogin()', '3.0');
342
343
	$user = get_user($user_guid);
344
	if (!$user) {
345
		return;
346
	}
347
348
	$user->setLastLogin();
349
}
350
351
/**
352
 * Update a specific piece of metadata.
353
 *
354
 * @param int    $id         ID of the metadata to update
355
 * @param string $name       Metadata name
356
 * @param string $value      Metadata value
357
 * @param string $value_type Value type
358
 *
359
 * @return bool
360
 *
361
 * @deprecated Use \ElggMetadata->save()
362
 */
363
function update_metadata($id, $name, $value, $value_type) {
364
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use ElggEntity setter or ElggEntity::setMetadata()', '3.0');
365
366
	$metadata = elgg_get_metadata_from_id($id);
367
	if (!$metadata) {
368
		return false;
369
	}
370
371
	$metadata->name = $name;
372
	$metadata->value_type = $value_type;
373
	$metadata->value = $value;
374
375
	return $metadata->save();
376
}
377
378
/**
379
 * Create a new metadata object, or update an existing one.
380
 *
381
 * Metadata can be an array by setting allow_multiple to true, but it is an
382
 * indexed array with no control over the indexing.
383
 *
384
 * @param int    $entity_guid    The entity to attach the metadata to
385
 * @param string $name           Name of the metadata
386
 * @param string $value          Value of the metadata
387
 * @param string $value_type     'text', 'integer', or '' for automatic detection
388
 * @param int    $ignored1       This argument is not used
389
 * @param null   $ignored2       This argument is not used
1 ignored issue
show
Documentation Bug introduced by
Are you sure the doc-type for parameter $ignored2 is correct as it would always require null to be passed?
Loading history...
390
 * @param bool   $allow_multiple Allow multiple values for one key. Default is false
391
 *
392
 * @return int|false id of metadata or false if failure
393
 *
394
 * @deprecated Use \ElggEntity setter or \Entity->setMetadata()
395
 */
396
function create_metadata($entity_guid, $name, $value, $value_type = '', $ignored1 = null,
1 ignored issue
show
The parameter $ignored1 is not used and could be removed. ( Ignorable by Annotation )

If this is a false-positive, you can also ignore this issue in your code via the ignore-unused  annotation

396
function create_metadata($entity_guid, $name, $value, $value_type = '', /** @scrutinizer ignore-unused */ $ignored1 = null,

This check looks for parameters that have been defined for a function or method, but which are not used in the method body.

Loading history...
397
						 $ignored2 = null, $allow_multiple = false) {
1 ignored issue
show
The parameter $ignored2 is not used and could be removed. ( Ignorable by Annotation )

If this is a false-positive, you can also ignore this issue in your code via the ignore-unused  annotation

397
						 /** @scrutinizer ignore-unused */ $ignored2 = null, $allow_multiple = false) {

This check looks for parameters that have been defined for a function or method, but which are not used in the method body.

Loading history...
398
	elgg_deprecated_notice(
399
		__FUNCTION__ . ' is deprecated. 
400
		Use ElggEntity setter or ElggEntity::setMetadata()',
401
		'3.0');
402
403
	$entity = get_entity($entity_guid);
404
	if (!$entity) {
405
		return false;
406
	}
407
408
	if ($allow_multiple) {
409
		return $entity->setMetadata($name, $value, $value_type, $allow_multiple);
410
	}
411
412
	$metadata = new ElggMetadata();
413
	$metadata->entity_guid = $entity_guid;
414
	$metadata->name = $name;
415
	$metadata->value_type = $value_type;
416
	$metadata->value = $value;
417
	return $metadata->save();
418
}
419
420
/**
421
 * Returns access collections owned by the entity
422
 *
423
 * @see add_access_collection()
424
 * @see get_members_of_access_collection()
425
 *
426
 * @param int $owner_guid GUID of the owner
427
 * @return \ElggAccessCollection[]|false
428
 *
429
 * @deprecated Use \Entity->getOwnedAccessCollections() or elgg_get_access_collections()
430
 */
431
function get_user_access_collections($owner_guid) {
432
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use \ElggEntity->getOwnedAccessCollections() or elgg_get_access_collections()', '3.0');
433
434
	return _elgg_services()->accessCollections->getEntityCollections(['owner_guid' => $owner_guid]);
435
}
436
437
438
/**
439
 * Returns entities based upon metadata.  Also accepts all
440
 * options available to elgg_get_entities().  Supports
441
 * the singular option shortcut.
442
 *
443
 * @note Using metadata_names and metadata_values results in a
444
 * "names IN (...) AND values IN (...)" clause.  This is subtly
445
 * differently than default multiple metadata_name_value_pairs, which use
446
 * "(name = value) AND (name = value)" clauses.
447
 *
448
 * When in doubt, use name_value_pairs.
449
 *
450
 * To ask for entities that do not have a metadata value, use a custom
451
 * where clause like this:
452
 *
453
 * 	$options['wheres'][] = "NOT EXISTS (
454
 *			SELECT 1 FROM {$dbprefix}metadata md
455
 *			WHERE md.entity_guid = e.guid
456
 *				AND md.name = $name
457
 *				AND md.value = $value)";
458
 *
459
 * @see elgg_get_entities
460
 *
461
 * @param array $options Array in format:
462
 *
463
 * 	metadata_names => null|ARR metadata names
464
 *
465
 * 	metadata_values => null|ARR metadata values
466
 *
467
 * 	metadata_name_value_pairs => null|ARR (
468
 *                                         name => 'name',
469
 *                                         value => 'value',
470
 *                                         'operand' => '=',
471
 *                                         'case_sensitive' => true
472
 *                                        )
473
 *                               Currently if multiple values are sent via
474
 *                               an array (value => array('value1', 'value2')
475
 *                               the pair's operand will be forced to "IN".
476
 *                               If passing "IN" as the operand and a string as the value,
477
 *                               the value must be a properly quoted and escaped string.
478
 *
479
 * 	metadata_name_value_pairs_operator => null|STR The operator to use for combining
480
 *                                        (name = value) OPERATOR (name = value); default AND
481
 *
482
 * 	metadata_case_sensitive => BOOL Overall Case sensitive
483
 *
484
 *  order_by_metadata => null|ARR array(
485
 *                                      'name' => 'metadata_text1',
486
 *                                      'direction' => ASC|DESC,
487
 *                                      'as' => text|integer
488
 *                                     )
489
 *                                Also supports array('name' => 'metadata_text1')
490
 *
491
 * @return \ElggEntity[]|mixed If count, int. If not count, array. false on errors.
492
 * @since 1.7.0
493
 *
494
 * @deprecated 3.0
495
 */
496
function elgg_get_entities_from_metadata(array $options = []) {
497
	elgg_deprecated_notice(
498
		__FUNCTION__ . ' has been deprecated.
499
		elgg_get_entities() now accepts all metadata options.
500
	', '3.0');
501
502
	return elgg_get_entities($options);
503
}
504
505
/**
506
 * Returns a list of entities filtered by provided metadata.
507
 *
508
 * @see elgg_get_entities
509
 *
510
 * @param array $options Options array
511
 *
512
 * @return array
513
 * @since 1.7.0
514
 * @deprecated 3.0
515
 */
516
function elgg_list_entities_from_metadata($options) {
517
	elgg_deprecated_notice(
518
		__FUNCTION__ . ' has been deprecated. Use elgg_list_entities().
519
	', '3.0');
520
521
	return elgg_list_entities($options);
522
}
523
524
/**
525
 * Returns entities based upon annotations.
526
 *
527
 * Entity creation time is selected as maxtime. To sort based upon
528
 * this, pass 'order_by' => 'maxtime asc' || 'maxtime desc'
529
 *
530
 * @see elgg_get_entities
531
 *
532
 * @param array $options Array in format:
533
 *
534
 * 	annotation_names => null|ARR annotations names
535
 *
536
 * 	annotation_values => null|ARR annotations values
537
 *
538
 * 	annotation_name_value_pairs => null|ARR (name = 'name', value => 'value',
539
 * 	'operator' => '=', 'case_sensitive' => true) entries.
540
 * 	Currently if multiple values are sent via an array (value => array('value1', 'value2')
541
 * 	the pair's operator will be forced to "IN".
542
 *
543
 * 	annotation_name_value_pairs_operator => null|STR The operator to use for combining
544
 *  (name = value) OPERATOR (name = value); default AND
545
 *
546
 * 	annotation_case_sensitive => BOOL Overall Case sensitive
547
 *
548
 *  order_by_annotation => null|ARR (array('name' => 'annotation_text1', 'direction' => ASC|DESC,
549
 *  'as' => text|integer),
550
 *
551
 *  Also supports array('name' => 'annotation_text1')
552
 *
553
 *  annotation_owner_guids => null|ARR guids for annotaiton owners
554
 *
555
 * @return mixed If count, int. If not count, array. false on errors.
556
 * @since 1.7.0
557
 */
558
function elgg_get_entities_from_annotations(array $options = []) {
559
	elgg_deprecated_notice(
560
		__FUNCTION__ . ' has been deprecated.
561
		elgg_get_entities() now accepts all annotation options
562
	', '3.0');
563
564
	return elgg_get_entities($options);
565
}
566
567
/**
568
 * Returns a viewable list of entities from annotations.
569
 *
570
 * @param array $options Options array
571
 *
572
 * @see elgg_get_entities_from_annotations()
573
 * @see elgg_list_entities()
574
 *
575
 * @return string
576
 * @deprecated 3.0
577
 */
578
function elgg_list_entities_from_annotations($options = []) {
579
	elgg_deprecated_notice(
580
		__FUNCTION__ . ' has been deprecated. Use elgg_list_entities().
581
	', '3.0');
582
	return elgg_list_entities($options);
583
}
584
585
586
/**
587
 * Return entities matching a given query joining against a relationship.
588
 *
589
 * By default the function finds relationship targets. E.g.:
590
 *
591
 *   // find groups with a particular member:
592
 *   $options = [
593
 *       'relationship' => 'member',
594
 *       'relationship_guid' => $member->guid,
595
 *   ];
596
 *
597
 *   // find people the user has friended
598
 *   $options = [
599
 *       'relationship' => 'friend',
600
 *       'relationship_guid' => $user->guid,
601
 *   ];
602
 *
603
 *   // find stuff created by friends (not in groups)
604
 *   $options = [
605
 *       'relationship' => 'friend',
606
 *       'relationship_guid' => $user->guid,
607
 *       'relationship_join_on' => 'container_guid',
608
 *   ];
609
 *
610
 * To find relationship subjects, set "inverse_relationship" to true. E.g.:
611
 *
612
 *   // find members of a particular group
613
 *   $options = [
614
 *       'relationship' => 'member',
615
 *       'relationship_guid' => $group->guid,
616
 *       'inverse_relationship' => true,
617
 *   ];
618
 *
619
 *   // find users who have friended the current user
620
 *   $options = [
621
 *       'relationship' => 'friend',
622
 *       'relationship_guid' => $user->guid,
623
 *       'inverse_relationship' => true,
624
 *   ];
625
 *
626
 * @note You may want to specify "type" because relationship types might be used for other entities.
627
 *
628
 * To ask for entities that do not have a particular relationship to an entity,
629
 * use a custom where clause like the following:
630
 *
631
 * 	$options['wheres'][] = "NOT EXISTS (
632
 *			SELECT 1 FROM {$db_prefix}entity_relationships
633
 *				WHERE guid_one = e.guid
634
 *				AND relationship = '$relationship'
635
 *		)";
636
 *
637
 * @see elgg_get_entities
638
 *
639
 * @param array $options Array in format:
640
 *
641
 *  relationship => null|STR Type of the relationship. E.g. "member"
642
 *
643
 *  relationship_guid => null|INT GUID of the subject of the relationship, unless "inverse_relationship" is set
644
 *                                to true, in which case this will specify the target.
645
 *
646
 *  inverse_relationship => false|BOOL Are we searching for relationship subjects? By default, the query finds
647
 *                                     targets of relationships.
648
 *
649
 *  relationship_join_on => null|STR How the entities relate: guid (default), container_guid, or owner_guid
650
 *                                   Examples using the relationship 'friend':
651
 *                                   1. use 'guid' if you want the user's friends
652
 *                                   2. use 'owner_guid' if you want the entities the user's friends own
653
 *                                      (including in groups)
654
 *                                   3. use 'container_guid' if you want the entities in the user's personal
655
 *                                      space (non-group)
656
 *
657
 * 	relationship_created_time_lower => null|INT Relationship created time lower boundary in epoch time
658
 *
659
 * 	relationship_created_time_upper => null|INT Relationship created time upper boundary in epoch time
660
 *
661
 * @return \ElggEntity[]|mixed If count, int. If not count, array. false on errors.
662
 * @since 1.7.0
663
 *
664
 * @deprecated 3.0
665
 */
666
function elgg_get_entities_from_relationship($options) {
667
	elgg_deprecated_notice(
668
		__FUNCTION__ . ' has been deprecated.
669
		elgg_get_entities() now accepts all relationship options.
670
	', '3.0');
671
672
	return elgg_get_entities($options);
673
}
674
675
/**
676
 * Returns a viewable list of entities by relationship
677
 *
678
 * @param array $options Options array for retrieval of entities
679
 *
680
 * @see elgg_list_entities()
681
 * @see elgg_get_entities_from_relationship()
682
 *
683
 * @return string The viewable list of entities
684
 * @deprecated 3.0
685
 */
686
function elgg_list_entities_from_relationship(array $options = []) {
687
	elgg_deprecated_notice(
688
		__FUNCTION__ . ' has been deprecated. Use elgg_list_entities().
689
	', '3.0');
690
691
	return elgg_list_entities($options);
692
}
693
694
/**
695
 * Returns entities based upon private settings.  Also accepts all
696
 * options available to elgg_get_entities().  Supports
697
 * the singular option shortcut.
698
 *
699
 * @see elgg_get_entities
700
 *
701
 * @param array $options Array in format:
702
 *
703
 * 	private_setting_names => null|ARR private setting names
704
 *
705
 * 	private_setting_values => null|ARR metadata values
706
 *
707
 * 	private_setting_name_value_pairs => null|ARR (
708
 *                                         name => 'name',
709
 *                                         value => 'value',
710
 *                                         'operand' => '=',
711
 *                                        )
712
 * 	                             Currently if multiple values are sent via
713
 *                               an array (value => array('value1', 'value2')
714
 *                               the pair's operand will be forced to "IN".
715
 *
716
 * 	private_setting_name_value_pairs_operator => null|STR The operator to use for combining
717
 *                                        (name = value) OPERATOR (name = value); default AND
718
 *
719
 *  private_setting_name_prefix => STR A prefix to apply to all private settings. Used to
720
 *                                     namespace plugin user settings or by plugins to namespace
721
 *                                     their own settings.
722
 *
723
 *
724
 * @return mixed int If count, int. If not count, array. false on errors.
725
 * @since 1.8.0
726
 * @deprecated 3.0
727
 */
728
function elgg_get_entities_from_private_settings(array $options = []) {
729
	elgg_deprecated_notice(
730
		__FUNCTION__ . ' has been deprecated.
731
		elgg_get_entities() now accepts all private settings options.
732
	', '3.0');
733
734
	return elgg_get_entities($options);
735
}
736
737
/**
738
 * Lists entities from an access collection
739
 *
740
 * @param array $options See elgg_list_entities() and elgg_get_entities_from_access_id()
741
 *
742
 * @see elgg_list_entities()
743
 * @see elgg_get_entities_from_access_id()
744
 *
745
 * @return string
746
 * @deprecated 3.0
747
 */
748
function elgg_list_entities_from_access_id(array $options = []) {
749
	elgg_deprecated_notice(
750
		__FUNCTION__ . ' has been deprecated. Use elgg_list_entities().
751
	', '3.0');
752
753
	return elgg_list_entities($options);
754
}
755
756
/**
757
 * Return entities based upon access id.
758
 *
759
 * @param array $options Any options accepted by {@link elgg_get_entities()} and
760
 * 	access_id => int The access ID of the entity.
761
 *
762
 * @see elgg_get_entities()
763
 * @return mixed If count, int. If not count, array. false on errors.
764
 * @since 1.7.0
765
 *
766
 * @deprected 3.0
767
 */
768
function elgg_get_entities_from_access_id(array $options = []) {
769
770
	elgg_deprecated_notice(
771
		__FUNCTION__ . ' has been deprecated.
772
		Use elgg_get_entities() with "access_ids" option.
773
	', '3.0');
774
775
	// restrict the resultset to access collection provided
776
	if (!isset($options['access_id']) && !isset($options['access_ids'])) {
777
		return false;
778
	}
779
780
	return elgg_get_entities($options);
781
}
782
783
/**
784
 * Get entities ordered by a mathematical calculation on annotation values
785
 *
786
 * @tip Note that this function uses { @link elgg_get_annotations() } to return a list of entities ordered by a mathematical
787
 * calculation on annotation values, and { @link elgg_get_entities_from_annotations() } to return a count of entities
788
 * if $options['count'] is set to a truthy value
789
 *
790
 * @param array $options An options array:
791
 * 	'calculation'            => The calculation to use. Must be a valid MySQL function.
792
 *                              Defaults to sum.  Result selected as 'annotation_calculation'.
793
 *                              Don't confuse this "calculation" option with the
794
 *                              "annotation_calculation" option to elgg_get_annotations().
795
 *                              This "calculation" option is applied to each entity's set of
796
 *                              annotations and is selected as annotation_calculation for that row.
797
 *                              See the docs for elgg_get_annotations() for proper use of the
798
 *                              "annotation_calculation" option.
799
 *	'order_by'               => The order for the sorting. Defaults to 'annotation_calculation desc'.
800
 *	'annotation_names'       => The names of annotations on the entity.
801
 *	'annotation_values'	     => The values of annotations on the entity.
802
 *
803
 *	'metadata_names'         => The name of metadata on the entity.
804
 *	'metadata_values'        => The value of metadata on the entitiy.
805
 *	'callback'               => Callback function to pass each row through.
806
 *                              @tip This function is different from other ege* functions,
807
 *                              as it uses a metastring-based getter function { @link elgg_get_annotations() },
808
 *                              therefore the callback function should be a derivative of { @link entity_row_to_elggstar() }
809
 *                              and not of { @link row_to_annotation() }
810
 *
811
 * @return \ElggEntity[]|int An array or a count of entities
812
 * @see elgg_get_annotations()
813
 * @see elgg_get_entities_from_annotations()
814
 *
815
 * @deprecated
816
 */
817
function elgg_get_entities_from_annotation_calculation($options) {
818
	elgg_deprecated_notice(
819
		__FUNCTION__ . ' has been deprecated.
820
		Use elgg_get_entities() with "annotation_sort_by_calculation" option.
821
		To sort in an ascending order, pass "order_by" => new OrderByClause("annotation_calculation", "asc")
822
	', '3.0');
823
824
	if (empty($options['count'])) {
825
		$options['annotation_sort_by_calculation'] = elgg_extract('calculation', $options, 'sum', false);
826
	}
827
	return Entities::find($options);
828
}
829
830
/**
831
 * List entities from an annotation calculation.
832
 *
833
 * @see elgg_get_entities_from_annotation_calculation()
834
 *
835
 * @param array $options An options array.
836
 *
837
 * @return string
838
 *
839
 * @deprecated
840
 */
841
function elgg_list_entities_from_annotation_calculation($options) {
842
	elgg_deprecated_notice(
843
		__FUNCTION__ . ' has been deprecated.
844
		Use elgg_get_entities() with "annotation_sort_by_calculation" option.
845
		To sort in an ascending order, pass "order_by" => new OrderByClause("annotation_calculation", "asc")
846
	', '3.0');
847
848
	if (empty($options['count'])) {
849
		$options['annotation_sort_by_calculation'] = elgg_extract('calculation', $options, 'sum', false);
850
	}
851
852
	return elgg_list_entities($options, 'elgg_get_entities');
853
}
854
855
856
/**
857
 * Enables or disables a metastrings-based object by its id.
858
 *
859
 * @warning To enable disabled metastrings you must first use
860
 * {@link access_show_hidden_entities()}.
861
 *
862
 * @param int    $id      The object's ID
863
 * @param string $enabled Value to set to: yes or no
864
 * @param string $type    Metastring type: metadata or annotation
865
 *
866
 * @return bool
867
 * @throws InvalidParameterException
868
 * @access private
869
 *
870
 * @deprecated
871
 */
872
function _elgg_set_metastring_based_object_enabled_by_id($id, $enabled, $type) {
873
874
	elgg_deprecated_notice(
875
		__FUNCTION__ . ' has been deprecated.
876
		Use ElggAnnotation::enable()
877
	', '3.0');
878
879
	if (!in_array($type, ['annotation', 'annotations'])) {
880
		return false;
881
	}
882
883
	$annotation = elgg_get_annotation_from_id($id);
884
	if (!$annotation) {
885
		return false;
886
	}
887
888
	if ($enabled === 'no' || $enabled === 0 || $enabled === false) {
889
		return $annotation->disable();
890
	} else if ($enabled === 'yes' || $enabled === 1 || $enabled === true) {
891
		return $annotation->enable();
892
	}
893
894
	return false;
895
}
896
897
/**
898
 * Returns a singular metastring-based object by its ID.
899
 *
900
 * @param int    $id   The metastring-based object's ID
901
 * @param string $type The type: annotation or metadata
902
 * @return \ElggExtender
903
 * @access private
904
 *
905
 * @deprecated
906
 */
907
function _elgg_get_metastring_based_object_from_id($id, $type) {
908
909
	elgg_deprecated_notice(
910
		__FUNCTION__ . ' has been deprecated.
911
		Use elgg_get_metadata_from_id() and elgg_get_annotation_from_id()
912
	', '3.0');
913
914
	$id = (int) $id;
915
	if (!$id) {
916
		return false;
917
	}
918
919
	if ($type == 'metadata') {
920
		$object = elgg_get_metadata_from_id($id);
921
	} else {
922
		$object = elgg_get_annotation_from_id($id);
923
	}
924
925
	return $object;
926
}
927
928
/**
929
 * Deletes a metastring-based object by its id
930
 *
931
 * @param int    $id   The object's ID
932
 * @param string $type The object's metastring type: annotation or metadata
933
 * @return bool
934
 * @access private
935
 *
936
 * @deprected
937
 */
938
function _elgg_delete_metastring_based_object_by_id($id, $type) {
939
940
	elgg_deprecated_notice(
941
		__FUNCTION__ . ' has been deprecated.
942
		Use ElggMetadata::delete() and ElggAnnotation::delete()
943
	', '3.0');
944
945
	switch ($type) {
946
		case 'annotations':
947
		case 'annotation':
948
			$object = elgg_get_annotation_from_id($id);
949
			break;
950
951
		case 'metadata':
952
			$object = elgg_get_metadata_from_id($id);
953
			break;
954
955
		default:
956
			return false;
957
	}
958
959
	if ($object) {
960
		return $object->delete();
961
	}
962
963
	return false;
964
}
965
966
/**
967
 * Get the URL for this metadata
968
 *
969
 * By default this links to the export handler in the current view.
970
 *
971
 * @param int $id Metadata ID
972
 *
973
 * @return mixed
974
 * @deprecated 3.0
975
 */
976
function get_metadata_url($id) {
977
	elgg_deprecated_notice(__FUNCTION__ . ' has been deprecated and will be removed', '3.0');
978
	$metadata = elgg_get_metadata_from_id($id);
979
	if (!$metadata instanceof ElggMetadata) {
980
		return;
981
	}
982
983
	return $metadata->getURL();
984
}
985
986
987
/**
988
 * Create a new annotation.
989
 *
990
 * @param int    $entity_guid GUID of entity to be annotated
991
 * @param string $name        Name of annotation
992
 * @param string $value       Value of annotation
993
 * @param string $value_type  Type of value (default is auto detection)
994
 * @param int    $owner_guid  Owner of annotation (default is logged in user)
995
 * @param int    $access_id   Access level of annotation
996
 *
997
 * @return int|bool id on success or false on failure
998
 * @deprecated 3.0
999
 */
1000
function create_annotation($entity_guid, $name, $value, $value_type = '', $owner_guid = 0, $access_id = ACCESS_PRIVATE) {
1001
	elgg_deprecated_notice(
1002
		__FUNCTION__ . ' has been deprecated.
1003
		Use ElggAnnotation::save() or ElggEntity::annotate()
1004
		', '3.0'
1005
	);
1006
1007
	$annotation = new ElggAnnotation();
1008
	$annotation->entity_guid = $entity_guid;
1009
	$annotation->name = $name;
1010
	$annotation->value_type = $value_type;
1011
	$annotation->value = $value;
1012
	$annotation->owner_guid = $owner_guid;
1013
	$annotation->access_id = $access_id;
1014
1015
	return $annotation->save();
1016
}
1017
1018
/**
1019
 * Update an annotation.
1020
 *
1021
 * @param int    $annotation_id Annotation ID
1022
 * @param string $name          Name of annotation
1023
 * @param string $value         Value of annotation
1024
 * @param string $value_type    Type of value
1025
 * @param int    $owner_guid    Owner of annotation
1026
 * @param int    $access_id     Access level of annotation
1027
 *
1028
 * @return bool
1029
 */
1030
function update_annotation($annotation_id, $name, $value, $value_type, $owner_guid, $access_id) {
1031
	elgg_deprecated_notice(
1032
		__FUNCTION__ . ' has been deprecated.
1033
		Use ElggAnnotation::save() or ElggEntity::annotate()
1034
		', '3.0'
1035
	);
1036
1037
	$annotation = elgg_get_annotation_from_id($annotation_id);
1038
	if (!$annotation) {
1039
		return false;
1040
	}
1041
1042
	$annotation->name = $name;
1043
	$annotation->value_type = $value_type;
1044
	$annotation->value = $value;
1045
	$annotation->owner_guid = $owner_guid;
1046
	$annotation->access_id = $access_id;
1047
1048
	return $annotation->save();
1049
}
1050
1051
/**
1052
 * Delete objects with a delete() method.
1053
 *
1054
 * Used as a callback for \ElggBatch.
1055
 *
1056
 * @param object $object The object to disable
1057
 * @return bool
1058
 * @access private
1059
 *
1060
 * @deprecated 3.0
1061
 */
1062
function elgg_batch_delete_callback($object) {
1063
	elgg_deprecated_notice(__FUNCTION__ . ' has been deprecated.', '3.0');
1064
1065
	// our db functions return the number of rows affected...
1066
	return $object->delete() ? true : false;
1067
}
1068