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

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

Checks if the types of returned expressions are compatible with the documented types.

Best Practice Bug Major
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)) {
89
		elgg_register_admin_menu_item($section, $parent_id);
90
	}
91
92
	// in the admin section parents never have links
93
	if ($parent_id) {
94
		$href = "admin/$parent_id/$menu_id";
95
	} else {
96
		$href = "admin/$menu_id";
97
	}
98
99
	$name = $menu_id;
100
	if ($parent_id) {
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 = '*') {
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) {
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
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,
397
						 $ignored2 = null, $allow_multiple = false) {
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);
1 ignored issue
show
Bug Best Practice introduced by
The expression return elgg_list_entities($options) returns the type string which is incompatible with the documented return type array.
Loading history...
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;
1 ignored issue
show
Bug Best Practice introduced by
The expression return false returns the type false which is incompatible with the documented return type ElggExtender.
Loading history...
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;
0 ignored issues
show
Bug Best Practice introduced by
The expression return $object returns the type false which is incompatible with the documented return type ElggExtender.
Loading history...
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
1069
/**
1070
 * Sanitise file paths ensuring that they begin and end with slashes etc.
1071
 *
1072
 * @param string $path         The path
1073
 * @param bool   $append_slash Add tailing slash
1074
 *
1075
 * @return string
1076
 * @deprecated 3.0
1077
 */
1078
function sanitise_filepath($path, $append_slash = true) {
1079
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use \\Elgg\\Project\\Paths::sanitize().', 3.0);
1080
1081
	return \Elgg\Project\Paths::sanitize($path, $append_slash);
1082
}
1083
1084
/**
1085
 * Registers a page handler for a particular identifier
1086
 *
1087
 * For example, you can register a function called 'blog_page_handler' for the identifier 'blog'
1088
 * For all URLs  http://yoururl/blog/*, the blog_page_handler() function will be called.
1089
 * The part of the URL marked with * above will be exploded on '/' characters and passed as an
1090
 * array to that function.
1091
 * For example, the URL http://yoururl/blog/username/friends/ would result in the call:
1092
 * blog_page_handler(array('username','friends'), blog);
1093
 *
1094
 * A request to register a page handler with the same identifier as previously registered
1095
 * handler will replace the previous one.
1096
 *
1097
 * The context is set to the identifier before the registered
1098
 * page handler function is called. For the above example, the context is set to 'blog'.
1099
 *
1100
 * Page handlers should return true to indicate that they handled the request.
1101
 * Requests not handled are forwarded to the front page with a reason of 404.
1102
 * Plugins can register for the 'forward', '404' plugin hook. @see forward()
1103
 *
1104
 * @param string $identifier The page type identifier
1105
 * @param string $function   Your function name
1106
 *
1107
 * @return bool Depending on success
1108
 * @deprecated 3.0
1109
 */
1110
function elgg_register_page_handler($identifier, callable $function) {
1111
	elgg_deprecated_notice(
1112
		__FUNCTION__ . ' has been deprecated. 
1113
		Use elgg_register_route() to register a named route or define it in elgg-plugin.php',
1114
		'3.0'
1115
	);
1116
	return _elgg_services()->router->registerPageHandler($identifier, $function);
1117
}
1118
1119
/**
1120
 * Unregister a page handler for an identifier
1121
 *
1122
 * Note: to replace a page handler, call elgg_register_page_handler()
1123
 *
1124
 * @param string $identifier The page type identifier
1125
 *
1126
 * @since 1.7.2
1127
 * @return void
1128
 * @deprecated
1129
 */
1130
function elgg_unregister_page_handler($identifier) {
1131
	elgg_deprecated_notice(
1132
		__FUNCTION__ . ' has been deprecated. 
1133
		Use new routing API to register and unregister routes.',
1134
		'3.0'
1135
	);
1136
	_elgg_services()->router->unregisterPageHandler($identifier);
1137
}
1138
1139
/**
1140
 * Alias of elgg_gatekeeper()
1141
 *
1142
 * Used at the top of a page to mark it as logged in users only.
1143
 *
1144
 * @return void
1145
 * @throws \Elgg\GatekeeperException
1146
 * @deprecated 3.0
1147
 */
1148
function gatekeeper() {
1149
	elgg_deprecated_notice(__FUNCTION__ . ' is deprecated. Use elgg_gatekeeper()', '3.0');
1150
	elgg_gatekeeper();
1151
}
1152
1153
/**
1154
 * Alias of elgg_admin_gatekeeper()
1155
 *
1156
 * Used at the top of a page to mark it as logged in admin or siteadmin only.
1157
 *
1158
 * @return void
1159
 * @throws \Elgg\GatekeeperException
1160
 * @deprecated 3.0