A change is not done because it works in a demonstration, because a manual test produced the expected result, or because the code has reached the main branch. These signals may confirm part of the implementation, but they do not prove that the change is safe, understandable, and operable in production.
The definition of done in PHP projects must establish which evidence makes a specific change acceptable. It must cover business behavior, but also existing data, asynchronous tasks, integrations, permissions, observability, and rollback. This prevents product from accepting something that operations cannot sustain or technology from deploying a modification whose effects are difficult to repair.
Do not confuse acceptance, implementation, and operation
It is useful to separate three states that are often condensed into a single “done”:
- Accepted scope: it has been verified that the agreed business rule behaves as expected in the relevant scenarios.
- Completed implementation: the necessary code, tests, configuration, and schema changes are ready and reviewed.
- Operable change: it can be deployed, monitored, supported, and, if necessary, limited or rolled back without leaving the system in an unknown state.
In an existing PHP application, the distance between these states can be considerable. A new validation in a controller may pass a demonstration but block automation that uses the same API. A migration may run without errors and still transform values that an import process continues to interpret using the previous semantics. A permission added in the interface may not apply to an internal route or a console command.
The definition must not become a uniform ritual. It must be proportional to risk: an isolated visual adjustment requires less evidence than a change involving billing, permissions, personal data, or flows with external effects.
Build a criteria matrix based on impact
Before development, classify the change by its impact surfaces. There is no need to assign a complex score: it is enough to identify which dimensions change and which failure would be unacceptable. Each dimension activates additional criteria and evidence.
Business and behavior
Define rules, exceptions, and boundary states with verifiable examples. Include what must happen with incomplete data, repeated requests, concurrency, and foreseeable errors. If one rule replaces another, specify from when it applies and what happens to records created under the previous rule.
Data and schema
If there are migrations, new fields, information recalculation, or imports, determine the affected volume, temporary compatibility between application and schema versions, and post-change validation. A completed migration does not mean the data is correct: counts, invalid values, duplicates, unexpected nulls, and the preservation of relevant relationships must be checked.
Integrations and asynchronous processes
Queues, cron jobs, webhooks, emails, file storage, and external APIs require their own criteria. Document input and output contracts, retries, idempotency, timeouts, handling of partial responses, and the destination of errors. In PHP, a console command or worker may use different services and credentials from those of a web request; testing must cover that realistic execution.
Permissions, security, and privacy
Specify who can view, create, approve, modify, or export each resource. Authorization must be verified on the server, not only through the visibility of a button. If personal data or operational secrets are involved, include log minimization, access restrictions, and a review of what information appears in errors, traces, and notifications.
Operations and deployment
Determine how a failure will be detected after deployment: contextual logs, existing metrics, applicable alerts, or specific manual checks. Distinguish deployment from release: the former installs artifacts and configuration; the latter exposes behavior to users or processes. When possible, a configuration setting, gradual rollout, or business condition can limit exposure without confusing it with a complete rollback.
What evidence should accompany the change
A definition-of-done list is useful if it requests observable proof, not vague formulas such as “validated” or “documented.” The evidence must be reviewable by the person accepting the change and useful during an incident.
- Automated tests: unit cases for isolated rules, integration tests for persistence, authorization, and services, and end-to-end tests only where they provide actual coverage of the flow.
- Acceptance verification: business scenarios run with identified inputs, results, and roles, including rejection cases.
- Migration result: execution plan, pre- and post-validation, expected counts, and explicit handling of anomalies.
- Integration contract: changes to fields, error codes, authentication, limits, retries, and compatibility with existing consumers.
- Operational verification: which log, metric, or query confirms that the flow works after deployment and who must review it.
- Support guide: known symptoms, identifiers to look for, safe actions, and escalation. It must be brief and accessible, not generic documentation that does not help under pressure.
Not all evidence has to be a separate document. A set of tests, a deployment note, and a validation query may be enough if they are precise, findable, and maintained alongside the change.
Minimum and enhanced criteria
For a low-risk change, with no modification to data, external interfaces, or permissions, the minimum usually includes accepted scope, code review, relevant tests, identified configuration, and a post-deployment check. Even here, what is considered correct behavior must be clear.
Add enhanced controls when any of these conditions exist:
- Persistent data is created, transformed, or deleted.
- A rule with economic, contractual, or compliance impact is modified.
- Roles, permissions, authentication, or information exposure are changed.
- Effects are sent to external systems, such as charges, emails, or webhooks.
- The change affects workers, queues, scheduled tasks, or processes that may be repeated.
- Deployment requires coordination among the application, database, infrastructure, or providers.
In these cases, include compatibility between versions, an ordered deployment plan, data validations, testing of foreseeable failures, observability, decision owners, and a containment plan. The useful question is not “are there tests?” but “what evidence would reduce the specific risk of this change?”
Rollback: regain control, not pretend nothing happened
A realistic rollback depends on the effects produced. Rolling back code may be simple; rolling back a destructive migration, a sent email, or an update accepted by an external API is not. Therefore, the criterion must distinguish between rolling back future execution, compensating for effects already emitted, and correcting data.
Before the release, define the threshold that would require action, who can make the decision, and which actions are safe. A configuration flag can stop new executions. A queue can be paused to prevent further effects. A compensating correction may require human review before modifying already processed records. If there is no safe automatic rollback, state so and prepare a recovery procedure with clear limits.
A valid rollback plan identifies irreversible effects, how to contain them, and the evidence needed to know that containment worked.
Example: a new approval in a PHP back office
Suppose a back office adds a rule: certain requests must be approved by a specific role before proceeding to execution. The demonstration may show that a button appears and that the status changes to “approved.” That is not enough.
The definition of done must clarify the state model: which requests require approval, what happens to existing ones, whether an approval can be revoked, and whether two people can act at the same time. It must be verified that the domain service, controllers, API routes, and console commands apply the same authorization. It must also be checked that a worker does not execute pending requests without approval because it uses an old query.
If a status field is added, the migration needs a rule to classify historical records and a subsequent check of the counts. Audit logs should retain the actor, time, transition, and reason where applicable, while avoiding unnecessary sensitive information. Operations needs to know how to detect requests stuck waiting for approval and how to stop processing if an inconsistent transition appears. Rollback could disable the requirement for new requests, but it should not delete already recorded approvals without an explicit decision.
Integrate criteria into the delivery cycle
The definition of done must not be written at the end as a list to close a task. During refinement, product and technology identify rules, dependencies, affected data, and operational consequences. Before development, they agree on acceptance scenarios and the required evidence. During implementation, that evidence guides testing, migrations, instrumentation, and minimum documentation. Before deployment, it is confirmed that the execution order, owners, and containment remain valid.
Avoid three anti-patterns: generic lists that ignore risk; criteria discovered when the change is already ready for deployment; and extensive documentation without actionable signals for support. A good definition of done in PHP projects does not add bureaucracy by default. It makes explicit what must be true for a change to operate safely after the demonstration has ended.
