Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
8 / 8
100.00%
5 / 5
 CRAP
100.00%
1 / 1
InvalidArgumentException
100.00%
8 / 8
100.00%
5 / 5
 5
100.00%
1 / 1
 __construct
100.00%
1 / 1
100.00%
1 / 1
 1
 forNonPositiveWorkerCount
100.00%
1 / 1
100.00%
1 / 1
 1
 forForeignWorker
100.00%
1 / 1
100.00%
1 / 1
 1
 forForeignWorkerGroup
100.00%
1 / 1
100.00%
1 / 1
 1
 forUnsupportedWorkerImplementation
100.00%
4 / 4
100.00%
1 / 1
 1
1<?php
2
3declare(strict_types=1);
4
5/**
6 * This file is part of fast-forward/fork.
7 *
8 * This source file is subject to the license bundled
9 * with this source code in the file LICENSE.
10 *
11 * @copyright Copyright (c) 2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
12 * @license   https://opensource.org/licenses/MIT MIT License
13 *
14 * @see       https://github.com/php-fast-forward/fork
15 * @see       https://github.com/php-fast-forward
16 * @see       https://datatracker.ietf.org/doc/html/rfc2119
17 */
18
19namespace FastForward\Fork\Exception;
20
21/**
22 * Represents invalid argument failures raised by the fork library.
23 *
24 * This exception class centralizes all argument validation errors related to
25 * worker management and orchestration.
26 *
27 * Implementations throwing this exception MUST ensure that the provided input
28 * violates the expected contract. Consumers of this exception SHOULD treat it
29 * as a programming error and MUST NOT rely on it for normal control flow.
30 */
31 class InvalidArgumentException extends \InvalidArgumentException implements ForkExceptionInterface
32{
33    /**
34     * Initializes the exception with a descriptive message.
35     *
36     * This constructor is private to enforce the use of named constructors for specific
37     * logic violation scenarios, ensuring that each exception instance is created with
38     * a clear and relevant message.
39     *
40     * @param string $message
41     */
42    private function __construct(string $message)
43    {
44        parent::__construct($message);
45    }
46
47    /**
48     * Creates an exception for a non-positive worker count.
49     *
50     * The worker count MUST be greater than zero. Any value less than or equal to
51     * zero SHALL be considered invalid and MUST trigger this exception.
52     *
53     * @param int $workerCount the invalid worker count provided by the caller
54     *
55     * @return self a new instance describing the invalid worker count
56     */
57    public static function forNonPositiveWorkerCount(int $workerCount): self
58    {
59        return new self(\sprintf('The worker count must be greater than zero, %d given.', $workerCount));
60    }
61
62    /**
63     * Creates an exception for a worker that is not owned by the manager.
64     *
65     * A worker MUST belong to the manager instance that operates on it. If a
66     * foreign worker is detected, this exception SHALL be thrown.
67     *
68     * @param int $workerPid the process identifier of the foreign worker
69     *
70     * @return self a new instance describing the ownership violation
71     */
72    public static function forForeignWorker(int $workerPid): self
73    {
74        return new self(\sprintf('Worker %d is not managed by this fork manager.', $workerPid));
75    }
76
77    /**
78     * Creates an exception for a worker group that belongs to another manager.
79     *
80     * Worker groups MUST be associated with the same manager instance. Passing a
81     * group from a different manager SHALL result in this exception.
82     *
83     * @return self a new instance describing the invalid worker group ownership
84     */
85    public static function forForeignWorkerGroup(): self
86    {
87        return new self('The provided worker group is not managed by this fork manager.');
88    }
89
90    /**
91     * Creates an exception for a worker implementation unsupported by the manager.
92     *
93     * The manager MAY restrict supported worker implementations. If an unsupported
94     * implementation is provided, this exception MUST be thrown.
95     *
96     * @param string $className the fully-qualified class name of the unsupported worker
97     *
98     * @return self a new instance describing the unsupported implementation
99     */
100    public static function forUnsupportedWorkerImplementation(string $className): self
101    {
102        return new self(\sprintf(
103            'The worker implementation %s is not supported by this fork manager.',
104            $className,
105        ));
106    }
107}