• Home
  • Features
  • Pricing
  • Docs
  • Announcements
  • Sign In

codeigniter4 / shield / 22001236210

13 Feb 2026 08:11PM UTC coverage: 92.812% (+0.02%) from 92.788%
22001236210

Pull #1309

github

web-flow
Merge 31495fbce into 903ae0137
Pull Request #1309: feat: Support hierarchical permissions in method

2905 of 3130 relevant lines covered (92.81%)

77.59 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

96.25
/src/Models/UserModel.php
1
<?php
2

3
declare(strict_types=1);
4

5
/**
6
 * This file is part of CodeIgniter Shield.
7
 *
8
 * (c) CodeIgniter Foundation <admin@codeigniter.com>
9
 *
10
 * For the full copyright and license information, please view
11
 * the LICENSE file that was distributed with this source code.
12
 */
13

14
namespace CodeIgniter\Shield\Models;
15

16
use CodeIgniter\Database\Exceptions\DataException;
17
use CodeIgniter\Database\RawSql;
18
use CodeIgniter\I18n\Time;
19
use CodeIgniter\Shield\Authentication\Authenticators\Session;
20
use CodeIgniter\Shield\Entities\User;
21
use CodeIgniter\Shield\Entities\UserIdentity;
22
use CodeIgniter\Shield\Exceptions\InvalidArgumentException;
23
use CodeIgniter\Shield\Exceptions\LogicException;
24
use CodeIgniter\Shield\Exceptions\ValidationException;
25
use Faker\Generator;
26

27
/**
28
 * @phpstan-consistent-constructor
29
 */
30
class UserModel extends BaseModel
31
{
32
    protected $primaryKey     = 'id';
33
    protected $returnType     = User::class;
34
    protected $useSoftDeletes = true;
35
    protected $allowedFields  = [
36
        'username',
37
        'status',
38
        'status_message',
39
        'active',
40
        'last_active',
41
    ];
42
    protected $useTimestamps = true;
43
    protected $afterFind     = ['fetchIdentities', 'fetchGroups', 'fetchPermissions'];
44
    protected $afterInsert   = ['saveEmailIdentity'];
45
    protected $afterUpdate   = ['saveEmailIdentity'];
46

47
    /**
48
     * Whether identity records should be included
49
     * when user records are fetched from the database.
50
     */
51
    protected bool $fetchIdentities = false;
52

53
    /**
54
     * Whether groups should be included
55
     * when user records are fetched from the database.
56
     */
57
    protected bool $fetchGroups = false;
58

59
    /**
60
     * Whether permissions should be included
61
     * when user records are fetched from the database.
62
     */
63
    protected bool $fetchPermissions = false;
64

65
    /**
66
     * Save the User for afterInsert and afterUpdate
67
     */
68
    protected ?User $tempUser = null;
69

70
    protected function initialize(): void
71
    {
72
        parent::initialize();
897 ✔
73

74
        $this->table = $this->tables['users'];
897 ✔
75
    }
76

77
    /**
78
     * Mark the next find* query to include identities
79
     *
80
     * @return $this
81
     */
82
    public function withIdentities(): self
83
    {
84
        $this->fetchIdentities = true;
15 ✔
85

86
        return $this;
15 ✔
87
    }
88

89
    /**
90
     * Mark the next find* query to include groups
91
     *
92
     * @return $this
93
     */
94
    public function withGroups(): self
95
    {
96
        $this->fetchGroups = true;
24 ✔
97

98
        return $this;
24 ✔
99
    }
100

101
    /**
102
     * Mark the next find* query to include permissions
103
     *
104
     * @return $this
105
     */
106
    public function withPermissions(): self
107
    {
108
        $this->fetchPermissions = true;
21 ✔
109

110
        return $this;
21 ✔
111
    }
112

113
    /**
114
     * Populates identities for all records
115
     * returned from a find* method. Called
116
     * automatically when $this->fetchIdentities == true
117
     *
118
     * Model event callback called by `afterFind`.
119
     */
120
    protected function fetchIdentities(array $data): array
121
    {
122
        if (! $this->fetchIdentities) {
777 ✔
123
            return $data;
777 ✔
124
        }
125

126
        $userIds = $data['singleton']
15 ✔
127
            ? array_column($data, 'id')
6 ✔
128
            : array_column($data['data'], 'id');
9 ✔
129

130
        if ($userIds === []) {
15 ✔
131
            return $data;
6 ✔
132
        }
133

134
        /** @var UserIdentityModel $identityModel */
135
        $identityModel = model(UserIdentityModel::class);
9 ✔
136

137
        // Get our identities for all users
138
        $identities = $identityModel->getIdentitiesByUserIds($userIds);
9 ✔
139

140
        if (empty($identities)) {
9 ✔
141
            return $data;
×
142
        }
143

144
        $mappedUsers = $this->assignIdentities($data, $identities);
9 ✔
145

146
        $data['data'] = $data['singleton'] ? $mappedUsers[$data['id']] : $mappedUsers;
9 ✔
147

148
        return $data;
9 ✔
149
    }
150

151
    /**
152
     * Map our users by ID to make assigning simpler
153
     *
154
     * @param array              $data       Event $data
155
     * @param list<UserIdentity> $identities
156
     *
157
     * @return         list<User>              UserId => User object
158
     * @phpstan-return array<int|string, User> UserId => User object
159
     */
160
    private function assignIdentities(array $data, array $identities): array
161
    {
162
        $mappedUsers    = [];
9 ✔
163
        $userIdentities = [];
9 ✔
164

165
        $users = $data['singleton'] ? [$data['data']] : $data['data'];
9 ✔
166

167
        foreach ($users as $user) {
9 ✔
168
            $mappedUsers[$user->id] = $user;
9 ✔
169
        }
170
        unset($users);
9 ✔
171

172
        // Now group the identities by user
173
        foreach ($identities as $identity) {
9 ✔
174
            $userIdentities[$identity->user_id][] = $identity;
9 ✔
175
        }
176
        unset($identities);
9 ✔
177

178
        // Now assign the identities to the user
179
        foreach ($userIdentities as $userId => $identityArray) {
9 ✔
180
            $mappedUsers[$userId]->identities = $identityArray;
9 ✔
181
        }
182
        unset($userIdentities);
9 ✔
183

184
        return $mappedUsers;
9 ✔
185
    }
186

187
    /**
188
     * Populates groups for all records
189
     * returned from a find* method. Called
190
     * automatically when $this->fetchGroups == true
191
     *
192
     * Model event callback called by `afterFind`.
193
     */
194
    protected function fetchGroups(array $data): array
195
    {
196
        if (! $this->fetchGroups) {
777 ✔
197
            return $data;
777 ✔
198
        }
199

200
        $userIds = $data['singleton']
24 ✔
201
            ? array_column($data, 'id')
15 ✔
202
            : array_column($data['data'], 'id');
9 ✔
203

204
        if ($userIds === []) {
24 ✔
205
            return $data;
6 ✔
206
        }
207

208
        /** @var GroupModel $groupModel */
209
        $groupModel = model(GroupModel::class);
18 ✔
210

211
        // Get our groups for all users
212
        $groups = $groupModel->getGroupsByUserIds($userIds);
18 ✔
213

214
        $mappedUsers = $this->assignProperties($data, $groups, 'groups');
18 ✔
215

216
        $data['data'] = $data['singleton'] ? $mappedUsers[$data['id']] : $mappedUsers;
18 ✔
217

218
        return $data;
18 ✔
219
    }
220

221
    /**
222
     * Populates permissions for all records
223
     * returned from a find* method. Called
224
     * automatically when $this->fetchPermissions == true
225
     *
226
     * Model event callback called by `afterFind`.
227
     */
228
    protected function fetchPermissions(array $data): array
229
    {
230
        if (! $this->fetchPermissions) {
777 ✔
231
            return $data;
777 ✔
232
        }
233

234
        $userIds = $data['singleton']
21 ✔
235
            ? array_column($data, 'id')
12 ✔
236
            : array_column($data['data'], 'id');
9 ✔
237

238
        if ($userIds === []) {
21 ✔
239
            return $data;
6 ✔
240
        }
241

242
        /** @var PermissionModel $permissionModel */
243
        $permissionModel = model(PermissionModel::class);
15 ✔
244

245
        $permissions = $permissionModel->getPermissionsByUserIds($userIds);
15 ✔
246

247
        $mappedUsers = $this->assignProperties($data, $permissions, 'permissions');
15 ✔
248

249
        $data['data'] = $data['singleton'] ? $mappedUsers[$data['id']] : $mappedUsers;
15 ✔
250

251
        return $data;
15 ✔
252
    }
253

254
    /**
255
     * Map our users by ID to make assigning simpler
256
     *
257
     * @param array       $data       Event $data
258
     * @param list<array> $properties
259
     * @param string      $type       One of: 'groups' or 'permissions'
260
     *
261
     * @return list<User> UserId => User object
262
     */
263
    private function assignProperties(array $data, array $properties, string $type): array
264
    {
265
        $mappedUsers = [];
24 ✔
266

267
        $users = $data['singleton'] ? [$data['data']] : $data['data'];
24 ✔
268

269
        foreach ($users as $user) {
24 ✔
270
            $mappedUsers[$user->id] = $user;
24 ✔
271
        }
272
        unset($users);
24 ✔
273

274
        // Build method name
275
        $method = 'set' . ucfirst($type) . 'Cache';
24 ✔
276

277
        // Assign properties to all users (empty array if no properties found)
278
        foreach ($mappedUsers as $userId => $user) {
24 ✔
279
            $propertyArray = $properties[$userId] ?? [];
24 ✔
280
            $user->{$method}($propertyArray);
24 ✔
281
        }
282
        unset($properties);
24 ✔
283

284
        return $mappedUsers;
24 ✔
285
    }
286

287
    /**
288
     * Adds a user to the default group.
289
     * Used during registration.
290
     */
291
    public function addToDefaultGroup(User $user): void
292
    {
293
        $defaultGroup = setting('AuthGroups.defaultGroup');
21 ✔
294

295
        /** @var GroupModel $groupModel */
296
        $groupModel = model(GroupModel::class);
21 ✔
297

298
        if (empty($defaultGroup) || ! $groupModel->isValidGroup($defaultGroup)) {
21 ✔
299
            throw new InvalidArgumentException(lang('Auth.unknownGroup', [$defaultGroup ?? '--not found--']));
×
300
        }
301

302
        $user->addGroup($defaultGroup);
21 ✔
303
    }
304

305
    public function fake(Generator &$faker): User
306
    {
307
        $this->checkReturnType();
756 ✔
308

309
        return new $this->returnType([
756 ✔
310
            'username' => $faker->unique()->userName(),
756 ✔
311
            'active'   => true,
756 ✔
312
        ]);
756 ✔
313
    }
314

315
    /**
316
     * Locates a User object by ID.
317
     *
318
     * @param int|string $id
319
     */
320
    public function findById($id): ?User
321
    {
322
        return $this->find($id);
267 ✔
323
    }
324

325
    /**
326
     * Locate a User object by the given credentials.
327
     *
328
     * @param array<string, string> $credentials
329
     */
330
    public function findByCredentials(array $credentials): ?User
331
    {
332
        // Email is stored in an identity so remove that here
333
        $email = $credentials['email'] ?? null;
144 ✔
334
        unset($credentials['email']);
144 ✔
335

336
        if ($email === null && $credentials === []) {
144 ✔
337
            return null;
3 ✔
338
        }
339

340
        // any of the credentials used should be case-insensitive
341
        foreach ($credentials as $key => $value) {
144 ✔
342
            $this->where(
9 ✔
343
                'LOWER(' . $this->db->protectIdentifiers($this->table . ".{$key}") . ')',
9 ✔
344
                strtolower($value),
9 ✔
345
            );
9 ✔
346
        }
347

348
        if ($email !== null) {
144 ✔
349
            /** @var array<string, int|string|null>|null $data */
350
            $data = $this->select(
135 ✔
351
                sprintf('%1$s.*, %2$s.secret as email, %2$s.secret2 as password_hash', $this->table, $this->tables['identities']),
135 ✔
352
            )
135 ✔
353
                ->join($this->tables['identities'], sprintf('%1$s.user_id = %2$s.id', $this->tables['identities'], $this->table))
135 ✔
354
                ->where($this->tables['identities'] . '.type', Session::ID_TYPE_EMAIL_PASSWORD)
135 ✔
355
                ->where(
135 ✔
356
                    'LOWER(' . $this->db->protectIdentifiers($this->tables['identities'] . '.secret') . ')',
135 ✔
357
                    strtolower($email),
135 ✔
358
                )
135 ✔
359
                ->asArray()
135 ✔
360
                ->first();
135 ✔
361

362
            if ($data === null) {
135 ✔
363
                return null;
33 ✔
364
            }
365

366
            $email = $data['email'];
102 ✔
367
            unset($data['email']);
102 ✔
368
            $password_hash = $data['password_hash'];
102 ✔
369
            unset($data['password_hash']);
102 ✔
370

371
            $this->checkReturnType();
102 ✔
372

373
            $user                = new $this->returnType($data);
102 ✔
374
            $user->email         = $email;
102 ✔
375
            $user->password_hash = $password_hash;
102 ✔
376
            $user->syncOriginal();
102 ✔
377

378
            return $user;
102 ✔
379
        }
380

381
        return $this->first();
9 ✔
382
    }
383

384
    /**
385
     * Activate a User.
386
     */
387
    public function activate(User $user): void
388
    {
389
        $user->active = true;
×
390

391
        $this->save($user);
×
392
    }
393

394
    /**
395
     * Override the BaseModel's `insert()` method.
396
     * If you pass User object, also inserts Email Identity.
397
     *
398
     * @param array|User $row
399
     *
400
     * @return int|string|true Insert ID if $returnID is true
401
     *
402
     * @throws ValidationException
403
     */
404
    public function insert($row = null, bool $returnID = true)
405
    {
406
        // Clone User object for not changing the passed object.
407
        $this->tempUser = $row instanceof User ? clone $row : null;
774 ✔
408

409
        $result = parent::insert($row, $returnID);
774 ✔
410

411
        $this->checkQueryReturn($result);
774 ✔
412

413
        return $returnID ? $this->insertID : $result;
774 ✔
414
    }
415

416
    /**
417
     * Override the BaseModel's `update()` method.
418
     * If you pass User object, also updates Email Identity.
419
     *
420
     * @param int|list<int|string>|RawSql|string|null $id
421
     * @param array|User                              $row
422
     *
423
     * @return true if the update is successful
424
     *
425
     * @throws ValidationException
426
     */
427
    public function update($id = null, $row = null): bool
428
    {
429
        // Clone User object for not changing the passed object.
430
        $this->tempUser = $row instanceof User ? clone $row : null;
90 ✔
431

432
        try {
433
            /** @throws DataException */
434
            $result = parent::update($id, $row);
90 ✔
435
        } catch (DataException $e) {
25 ✔
436
            // When $data is an array.
437
            if ($this->tempUser === null) {
25 ✔
438
                throw $e;
3 ✔
439
            }
440

441
            $messages = [
22 ✔
442
                lang('Database.emptyDataset', ['update']),
22 ✔
443
            ];
22 ✔
444

445
            if (in_array($e->getMessage(), $messages, true)) {
22 ✔
446
                $this->tempUser->saveEmailIdentity();
22 ✔
447

448
                return true;
22 ✔
449
            }
450

451
            throw $e;
×
452
        }
453

454
        $this->checkQueryReturn($result);
72 ✔
455

456
        return true;
72 ✔
457
    }
458

459
    /**
460
     * Override the BaseModel's `save()` method.
461
     * If you pass User object, also updates Email Identity.
462
     *
463
     * @param array|User $row
464
     *
465
     * @return true if the save is successful
466
     *
467
     * @throws ValidationException
468
     */
469
    public function save($row): bool
470
    {
471
        $result = parent::save($row);
111 ✔
472

473
        $this->checkQueryReturn($result);
108 ✔
474

475
        return true;
108 ✔
476
    }
477

478
    /**
479
     * Save Email Identity
480
     *
481
     * Model event callback called by `afterInsert` and `afterUpdate`.
482
     */
483
    protected function saveEmailIdentity(array $data): array
484
    {
485
        // If insert()/update() gets an array data, do nothing.
486
        if ($this->tempUser === null) {
774 ✔
487
            return $data;
30 ✔
488
        }
489

490
        // Insert
491
        if ($this->tempUser->id === null) {
771 ✔
492
            /** @var User $user */
493
            $user = $this->find($this->db->insertID());
750 ✔
494

495
            // If you get identity (email/password), the User object must have the id.
496
            $this->tempUser->id = $user->id;
750 ✔
497

498
            $user->email         = $this->tempUser->email ?? '';
750 ✔
499
            $user->password      = $this->tempUser->password ?? '';
750 ✔
500
            $user->password_hash = $this->tempUser->password_hash ?? '';
750 ✔
501

502
            $user->saveEmailIdentity();
750 ✔
503
            $this->tempUser = null;
750 ✔
504

505
            return $data;
750 ✔
506
        }
507

508
        // Update
509
        $this->tempUser->saveEmailIdentity();
77 ✔
510
        $this->tempUser = null;
77 ✔
511

512
        return $data;
77 ✔
513
    }
514

515
    /**
516
     * Updates the user's last active date.
517
     */
518
    public function updateActiveDate(User $user): void
519
    {
520
        assert($user->last_active instanceof Time);
521

522
        // Safe date string for database
523
        $last_active = $this->timeToDate($user->last_active);
39 ✔
524

525
        $this->builder()
39 ✔
526
            ->set('last_active', $last_active)
39 ✔
527
            ->where('id', $user->id)
39 ✔
528
            ->update();
39 ✔
529
    }
530

531
    private function checkReturnType(): void
532
    {
533
        if (! is_a($this->returnType, User::class, true)) {
783 ✔
534
            throw new LogicException('Return type must be a subclass of ' . User::class);
×
535
        }
536
    }
537

538
    /**
539
     * Returns a new User Entity.
540
     *
541
     * @param array<string, array<array-key, mixed>|bool|float|int|object|string|null> $data (Optional) user data
542
     */
543
    public function createNewUser(array $data = []): User
544
    {
545
        return new $this->returnType($data);
18 ✔
546
    }
547
}
STATUS · Troubleshooting · Open an Issue · Sales · Support · CAREERS · ENTERPRISE · START FREE TRIAL · SCHEDULE DEMO
ANNOUNCEMENTS · TWITTER · TOS & SLA · Supported CI Services · What's a CI service? · Automated Testing

© 2026 Coveralls, Inc