tbh/breadcrumb-the-shire
1
0
Fork 0
forked from fa/breadcrumb-the-shire
Code Pull Requests Activity

docs: add class docblocks, business-rule comments, and transaction wrapper

Browse Source 
- 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>
This commit is contained in:
Felix Schneider
2026-03-13 21:58:51 +01:00
parent aaea038619
commit f4ce9f3378
71 changed files with 181 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
lib/Repository/Access/PermissionRepository.php
View File

@@ -6,6 +6,7 @@ use MintyPHP\DB;
use MintyPHP\Repository\Support\RepoQuery;
use MintyPHP\Repository\Support\RepositoryArrayHelper;
/** Reads and writes permission records; supports active/system flag filtering. */
class PermissionRepository implements PermissionRepositoryInterface
{
public function list(): array

1
lib/Repository/Access/PermissionRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Access;
/** Contract for permission CRUD and lookup by key or ID. */
interface PermissionRepositoryInterface
{
public function list(): array;

1
lib/Repository/Access/RoleAssignableRoleRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Access;
use MintyPHP\DB;
/** Manages which roles a given role is allowed to assign (role hierarchy). */
class RoleAssignableRoleRepository implements RoleAssignableRoleRepositoryInterface
{
public function listAssignableRoleIdsByRoleId(int $roleId): array

1
lib/Repository/Access/RolePermissionRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Access;
use MintyPHP\DB;
/** Manages the many-to-many link between roles and permissions. */
class RolePermissionRepository implements RolePermissionRepositoryInterface
{
public function listPermissionIdsByRoleId(int $roleId): array

1
lib/Repository/Access/RolePermissionRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Access;
/** Contract for managing permission assignments on roles. */
interface RolePermissionRepositoryInterface
{
public function listPermissionIdsByRoleId(int $roleId): array;

1
lib/Repository/Access/RoleRepository.php
View File

@@ -6,6 +6,7 @@ use MintyPHP\DB;
use MintyPHP\Repository\Support\RepoQuery;
use MintyPHP\Repository\Support\RepositoryArrayHelper;
/** Reads and writes role records with pagination, search, and code uniqueness checks. */
class RoleRepository implements RoleRepositoryInterface
{
public function list(): array

1
lib/Repository/Access/RoleRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Access;
/** Contract for role CRUD, existence checks, and filtered listing. */
interface RoleRepositoryInterface
{
public function list(): array;

1
lib/Repository/Access/UserRoleRepository.php
View File

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\Access;
use MintyPHP\DB;
use MintyPHP\Repository\Support\RepositoryArrayHelper;
/** Queries user-role assignments and counts active/inactive users per role. */
class UserRoleRepository implements UserRoleRepositoryInterface
{
public function listRoleIdsByUserId(int $userId): array

1
lib/Repository/Access/UserRoleRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Access;
/** Contract for querying user-role relationships and role usage counts. */
interface UserRoleRepositoryInterface
{
public function listRoleIdsByUserId(int $userId): array;

1
lib/Repository/Audit/ApiAuditLogRepository.php
View File

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\Audit;
use MintyPHP\DB;
use MintyPHP\Repository\Support\RepoQuery;
/** Records API request/response audit entries with status codes, timing, and error details. */
class ApiAuditLogRepository implements ApiAuditLogRepositoryInterface
{
private const FILTER_OPTIONS_LIMIT_MAX = 200;

1
lib/Repository/Audit/ApiAuditLogRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Audit;
/** Contract for API request audit log creation, pagination, and retention purge. */
interface ApiAuditLogRepositoryInterface
{
public function create(array $data): int|false;

1
lib/Repository/Audit/ImportAuditRunRepository.php
View File

@@ -6,6 +6,7 @@ use MintyPHP\DB;
use MintyPHP\Domain\Taxonomy\ImportAuditStatus;
use MintyPHP\Repository\Support\RepoQuery;
/** Tracks CSV import runs including source file, row counts, status, and completion metadata. */
class ImportAuditRunRepository implements ImportAuditRunRepositoryInterface
{
private const FILTER_OPTIONS_LIMIT_MAX = 200;

1
lib/Repository/Audit/ImportAuditRunRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Audit;
/** Contract for CSV import run audit trail creation, completion, and purge. */
interface ImportAuditRunRepositoryInterface
{
public function createRunning(array $data): int|false;

1
lib/Repository/Audit/SystemAuditLogRepository.php
View File

@@ -7,6 +7,7 @@ use MintyPHP\Domain\Taxonomy\SystemAuditChannel;
use MintyPHP\Domain\Taxonomy\SystemAuditOutcome;
use MintyPHP\Repository\Support\RepoQuery;
/** Persists system audit events with actor, target, outcome, channel, and hashed request metadata. */
class SystemAuditLogRepository implements SystemAuditLogRepositoryInterface
{
private const FILTER_OPTIONS_LIMIT_MAX = 200;

1
lib/Repository/Audit/SystemAuditLogRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Audit;
/** Contract for system-wide security event logging with channel and outcome filtering. */
interface SystemAuditLogRepositoryInterface
{
public function create(array $data): int|false;

1
lib/Repository/Audit/UserLifecycleAuditRepository.php
View File

@@ -8,6 +8,7 @@ use MintyPHP\Domain\Taxonomy\UserLifecycleStatus;
use MintyPHP\Domain\Taxonomy\UserLifecycleTriggerType;
use MintyPHP\Repository\Support\RepoQuery;
/** Records user lifecycle transitions (deactivation, deletion, restore) with reason codes and snapshots. */
class UserLifecycleAuditRepository implements UserLifecycleAuditRepositoryInterface
{
private const FILTER_OPTIONS_LIMIT_MAX = 200;

1
lib/Repository/Audit/UserLifecycleAuditRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Audit;
/** Contract for tracking user deactivation/deletion lifecycle events and restore eligibility. */
interface UserLifecycleAuditRepositoryInterface
{
public function create(array $row): int|false;

1
lib/Repository/Auth/ApiTokenRepository.php
View File

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\Auth;
use MintyPHP\DB;
use MintyPHP\Repository\Support\RepoQuery;
/** Persists API tokens with selector/hash pairs, expiry tracking, and usage timestamps. */
class ApiTokenRepository implements ApiTokenRepositoryInterface
{
private const UUID_REGEX = '/^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i';

1
lib/Repository/Auth/ApiTokenRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Auth;
/** Contract for API bearer token creation, lookup by selector or UUID, and revocation. */
interface ApiTokenRepositoryInterface
{
public function isUuid(string $value): bool;

1
lib/Repository/Auth/EmailVerificationRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Auth;
use MintyPHP\DB;
/** Stores email verification codes with attempt counters, expiry, and completion status. */
class EmailVerificationRepository implements EmailVerificationRepositoryInterface
{
public function create(int $userId, string $codeHash, string $expiresAt): ?int

1
lib/Repository/Auth/EmailVerificationRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Auth;
/** Contract for email verification code lifecycle: creation, lookup, attempt tracking, and completion. */
interface EmailVerificationRepositoryInterface
{
public function create(int $userId, string $codeHash, string $expiresAt): ?int;

1
lib/Repository/Auth/PasswordResetRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Auth;
use MintyPHP\DB;
/** Stores password reset codes with attempt counters, expiry, and completion history. */
class PasswordResetRepository implements PasswordResetRepositoryInterface
{
private function unwrapList($rows): array

1
lib/Repository/Auth/PasswordResetRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Auth;
/** Contract for password reset code lifecycle: creation, lookup, attempt tracking, and completion. */
interface PasswordResetRepositoryInterface
{
public function create(int $userId, string $codeHash, string $expiresAt): ?int;

1
lib/Repository/Auth/RememberTokenRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Auth;
use MintyPHP\DB;
/** Manages persistent login tokens with rotation, family tracking, and admin-initiated expiry. */
class RememberTokenRepository implements RememberTokenRepositoryInterface
{
private function unwrapList($rows): array

1
lib/Repository/Auth/RememberTokenRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Auth;
/** Contract for remember-me token creation, rotation, expiry, and active session counting. */
interface RememberTokenRepositoryInterface
{
public function create(int $userId, string $selector, string $tokenHash, string $expiresAt): ?int;

1
lib/Repository/Content/PageContentRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Content;
use MintyPHP\DB;
/** Reads and writes locale-specific content blocks for CMS pages. */
class PageContentRepository
{
private static function unwrap(?array $row): ?array

1
lib/Repository/Content/PageRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Content;
use MintyPHP\DB;
/** Looks up CMS page metadata by slug. */
class PageRepository
{
private static function unwrap(?array $row): ?array

1
lib/Repository/CustomField/TenantCustomFieldDefinitionRepository.php
View File

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\CustomField;
use MintyPHP\DB;
use MintyPHP\Repository\Support\RepoQuery;
/** Reads and writes tenant-scoped custom field definitions with type and pagination filtering. */
class TenantCustomFieldDefinitionRepository
{
private static function unwrap(?array $row): ?array

1
lib/Repository/CustomField/TenantCustomFieldOptionRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\CustomField;
use MintyPHP\DB;
/** Retrieves selectable options for tenant-scoped custom field definitions. */
class TenantCustomFieldOptionRepository
{
private static function unwrapList($rows): array

1
lib/Repository/CustomField/UserCustomFieldValueOptionRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\CustomField;
use MintyPHP\DB;
/** Manages selected option links for user custom field values (atomic replace). */
class UserCustomFieldValueOptionRepository
{
public static function replaceForValueId(int $valueId, array $optionIds): bool

1
lib/Repository/CustomField/UserCustomFieldValueRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\CustomField;
use MintyPHP\DB;
/** Reads and writes custom field values attached to individual users. */
class UserCustomFieldValueRepository
{
private static function unwrapList($rows): array

1
lib/Repository/Mail/MailLogRepository.php
View File

@@ -6,6 +6,7 @@ use MintyPHP\DB;
use MintyPHP\Domain\Taxonomy\MailLogStatus;
use MintyPHP\Repository\Support\RepoQuery;
/** Logs outgoing emails with queued/sent/failed status transitions and provider message IDs. */
class MailLogRepository implements MailLogRepositoryInterface
{
public function create(array $data): ?int

1
lib/Repository/Mail/MailLogRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Mail;
/** Contract for outgoing email log creation, status updates, and paginated listing. */
interface MailLogRepositoryInterface
{
public function create(array $data): ?int;

1
lib/Repository/Org/DepartmentRepository.php
View File

@@ -6,6 +6,7 @@ use MintyPHP\DB;
use MintyPHP\Repository\Support\RepoQuery;
use MintyPHP\Repository\Support\RepositoryArrayHelper;
/** Reads and writes department records with cost center, code tracking, and pagination. */
class DepartmentRepository implements DepartmentRepositoryInterface
{
public function list(): array

1
lib/Repository/Org/DepartmentRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Org;
/** Contract for department CRUD, existence checks, and filtered listing. */
interface DepartmentRepositoryInterface
{
public function list(): array;

1
lib/Repository/Org/UserDepartmentRepository.php
View File

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\Org;
use MintyPHP\DB;
use MintyPHP\Repository\Support\RepositoryArrayHelper;
/** Queries user-department assignments and counts active/inactive users per department. */
class UserDepartmentRepository implements UserDepartmentRepositoryInterface
{
public function listDepartmentIdsByUserId(int $userId): array

1
lib/Repository/Org/UserDepartmentRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Org;
/** Contract for querying user-department membership and per-department user counts. */
interface UserDepartmentRepositoryInterface
{
public function listDepartmentIdsByUserId(int $userId): array;

1
lib/Repository/Scheduler/ScheduledJobRepository.php
View File

@@ -6,6 +6,7 @@ use MintyPHP\DB;
use MintyPHP\Domain\Taxonomy\ScheduledJobStatus;
use MintyPHP\Repository\Support\RepoQuery;
/** Persists scheduled jobs with cron expressions, next-run calculation, and metadata updates. */
class ScheduledJobRepository implements ScheduledJobRepositoryInterface
{
public function create(array $data): int|false

1
lib/Repository/Scheduler/ScheduledJobRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Scheduler;
/** Contract for scheduled job CRUD, due-job queries, and run status tracking. */
interface ScheduledJobRepositoryInterface
{
public function create(array $data): int|false;

1
lib/Repository/Scheduler/ScheduledJobRunRepository.php
View File

@@ -7,6 +7,7 @@ use MintyPHP\Domain\Taxonomy\ScheduledJobRunStatus;
use MintyPHP\Domain\Taxonomy\ScheduledJobTriggerType;
use MintyPHP\Repository\Support\RepoQuery;
/** Records individual job run results with duration, output, and retention-based purging. */
class ScheduledJobRunRepository implements ScheduledJobRunRepositoryInterface
{
public function create(array $data): int|false

1
lib/Repository/Scheduler/ScheduledJobRunRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Scheduler;
/** Contract for scheduled job run history: creation, pagination, and retention purge. */
interface ScheduledJobRunRepositoryInterface
{
public function create(array $data): int|false;

1
lib/Repository/Scheduler/SchedulerRuntimeRepository.php
View File

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\Scheduler;
use MintyPHP\DB;
use MintyPHP\Domain\Taxonomy\SchedulerRuntimeResult;
/** Tracks scheduler daemon heartbeat, result codes, and error state. */
class SchedulerRuntimeRepository implements SchedulerRuntimeRepositoryInterface
{
public function touchHeartbeat(string $result, ?string $errorCode = null, ?string $heartbeatAtUtc = null): bool

1
lib/Repository/Scheduler/SchedulerRuntimeRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Scheduler;
/** Contract for scheduler daemon heartbeat and runtime status. */
interface SchedulerRuntimeRepositoryInterface
{
public function touchHeartbeat(string $result, ?string $errorCode = null, ?string $heartbeatAtUtc = null): bool;

1
lib/Repository/Security/RateLimitRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Security;
use MintyPHP\DB;
/** Persists rate limit counters with hit tracking, window expiry, and block duration. */
class RateLimitRepository implements RateLimitRepositoryInterface
{
public function findByScopeAndHash(string $scope, string $subjectHash): ?array

1
lib/Repository/Security/RateLimitRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Security;
/** Contract for sliding-window rate limit storage by scope and subject hash. */
interface RateLimitRepositoryInterface
{
public function findByScopeAndHash(string $scope, string $subjectHash): ?array;

1
lib/Repository/Settings/SettingRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Settings;
use MintyPHP\DB;
/** Reads and upserts application settings as key-value pairs in the database. */
class SettingRepository implements SettingRepositoryInterface
{
public function find(string $key): ?array

1
lib/Repository/Settings/SettingRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Settings;
/** Contract for key-value application settings with optional descriptions. */
interface SettingRepositoryInterface
{
public function find(string $key): ?array;

30
lib/Repository/Support/DatabaseSessionRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Support;
use MintyPHP\DB;
/** Executes database session operations: advisory locks, transactions, and commit/rollback. */
class DatabaseSessionRepository implements DatabaseSessionRepositoryInterface
{
public function acquireAdvisoryLock(string $lockName, int $timeoutSeconds = 0): bool
@@ -47,4 +48,33 @@ class DatabaseSessionRepository implements DatabaseSessionRepositoryInterface
{
DB::handle()->rollback();
}
/**
* Run a callback inside a DB transaction. Commits on success, rolls back on exception.
*
* Eliminates the need for manual begin/commit/rollback + rollbackQuietly() boilerplate
* that is duplicated across multiple services. The callback receives no arguments;
* use closures to capture dependencies.
*
* @template T
* @param callable(): T $callback
* @return T The value returned by the callback.
* @throws \Throwable Re-throws the original exception after rollback.
*/
public function transaction(callable $callback): mixed
{
$this->beginTransaction();
try {
$result = $callback();
$this->commitTransaction();
return $result;
} catch (\Throwable $e) {
try {
$this->rollbackTransaction();
} catch (\Throwable) {
// Swallow — the original exception is more important.
}
throw $e;
}
}
}

8
lib/Repository/Support/DatabaseSessionRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Support;
/** Contract for database-level session control: advisory locks and transaction management. */
interface DatabaseSessionRepositoryInterface
{
public function acquireAdvisoryLock(string $lockName, int $timeoutSeconds = 0): bool;
@@ -13,4 +14,11 @@ interface DatabaseSessionRepositoryInterface
public function commitTransaction(): void;
public function rollbackTransaction(): void;
/**
* @template T
* @param callable(): T $callback
* @return T
*/
public function transaction(callable $callback): mixed;
}

1
lib/Repository/Support/RepoQuery.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Support;
/** Static helpers for safe SQL query building: LIKE escaping, limit/offset clamping, ID list normalization, and enum filtering. */
class RepoQuery
{
private static function normalizeLikeValue(string $value): string

1
lib/Repository/Tenant/TenantMicrosoftAuthRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Tenant;
use MintyPHP\DB;
/** Persists Microsoft Entra ID OAuth settings per tenant, including encrypted client secrets. */
class TenantMicrosoftAuthRepository implements TenantMicrosoftAuthRepositoryInterface
{
private function unwrap($row): ?array

1
lib/Repository/Tenant/TenantMicrosoftAuthRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Tenant;
/** Contract for storing and retrieving Microsoft Entra ID SSO configuration per tenant. */
interface TenantMicrosoftAuthRepositoryInterface
{
public function findByTenantId(int $tenantId): ?array;

1
lib/Repository/Tenant/TenantRepository.php
View File

@@ -7,6 +7,7 @@ use MintyPHP\Domain\Taxonomy\TenantStatus;
use MintyPHP\Repository\Support\RepoQuery;
use MintyPHP\Repository\Support\RepositoryArrayHelper;
/** Reads and writes tenant records with pagination, search, and status filtering. */
class TenantRepository implements TenantRepositoryInterface
{
public function list(): array

1
lib/Repository/Tenant/TenantRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Tenant;
/** Contract for tenant CRUD and filtered listing. */
interface TenantRepositoryInterface
{
public function list(): array;

1
lib/Repository/Tenant/UserTenantRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\Tenant;
use MintyPHP\DB;
/** Queries the many-to-many link between users and tenants. */
class UserTenantRepository implements UserTenantRepositoryInterface
{
public function listTenantIdsByUserId(int $userId): array

1
lib/Repository/Tenant/UserTenantRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\Tenant;
/** Contract for querying user-tenant membership and per-tenant user counts. */
interface UserTenantRepositoryInterface
{
public function listTenantIdsByUserId(int $userId): array;

1
lib/Repository/User/UserExternalIdentityRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\User;
use MintyPHP\DB;
/** Links and looks up external identity provider accounts (Entra ID / OIDC) for users. */
class UserExternalIdentityRepository implements UserExternalIdentityRepositoryInterface
{
private function unwrap($row): ?array

1
lib/Repository/User/UserExternalIdentityRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\User;
/** Contract for linking external identity provider accounts (OIDC) to users. */
interface UserExternalIdentityRepositoryInterface
{
public function findByProviderTidOid(string $provider, string $tid, string $oid): ?array;

1
lib/Repository/User/UserListQueryRepository.php
View File

@@ -5,6 +5,7 @@ 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

1
lib/Repository/User/UserListQueryRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\User;
/** Contract for paginated user listing with multi-criteria filtering. */
interface UserListQueryRepositoryInterface
{
public function listPaged(array $options): array;

1
lib/Repository/User/UserReadRepository.php
View File

@@ -4,6 +4,7 @@ namespace MintyPHP\Repository\User;
use MintyPHP\DB;
/** Retrieves user records and authorization snapshots; no write operations. */
class UserReadRepository implements UserReadRepositoryInterface
{
public function findAuthzSnapshot(int $userId): ?array

1
lib/Repository/User/UserReadRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\User;
/** Contract for read-only user lookups by ID, UUID, email, and authorization snapshots. */
interface UserReadRepositoryInterface
{
public function findAuthzSnapshot(int $userId): ?array;

1
lib/Repository/User/UserSavedFilterRepository.php
View File

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\User;
use MintyPHP\DB;
use MintyPHP\Repository\Support\RepoQuery;
/** Persists and retrieves user-defined search filter presets per list context. */
class UserSavedFilterRepository implements UserSavedFilterRepositoryInterface
{
private function unwrapList($rows): array

1
lib/Repository/User/UserSavedFilterRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\User;
/** Contract for per-user, per-context persistence of saved search filters. */
interface UserSavedFilterRepositoryInterface
{
public function listByUserAndContext(int $userId, string $context): array;

1
lib/Repository/User/UserWriteRepository.php
View File

@@ -5,6 +5,7 @@ namespace MintyPHP\Repository\User;
use MintyPHP\DB;
use MintyPHP\Repository\Support\RepoQuery;
/** Creates and mutates user records including activation, tenant links, and preferences. */
class UserWriteRepository implements UserWriteRepositoryInterface
{
public function updateLastLogin(int $userId, string $provider = 'local'): void

1
lib/Repository/User/UserWriteRepositoryInterface.php
View File

@@ -2,6 +2,7 @@
namespace MintyPHP\Repository\User;
/** Contract for user creation, updates, activation, tenant assignment, and preference changes. */
interface UserWriteRepositoryInterface
{
public function updateLastLogin(int $userId, string $provider = 'local'): void;

12
lib/Service/Access/PermissionService.php
View File

@@ -8,6 +8,18 @@ use MintyPHP\Repository\Access\RolePermissionRepositoryInterface;
use MintyPHP\Repository\Access\UserRoleRepositoryInterface;
use MintyPHP\Service\Audit\SystemAuditService;
/**
* Central RBAC permission service — resolves and caches permission keys for users.
*
* Permission resolution: User → Roles (via user_roles) → Permissions (via role_permissions).
* The resolved key list is cached in two tiers:
* - API requests (stateless): in-memory array, lives for one request cycle.
* - Web requests: session store, survives across page loads until refresh.
* A forced refresh can be triggered by passing $refresh = true to getUserPermissions().
*
* All permission key constants are defined here as the single source of truth,
* referenced by actions, services, policies, and templates.
*/
class PermissionService
{
private array $apiPermissionCache = [];

23
lib/Service/Auth/AuthService.php
View File

@@ -14,6 +14,21 @@ use MintyPHP\Service\User\UserTenantContextService;
use MintyPHP\Session;
use MintyPHP\Support\Flash;
/**
* Orchestrates authentication flows: login, registration, logout, and session refresh.
*
* Login is a cascading validation — each step must pass before the next is attempted:
* 1. Email verification status (unverified → redirect to verification)
* 2. Credential check via Auth::login (email + password)
* 3. Account active flag
* 4. Local password login allowed (at least one tenant permits it)
* 5. Permissions loaded + tenant context hydrated into session
* 6. At least one active tenant assigned
*
* Every outcome (success or failure at any step) is recorded as an audit event.
* On SSO-initiated login (loginUserById), steps 1-4 are skipped because the IdP
* already authenticated the user; steps 5-6 still apply.
*/
class AuthService
{
public function __construct(
@@ -293,6 +308,14 @@ class AuthService
$this->systemAuditService->record($eventType, $outcome, $context);
}
/**
* Re-validates the session against the current DB state.
*
* Uses an authz_version counter: the DB version is bumped whenever permissions or
* tenant assignments change. A mismatch with the session version triggers a full
* reload of user data, permissions, and tenant context. This is the mechanism that
* makes permission changes take effect without requiring re-login.
*/
public function refreshSessionAuthState(int $userId): array
{
if ($userId <= 0) {

17
lib/Service/Import/ImportService.php
View File

@@ -9,6 +9,23 @@ use MintyPHP\Service\Import\Profile\ImportProfileInterface;
use MintyPHP\Service\Settings\SettingsDefaultsGateway;
use MintyPHP\Service\Tenant\TenantScopeService;
/**
* Orchestrates CSV imports through a three-phase workflow:
*
* 1. analyzeUpload() — validates file, detects delimiter/headers, stores temp file,
* returns a session-scoped token for subsequent calls.
* 2. preview() — maps columns → target fields, validates each row via the
* profile's dryRunRow(), returns would-create/skip/fail counts.
* 3. commit() — identical mapping + validation, then commitRow() for real
* writes; wrapped in an audit run (start → finish).
*
* Import behavior is pluggable via ImportProfileInterface. Each profile defines
* allowed/required target fields, validation rules, and the actual create logic.
* The PROFILE_PERMISSION_MAP links profile keys to the required permission.
*
* Cross-user token reuse is prevented by verifying user_id in preview/commit.
* Assignment columns (tenant/role/department) require a separate permission check.
*/
class ImportService
{
private const MAX_ROWS = 20000;

13
lib/Service/Tenant/TenantScopeService.php
View File

@@ -7,6 +7,19 @@ use MintyPHP\Repository\Tenant\TenantRepositoryInterface;
use MintyPHP\Repository\Tenant\UserTenantRepositoryInterface;
use MintyPHP\Service\Access\PermissionService;
/**
* Enforces tenant-boundary access control across the application.
*
* Core rules:
* - Users with TENANT_SCOPE_GLOBAL permission bypass all tenant checks.
* - canAccess() resolves the resource's tenant IDs, intersects with the user's
* tenant IDs, and grants access only on overlap.
* - In strict mode (default): unscoped resources (no tenant assigned) are denied.
* - In permissive mode: unscoped resources are allowed.
* - Resources whose tenants all became inactive are always denied (not treated as unscoped).
* - mergeTenantIdsPreservingOutOfScope() ensures that a scoped admin cannot
* accidentally remove tenant assignments outside their own scope.
*/
class TenantScopeService
{
public function __construct(

14
lib/Service/User/UserAccountService.php
View File

@@ -10,6 +10,20 @@ use MintyPHP\Repository\User\UserWriteRepositoryInterface;
use MintyPHP\Service\Audit\SystemAuditService;
use MintyPHP\Service\Tenant\TenantScopeService;
/**
* User account lifecycle: creation, updates, activation, deletion, and self-service profile edits.
*
* Write operations (createFromAdmin, register) run inside a DB transaction to ensure
* atomicity of user record + tenant/role/department assignments. On any failure the
* transaction is rolled back and no partial state is left behind.
*
* Tenant-scoped operations (delete, bulk activate/deactivate) filter UUIDs through
* TenantScopeService before executing, so a scoped admin can only affect users
* within their own tenant boundary. Self-delete and self-deactivate are always blocked.
*
* Every state change is recorded via SystemAuditService with before/after snapshots
* where applicable (e.g. active flag, locale, theme, primary tenant).
*/
class UserAccountService
{
public function __construct(