When an application receives ambiguous data, forcing it into a “valid” or “invalid” answer often hides the problem instead of solving it. This can happen with forms, integrations, or results proposed by an automated system: there is not enough context to safely accept or discard the record. In such cases, human review of uncertain data in PHP should be a domain state with explicit rules, not an informal label or an improvised inbox.
The design must answer four questions: what was received, what is proposed, who should decide, and what happens next. Separating these responsibilities makes the workflow easier to operate, correct errors, and explain why data was processed in a particular way.
Classify the problem before creating states
Not all data that cannot proceed requires human review. Distinguish at least these situations:
- Invalid: it violates a verifiable rule, such as a format that cannot be interpreted. It should be rejected or sent back for correction, depending on its source and the product.
- Incomplete: a required field is missing. The appropriate action may be to request the data, retain the draft, or wait for an additional source.
- Uncertain: there are several plausible interpretations, or the evidence is insufficient for an automated decision. A person may need to evaluate it.
Review should not become the generic destination for every error. If a value violates an unequivocal constraint, sending it to a review queue only adds work. By contrast, when a decision depends on context or judgment, a reviewable state makes it possible to pause processing without prematurely declaring the data correct or incorrect.
It is also useful to distinguish this workflow from an import quarantine. Quarantine usually isolates inputs that must not be incorporated into the system, for example, because they failed technical or security checks. Review resolves a business ambiguity. The same record may pass through both mechanisms, but their objectives, permissions, and exit criteria are not interchangeable.
Define a small, explicit lifecycle
Start with the states needed to describe the process, not a list of every future possibility. A basic lifecycle might be:
pending_review: awaiting a decision.confirmed: a person confirms a usable value.rejected: the person determines that it should not be processed.reopenedor a new review entry: a previous decision is called into question again.
Define the permitted transitions. For example, a pending case can be confirmed or rejected; a resolved case can be reopened only under authorized conditions. Do not allow an arbitrary request to change the state directly to any value. A transition should specify its source state, destination state, permitted actor, and associated effects.
Store the reason for the decision and the identity of the person responsible. If data is rejected, record a useful reason, not just a boolean. If an interpretation is confirmed, retain the value that was approved and, where appropriate, the evidence supporting the decision. Specify whether a reason is required for each action, and avoid including unnecessary personal information in free-text notes.
Separate input, proposal, and confirmed value
A robust design does not overwrite received data with an automated process's interpretation or a person's correction. Keep these concepts distinct:
- Received data: the original input and its provenance, with appropriate access and retention controls.
- Proposed interpretation: a suggestion generated by rules, an integration, or an assisted system, together with the information needed to evaluate it.
- Confirmed value: the value the application uses after an authorized decision.
This separation prevents a proposal from accidentally being treated as truth and makes it possible to reconstruct how the current value was reached. There is no need to indiscriminately duplicate every field: retain the data needed for auditing and support, applying data protection and retention policies. If a proposal includes a score or automated explanation, treat it as context, not as a decision.
Record changes as events or history entries that are immutable to the ordinary application: case identifier, action, previous and new state, actor, date, and reason. The model can also maintain the current state to make it easy to query the queue. A correction is represented by a new decision or a reopening linked to the history; deleting the previous decision destroys traceability.
Implement decisions in the domain layer
In PHP, encapsulate transitions in an application service or domain entity instead of relying on every controller to apply the same rules. A schematic example:
final class ReviewDecisionService
{
public function confirm(ReviewCase $case, User $actor, string $value, string $reason): void
{
if (!$actor->canReview($case)) {
throw new DomainException('Access not permitted');
}
if (!$case->isPending()) {
throw new DomainException('The case is not pending');
}
$case->confirm($value, $actor->id(), $reason);
}
}The snippet illustrates where to place rules, not a complete implementation. Also validate the value's format and limits, check that the actor is authorized for that case, and record the decision. Do not confuse authentication—who the user is—with authorization—what they can do with that record. If roles or separation of duties apply, express those restrictions as product rules.
When updating the case and writing the history must be consistent, save them in a database transaction. If the decision triggers external effects, such as a call to another API, do not assume that the local transaction also covers that system. Use a reliable delivery mechanism, such as a transactional outbox when the architecture requires it, and design consumers to tolerate retries.
Design a queue that helps people decide
A useful queue makes it possible to prioritize and find cases without obscuring their context. Include relevant filters—status, date, type, or assignment—and show only the information needed to understand the case. If there is a proposal, make it clear that it is a proposal. Show provenance, the reason for review, and available actions, and avoid displaying controls that the user is not authorized to use.
Assignment can reduce duplicate work, but it does not replace authorization or protection against simultaneous decisions. One person may open a case while another resolves it before the first person submits a response. To prevent an old screen from overwriting a recent change, use optimistic concurrency control: compare a version or timestamp when saving and reject the stale operation so the user reloads the case.
If the process requires temporary reservations, define when they expire and what happens when they do. Do not use permanent assignment as an accidental lock. Record relevant actions so you can explain who reviewed the case and detect records that remain pending longer than is acceptable for operations.
Correct and reopen without erasing the past
A decision may be wrong or may change because new evidence has arrived. Define who can reopen it, what reason they must provide, and whether the confirmed data becomes unavailable while it is reviewed again. The answer depends on the impact of the value on downstream processes; for example, it may be necessary to stop new actions, but not to automatically remove effects that have already occurred.
Keep the previous decision in the history and create a new version or review event. If correcting the data requires recalculating dependent information, identify those effects explicitly and establish an idempotent procedure to prevent duplicates. A status correction must not pretend that an external operation has already been undone.
Test rules, permissions, and downstream effects
Tests should cover the complete workflow and its boundaries, not just verify that the form is saved. At a minimum, check that:
- A pending case accepts the expected transitions and rejects others.
- Actors without permission cannot make decisions, reopen cases, or view restricted data.
- Each decision retains the actor, reason, and previous and new values, according to the defined policy.
- Two concurrent changes cannot let a stale decision overwrite another.
- A failure to record the history does not leave the state updated without traceability.
- Retrying a downstream effect does not duplicate operations or notifications.
As a design checklist, confirm that the uncertainty has an identifiable cause; that the original data, proposal, and confirmed value are distinguished; that each transition has a permission and a reason; that the queue provides sufficient context; and that reopening preserves the history and defines the operational impact. If any of these points depends on informal conventions, a system rule is still missing.
