vendor/adldap2/adldap2/docs/models/traits/has-member-of.md

   1 # HasMemberOf Trait
   2
   3 Models that contain this trait, have the ability to be apart of a group.
   4
   5 There's many helpful methods to assist you in all of the operations related to group membership, let's get started!
   6
   7 ## Retrieving Groups
   8
   9 To retrieve the groups that a model is apart of, call the `getGroups()` method:
  10
  11 ```php
  12 $user = $provider->search()->users()->find('jdoe');
  13
  14 $groups = $user->getGroups();
  15
  16 foreach ($groups as $group) {
  17
  18     $group->getCommonName(); // ex. 'Accounting'
  19
  20 }
  21 ```
  22
  23 We can also pass in specific fields we need from the returned groups to speed up our queries.
  24
  25 For example, if we only need the groups common name:
  26
  27 ```php
  28 // Group models will be returned with only their common name.
  29 $groups = $user->getGroups(['cn']);
  30 ```
  31
  32 However, calling `getGroups()` will only retrieve the models immediate groups (non-recursive).
  33
  34 To retrieve nested groups, pass in `true` into the second parameter:
  35
  36 ```php
  37 $groups = $user->getGroups([], $recursive = true);
  38 ```
  39
  40 ## Retrieve Group Names
  41
  42 If you only want the models group names, call the `getGroupNames()` method:
  43
  44 ```php
  45 $names = $user->getGroupNames();
  46
  47 foreach ($names as $name) {
  48
  49     echo $name; // ex. 'Accounting'
  50
  51 }
  52 ```
  53
  54 However, this method will also retrieve only the immediate groups names
  55 much like the `getGroups()` method. You'll need to pass in `true` in
  56 the first parameter to retrieve results recursively.
  57
  58 ```php
  59 $names = $user->getGroupNames($recursive = true);
  60 ```
  61
  62 ## Checking if the Model is apart of a Group
  63
  64 To check if a model is apart of a certain group, use the `inGroup()` method:
  65
  66 ```php
  67 $group = $provider->search()->groups()->find('Office');
  68
  69 if ($user->inGroup($group)) {
  70
  71     //
  72
  73 }
  74 ```
  75
  76 You can also check for multiple memberships by passing in an array of groups:
  77
  78 ```php
  79 $groups = $provider->search()->findManyBy('cn', ['Accounting', 'Office']));
  80
  81 if ($user->inGroup($groups->toArray()) {
  82
  83     // This user is apart of the 'Accounting' and 'Office' group!
  84
  85 }
  86 ```
  87
  88 > **Note**: Much like the other methods above, you'll need to provide a `$recursive`
  89 > flag to the `inGroup()` method if you'd like recursive results included.
  90
  91 We can also provide distinguished names instead of Group model instances:
  92
  93 ```php
  94 $dns = [
  95     'cn=Accounting,ou=Groups,dc=acme,dc=org',
  96     'cn=Office,ou=Groups,dc=acme,dc=org',
  97 ];
  98
  99 if ($user->inGroup($dns, $recursive = true)) {
 100
 101     //
 102
 103 }
 104 ```
 105
 106 Or, we can also just provide the name(s) of the group(s).
 107
 108 ```php
 109 $names = [
 110     'Accounting',
 111     'Office',
 112 ];
 113
 114 if ($user->inGroup($names, $recursive = true)) {
 115
 116     //
 117
 118 }
 119 ```
 120
 121 ## Adding a Group
 122
 123 To add the model to a specific group, call the `addGroup()` method:
 124
 125 ```php
 126 $group = $provider->search()->groups()->find('Accounting');
 127
 128 // You can either provide a Group model:
 129 if ($user->addGroup($group)) {
 130
 131     //
 132
 133 }
 134
 135 // Or a Groups DN:
 136 if ($user->addGroup('cn=Accounting,ou=Groups,dc=acme,dc=org')) {
 137
 138     //
 139
 140 }
 141 ```
 142
 143 > **Note**: You do not need to call the `save()` method for adding / removing groups.
 144 > This is done automatically so you can perform clean `if` statements on the method.
 145
 146 ## Removing a Group
 147
 148 To remove the model from a specific group, call the `removeGroup()` method:
 149
 150 ```php
 151 $group = $user->getGroups()->first();
 152
 153 // You can either provide a Group model:
 154 if ($user->removeGroup($group)) {
 155
 156     //
 157
 158 }
 159
 160 // Or the groups DN:
 161 if ($user->removeGroup('cn=Accounting,ou=Office Groups,dc=acme,dc=org')) {
 162
 163     //
 164
 165 }
 166 ```