Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Core\Engine\Domain\Repository;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Core\Engine\Domain\Model\PrefixMetadata;
12use DateTimeImmutable;
13
14/**
15 * Prefix Repository Interface.
16 *
17 * Contract for persisting, querying, and atomically incrementing record prefix sequence rules.
18 *
19 * @package App\Core\Engine\Domain\Repository
20 */
21interface PrefixRepositoryInterface
22{
23    /**
24     * Finds all active prefix configurations for a given module.
25     *
26     * @param int $moduleId Module primary key.
27     * @return list<PrefixMetadata> List of active prefix definitions.
28     */
29    public function findActiveByModule(int $moduleId): array;
30
31    /**
32     * Finds a specific prefix rule for a module and field.
33     *
34     * @param int $moduleId Module primary key.
35     * @param int $fieldId  Field primary key.
36     * @return PrefixMetadata|null Found metadata or null.
37     */
38    public function findByModuleAndField(int $moduleId, int $fieldId): ?PrefixMetadata;
39
40    /**
41     * Atomically acquires and increments the next sequence number for a prefix rule.
42     *
43     * Ensures race-condition safety by locking the row (FOR UPDATE) within a transaction.
44     * Evaluates sequence reset rules (yearly, monthly, daily) before incrementing.
45     *
46     * @param int               $prefixId Prefix primary key.
47     * @param DateTimeImmutable $now      Current timestamp for reset evaluation.
48     * @return int The allocated sequence number to use for the new record.
49     */
50    public function acquireNextNumber(int $prefixId, DateTimeImmutable $now): int;
51
52    /**
53     * Finds a picklist value short code by picklist value ID or string value.
54     *
55     * @param int|string $valueOrId Picklist value ID or code value.
56     * @param int        $picklistId Picklist parent ID.
57     * @return string|null The short code (or value) if found.
58     */
59    public function findPicklistShortCode(int|string $valueOrId, int $picklistId): ?string;
60}