fs
f4ce9f3378
- Add single-line class docblocks to all 59 repository classes and interfaces describing scope and responsibility - Add multi-line docblocks to key services documenting business rules: AuthService (6-step login cascade), ImportService (3-phase CSV workflow), TenantScopeService (strict/permissive modes), PermissionService (RBAC resolution + two-tier caching), UserAccountService (atomicity + audit) - Add transaction(callable) wrapper to DatabaseSessionRepository to DRY up begin/commit/rollback boilerplate Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
386 lines
18 KiB
PHP
386 lines
18 KiB
PHP
<?php
|
|
|
|
namespace MintyPHP\Repository\User;
|
|
|
|
use MintyPHP\DB;
|
|
use MintyPHP\Repository\Support\RepoQuery;
|
|
|
|
/** Builds and executes complex user list queries with search, date, role, department, and custom field filters. */
|
|
class UserListQueryRepository implements UserListQueryRepositoryInterface
|
|
{
|
|
private function buildUserFilters(array $options): array
|
|
{
|
|
$search = trim((string) ($options['search'] ?? ''));
|
|
$active = $options['active'] ?? null;
|
|
$createdFrom = trim((string) ($options['created_from'] ?? ''));
|
|
$createdTo = trim((string) ($options['created_to'] ?? ''));
|
|
$tenant = trim((string) ($options['tenant'] ?? ''));
|
|
$tenantUuids = array_filter(array_map('trim', explode(',', (string) ($options['tenants'] ?? ''))));
|
|
$roleIds = RepoQuery::normalizeIdList($options['roles'] ?? []);
|
|
$departmentIds = RepoQuery::normalizeIdList($options['departments'] ?? []);
|
|
$emailVerified = $options['email_verified'] ?? null;
|
|
$loginStatus = $options['login_status'] ?? null;
|
|
$customFieldFilterSpec = is_array($options['customFieldFilterSpec'] ?? null)
|
|
? $options['customFieldFilterSpec']
|
|
: [];
|
|
$customFieldFilters = is_array($customFieldFilterSpec['filters'] ?? null)
|
|
? $customFieldFilterSpec['filters']
|
|
: [];
|
|
|
|
$where = [];
|
|
$params = [];
|
|
|
|
RepoQuery::addLikeFilter(
|
|
$where,
|
|
$params,
|
|
['users.first_name', 'users.last_name', 'users.email'],
|
|
$search
|
|
);
|
|
RepoQuery::addEnumFilter($where, $params, $active, [
|
|
['aliases' => ['1', 'true', 'active'], 'sql' => 'users.active = ?', 'params' => ['1']],
|
|
['aliases' => ['0', 'false', 'inactive'], 'sql' => 'users.active = ?', 'params' => ['0']],
|
|
]);
|
|
|
|
if ($createdFrom !== '' && preg_match('/^\d{4}-\d{2}-\d{2}$/', $createdFrom)) {
|
|
$where[] = 'users.created >= ?';
|
|
$params[] = $createdFrom . ' 00:00:00';
|
|
}
|
|
if ($createdTo !== '' && preg_match('/^\d{4}-\d{2}-\d{2}$/', $createdTo)) {
|
|
$where[] = 'users.created <= ?';
|
|
$params[] = $createdTo . ' 23:59:59';
|
|
}
|
|
if ($tenantUuids) {
|
|
$where[] = 'exists (select 1 from user_tenants ut2 join tenants t2 on t2.id = ut2.tenant_id where ut2.user_id = users.id and t2.uuid in (???))';
|
|
$params[] = array_values($tenantUuids);
|
|
} else {
|
|
RepoQuery::addEqualsFilter(
|
|
$where,
|
|
$params,
|
|
$tenant,
|
|
'exists (select 1 from user_tenants ut2 join tenants t2 on t2.id = ut2.tenant_id where ut2.user_id = users.id and t2.uuid = ?)'
|
|
);
|
|
}
|
|
if ($roleIds) {
|
|
$where[] = 'exists (select 1 from user_roles ur2 where ur2.user_id = users.id and ur2.role_id in (???))';
|
|
$params[] = array_map('strval', $roleIds);
|
|
}
|
|
if ($departmentIds) {
|
|
$where[] = 'exists (select 1 from user_departments ud2 where ud2.user_id = users.id and ud2.department_id in (???))';
|
|
$params[] = array_map('strval', $departmentIds);
|
|
}
|
|
RepoQuery::addEnumFilter($where, $params, $emailVerified, [
|
|
['aliases' => ['1', 'true', 'verified', 'yes'], 'sql' => 'users.email_verified_at is not null'],
|
|
['aliases' => ['0', 'false', 'unverified', 'no'], 'sql' => 'users.email_verified_at is null'],
|
|
]);
|
|
RepoQuery::addEnumFilter($where, $params, $loginStatus, [
|
|
['aliases' => ['never', 'none', 'no'], 'sql' => 'users.last_login_at is null'],
|
|
['aliases' => ['ever', 'logged', 'yes'], 'sql' => 'users.last_login_at is not null'],
|
|
]);
|
|
if (!empty($customFieldFilters['select']) && is_array($customFieldFilters['select'])) {
|
|
foreach ($customFieldFilters['select'] as $definitionId => $optionId) {
|
|
$definitionId = (int) $definitionId;
|
|
$optionId = (int) $optionId;
|
|
if ($definitionId <= 0 || $optionId <= 0) {
|
|
continue;
|
|
}
|
|
$where[] = 'exists (select 1 from user_custom_field_values ucfv ' .
|
|
'where ucfv.user_id = users.id and ucfv.definition_id = ? and ucfv.option_id = ?)';
|
|
$params[] = (string) $definitionId;
|
|
$params[] = (string) $optionId;
|
|
}
|
|
}
|
|
if (!empty($customFieldFilters['boolean']) && is_array($customFieldFilters['boolean'])) {
|
|
foreach ($customFieldFilters['boolean'] as $definitionId => $boolValue) {
|
|
$definitionId = (int) $definitionId;
|
|
$boolValue = (int) $boolValue;
|
|
if ($definitionId <= 0 || ($boolValue !== 0 && $boolValue !== 1)) {
|
|
continue;
|
|
}
|
|
$where[] = 'exists (select 1 from user_custom_field_values ucfv ' .
|
|
'where ucfv.user_id = users.id and ucfv.definition_id = ? and ucfv.value_bool = ?)';
|
|
$params[] = (string) $definitionId;
|
|
$params[] = (string) $boolValue;
|
|
}
|
|
}
|
|
if (!empty($customFieldFilters['multiselect']) && is_array($customFieldFilters['multiselect'])) {
|
|
foreach ($customFieldFilters['multiselect'] as $definitionId => $optionIds) {
|
|
$definitionId = (int) $definitionId;
|
|
$optionIds = RepoQuery::normalizeIdList($optionIds);
|
|
if ($definitionId <= 0 || !$optionIds) {
|
|
continue;
|
|
}
|
|
$where[] = 'exists (select 1 from user_custom_field_values ucfv ' .
|
|
'join user_custom_field_value_options ucfvo on ucfvo.value_id = ucfv.id ' .
|
|
'where ucfv.user_id = users.id and ucfv.definition_id = ? and ucfvo.option_id in (???))';
|
|
$params[] = (string) $definitionId;
|
|
$params[] = array_map('strval', $optionIds);
|
|
}
|
|
}
|
|
if (!empty($customFieldFilters['date']) && is_array($customFieldFilters['date'])) {
|
|
foreach ($customFieldFilters['date'] as $definitionId => $bounds) {
|
|
$definitionId = (int) $definitionId;
|
|
$from = is_array($bounds) ? trim((string) ($bounds['from'] ?? '')) : '';
|
|
$to = is_array($bounds) ? trim((string) ($bounds['to'] ?? '')) : '';
|
|
if ($definitionId <= 0 || ($from === '' && $to === '')) {
|
|
continue;
|
|
}
|
|
if ($from !== '') {
|
|
$where[] = 'exists (select 1 from user_custom_field_values ucfv ' .
|
|
'where ucfv.user_id = users.id and ucfv.definition_id = ? and ucfv.value_date >= ?)';
|
|
$params[] = (string) $definitionId;
|
|
$params[] = $from;
|
|
}
|
|
if ($to !== '') {
|
|
$where[] = 'exists (select 1 from user_custom_field_values ucfv ' .
|
|
'where ucfv.user_id = users.id and ucfv.definition_id = ? and ucfv.value_date <= ?)';
|
|
$params[] = (string) $definitionId;
|
|
$params[] = $to;
|
|
}
|
|
}
|
|
}
|
|
if (!empty($options['tenantUserId'])) {
|
|
$tenantUserId = (int) $options['tenantUserId'];
|
|
if ($tenantUserId > 0) {
|
|
if (defined('TENANT_SCOPE_STRICT') && TENANT_SCOPE_STRICT) {
|
|
$where[] = 'exists (select 1 from user_tenants ut join user_tenants ut2 on ut2.tenant_id = ut.tenant_id ' .
|
|
"join tenants t on t.id = ut.tenant_id and t.status = 'active' " .
|
|
'where ut2.user_id = ? and ut.user_id = users.id)';
|
|
$params[] = (string) $tenantUserId;
|
|
} else {
|
|
$where[] = '(not exists (select 1 from user_tenants ut where ut.user_id = users.id) ' .
|
|
'or exists (select 1 from user_tenants ut join user_tenants ut2 on ut2.tenant_id = ut.tenant_id ' .
|
|
"join tenants t on t.id = ut.tenant_id and t.status = 'active' " .
|
|
'where ut2.user_id = ? and ut.user_id = users.id))';
|
|
$params[] = (string) $tenantUserId;
|
|
}
|
|
}
|
|
}
|
|
|
|
$whereSql = $where ? (' where ' . implode(' and ', $where)) : '';
|
|
return [$whereSql, $params];
|
|
}
|
|
|
|
private function buildListQuery(string $whereSql, string $order, string $dir): string
|
|
{
|
|
return 'select users.id, users.uuid, users.first_name, users.last_name, users.display_name, users.email, users.profile_description, users.job_title, users.phone, users.mobile, users.short_dial, users.address, users.postal_code, users.city, users.country, users.region, users.hire_date, users.theme, users.primary_tenant_id, users.created_by, users.modified_by, users.created, users.modified, users.last_login_at, users.last_login_provider, users.active, ' .
|
|
'pt.description as primary_tenant_label ' .
|
|
"from users left join tenants pt on pt.id = users.primary_tenant_id and pt.status = 'active'" .
|
|
$whereSql .
|
|
sprintf(' order by `users`.`%s` %s limit ? offset ?', $order, $dir);
|
|
}
|
|
|
|
private function extractIds(array $list): array
|
|
{
|
|
$ids = [];
|
|
foreach ($list as $user) {
|
|
if (isset($user['id'])) {
|
|
$ids[] = (int) $user['id'];
|
|
}
|
|
}
|
|
return $ids;
|
|
}
|
|
|
|
private function collectLabels(array $rows, string $userKey, string $labelKey): array
|
|
{
|
|
$labelsByUser = [];
|
|
foreach ($rows as $row) {
|
|
$userId = 0;
|
|
$label = '';
|
|
if (isset($row[$userKey]) && is_array($row[$userKey])) {
|
|
$userId = (int) ($row[$userKey]['user_id'] ?? 0);
|
|
}
|
|
if (isset($row[$labelKey]) && is_array($row[$labelKey])) {
|
|
$label = (string) ($row[$labelKey]['description'] ?? '');
|
|
}
|
|
if ($userId === 0 || $label === '') {
|
|
foreach ($row as $value) {
|
|
if (!is_array($value)) {
|
|
continue;
|
|
}
|
|
if ($userId === 0 && isset($value['user_id'])) {
|
|
$userId = (int) $value['user_id'];
|
|
}
|
|
if ($label === '' && isset($value['description'])) {
|
|
$label = (string) $value['description'];
|
|
}
|
|
}
|
|
}
|
|
if ($userId === 0 && isset($row['user_id'])) {
|
|
$userId = (int) $row['user_id'];
|
|
}
|
|
if ($label === '' && isset($row['description'])) {
|
|
$label = (string) $row['description'];
|
|
}
|
|
if ($userId > 0 && $label !== '') {
|
|
$labelsByUser[$userId] ??= [];
|
|
$labelsByUser[$userId][] = $label;
|
|
}
|
|
}
|
|
return $labelsByUser;
|
|
}
|
|
|
|
private function hydrateUserLabels(array $list, array $options): array
|
|
{
|
|
$ids = $this->extractIds($list);
|
|
if (!$ids) {
|
|
return $list;
|
|
}
|
|
|
|
$scopeUserId = (int) ($options['tenantUserId'] ?? 0);
|
|
$scopeToActiveTenants = $scopeUserId > 0;
|
|
$tenantLabelJoin = $scopeToActiveTenants
|
|
? "join tenants t on t.id = ut.tenant_id and t.status = 'active' "
|
|
: 'join tenants t on t.id = ut.tenant_id ';
|
|
$placeholders = implode(',', array_fill(0, count($ids), '?'));
|
|
$tenantScopeSql = '';
|
|
$tenantScopeParams = [];
|
|
if ($scopeToActiveTenants) {
|
|
$tenantScopeSql = ' and exists (select 1 from user_tenants uts ' .
|
|
"join tenants ts on ts.id = uts.tenant_id and ts.status = 'active' " .
|
|
'where uts.user_id = ? and uts.tenant_id = ut.tenant_id)';
|
|
$tenantScopeParams[] = (string) $scopeUserId;
|
|
}
|
|
|
|
$labelSql = 'select ut.user_id as user_id, t.id as tenant_id, t.description as description from user_tenants ut ' . $tenantLabelJoin .
|
|
'where ut.user_id in (' . $placeholders . ')' . $tenantScopeSql . ' order by t.description asc';
|
|
$labelRows = call_user_func_array(['MintyPHP\\DB', 'select'], array_merge(
|
|
[$labelSql],
|
|
array_merge(array_map('strval', $ids), $tenantScopeParams)
|
|
));
|
|
$roleRows = DB::select(
|
|
'select ur.user_id as user_id, r.description as description from user_roles ur join roles r on r.id = ur.role_id and r.active = 1 ' .
|
|
'where ur.user_id in (' . $placeholders . ') order by r.description asc',
|
|
...array_map('strval', $ids)
|
|
);
|
|
|
|
$departmentScopeSql = '';
|
|
$departmentScopeParams = [];
|
|
if ($scopeToActiveTenants) {
|
|
$departmentScopeSql = ' and exists (select 1 from user_tenants uts ' .
|
|
"join tenants ts on ts.id = uts.tenant_id and ts.status = 'active' " .
|
|
'where uts.user_id = ? and uts.tenant_id = d.tenant_id)';
|
|
$departmentScopeParams[] = (string) $scopeUserId;
|
|
}
|
|
$departmentLabelSql = 'select ud.user_id as user_id, d.description as description from user_departments ud ' .
|
|
'join departments d on d.id = ud.department_id and d.active = 1 ' .
|
|
'where ud.user_id in (' . $placeholders . ')' . $departmentScopeSql . ' order by d.description asc';
|
|
$departmentRows = call_user_func_array(['MintyPHP\\DB', 'select'], array_merge(
|
|
[$departmentLabelSql],
|
|
array_merge(array_map('strval', $ids), $departmentScopeParams)
|
|
));
|
|
|
|
$tenantMapByUser = [];
|
|
foreach ($labelRows as $row) {
|
|
$userId = 0;
|
|
$tenantId = 0;
|
|
$label = '';
|
|
if (isset($row['ut']) && is_array($row['ut'])) {
|
|
$userId = (int) ($row['ut']['user_id'] ?? 0);
|
|
}
|
|
if (isset($row['t']) && is_array($row['t'])) {
|
|
$tenantId = (int) ($row['t']['tenant_id'] ?? 0);
|
|
$label = (string) ($row['t']['description'] ?? '');
|
|
}
|
|
if ($userId === 0 || $tenantId === 0 || $label === '') {
|
|
foreach ($row as $value) {
|
|
if (!is_array($value)) {
|
|
continue;
|
|
}
|
|
if ($userId === 0 && isset($value['user_id'])) {
|
|
$userId = (int) $value['user_id'];
|
|
}
|
|
if ($tenantId === 0 && isset($value['tenant_id'])) {
|
|
$tenantId = (int) $value['tenant_id'];
|
|
}
|
|
if ($label === '' && isset($value['description'])) {
|
|
$label = (string) $value['description'];
|
|
}
|
|
}
|
|
}
|
|
if ($userId === 0 && isset($row['user_id'])) {
|
|
$userId = (int) $row['user_id'];
|
|
}
|
|
if ($tenantId === 0 && isset($row['tenant_id'])) {
|
|
$tenantId = (int) $row['tenant_id'];
|
|
}
|
|
if ($label === '' && isset($row['description'])) {
|
|
$label = (string) $row['description'];
|
|
}
|
|
if ($userId > 0 && $tenantId > 0 && $label !== '') {
|
|
$tenantMapByUser[$userId] ??= [];
|
|
$tenantMapByUser[$userId][$tenantId] = $label;
|
|
}
|
|
}
|
|
$tenantLabelsByUser = [];
|
|
foreach ($tenantMapByUser as $userId => $map) {
|
|
$tenantLabelsByUser[$userId] = array_values($map);
|
|
}
|
|
$roleLabelsByUser = $this->collectLabels($roleRows, 'ur', 'r');
|
|
$departmentLabelsByUser = $this->collectLabels($departmentRows, 'ud', 'd');
|
|
|
|
foreach ($list as &$user) {
|
|
$userId = (int) ($user['id'] ?? 0);
|
|
$primaryId = (int) ($user['primary_tenant_id'] ?? 0);
|
|
$user['tenant_labels'] = $tenantLabelsByUser[$userId] ?? [];
|
|
if ($primaryId > 0 && isset($tenantMapByUser[$userId][$primaryId])) {
|
|
$user['primary_tenant_label'] = $tenantMapByUser[$userId][$primaryId];
|
|
}
|
|
$user['role_labels'] = $roleLabelsByUser[$userId] ?? [];
|
|
$user['department_labels'] = $departmentLabelsByUser[$userId] ?? [];
|
|
}
|
|
unset($user);
|
|
|
|
return $list;
|
|
}
|
|
|
|
private function unwrapList($rows): array
|
|
{
|
|
if (!is_array($rows)) {
|
|
return [];
|
|
}
|
|
$list = [];
|
|
foreach ($rows as $row) {
|
|
$user = $row['users'] ?? null;
|
|
if (is_array($user)) {
|
|
foreach ($row as $key => $value) {
|
|
if ($key === 'users' || is_array($value)) {
|
|
continue;
|
|
}
|
|
$user[$key] = $value;
|
|
}
|
|
if (isset($row['pt']) && is_array($row['pt'])) {
|
|
$label = (string) ($row['pt']['description'] ?? '');
|
|
if ($label !== '') {
|
|
$user['primary_tenant_label'] = $label;
|
|
}
|
|
}
|
|
$list[] = $user;
|
|
}
|
|
}
|
|
return $list;
|
|
}
|
|
|
|
public function listPaged(array $options): array
|
|
{
|
|
$allowedOrder = ['id', 'uuid', 'first_name', 'last_name', 'display_name', 'email', 'created', 'modified', 'active', 'last_login_at'];
|
|
[$limit, $offset] = RepoQuery::sanitizeLimitOffset($options);
|
|
[$order, $dir] = RepoQuery::sanitizeOrder($options, $allowedOrder);
|
|
[$whereSql, $params] = $this->buildUserFilters($options);
|
|
|
|
$count = DB::selectValue('select count(*) from users' . $whereSql, ...$params);
|
|
$total = $count ? (int) $count : 0;
|
|
|
|
$query = $this->buildListQuery($whereSql, $order, $dir);
|
|
$queryParams = array_merge($params, [(string) $limit, (string) $offset]);
|
|
$rows = call_user_func_array(['MintyPHP\\DB', 'select'], array_merge([$query], $queryParams));
|
|
|
|
$list = $this->unwrapList($rows);
|
|
$list = $this->hydrateUserLabels($list, $options);
|
|
|
|
return [
|
|
'total' => $total,
|
|
'rows' => $list,
|
|
];
|
|
}
|
|
}
|