An import that takes hours, a report that queries several sources, or a task that coordinates integrations can keep consuming resources long after it has stopped being useful. Without explicit limits, it is also difficult to tell whether it is working, blocked, or incomplete. Designing time limits for long-running PHP processes requires defining how long each stage may take, how work is stopped, and what status is preserved if execution is interrupted.
The goal is not to impose a single number on the entire process. It is to establish a consistent end-to-end budget, pass it on to dependent operations, and ensure the final status reflects what happened. A timeout, a requested cancellation, and forced termination are distinct situations and should be treated as such.
Why an explicit limit is needed
A process without a deadline can retain memory, connections, and execution capacity indefinitely. It can also leave a task marked as active even though it is no longer making progress. In an environment with workers, the problem is amplified: a blocked execution occupies a worker and can delay subsequent jobs.
PHP or server limits are not a substitute for an application policy. For example, max_execution_time can limit a script's execution, but it does not necessarily represent how long the business is willing to wait. In addition, the limits imposed by the web server, PHP-FPM, the queue manager, the HTTP client, and the database can act independently. If they differ, one layer may terminate the work before another has a chance to save the corresponding status.
First identify where the process runs and which components can stop it. A console task, a queue worker, and a web request have different mechanisms and consequences. The application-level limit must coexist with these external controls, rather than relying on one of them to handle termination on its own.
Distinguish timeout, deadline, and cancellation
- Operation timeout: the maximum time a specific call can wait, such as a query or an HTTP request.
- Global deadline: the cutoff time for the entire process. Stages share the remaining time instead of each receiving the full budget.
- Requested cancellation: an explicit decision to stop working, for example because a user cancelled the task or the system removed it from a queue.
A timeout indicates that an operation did not finish within its budget. By itself, it does not mean the entire process must stop; that depends on the stage and the product rules. Cancellation, by contrast, is a control signal that the process must check and handle when it can do so safely. Neither guarantees that an operating system or supervisor will stop execution at a precise point; forced termination can occur between checks.
Represent the deadline as an absolute time or as the remaining time calculated from a monotonic clock. Before starting a stage, check whether there is still time available. This prevents a sequence of operations with individual timeouts from consuming much more than the global budget. In PHP, encapsulate the calculation and cancellation check in a shared object or service instead of duplicating scattered comparisons.
Allocate the budget across stages and dependencies
Break the process into observable stages, such as reading, transformation, writing, and external coordination. Define how much time each can consume without exceeding the global deadline. The budgets do not all need to be identical: a stage with bounded local work may need a different limit from a call to a remote service.
When calling a dependency, use the lower of its operational timeout and the process's remaining time. Configure connection and read limits separately when the library allows it. A fast connection does not prevent the response from taking too long, and a read timeout does not necessarily include all the preceding time. Apply the same principle to SQL queries, storage operations, and child processes, using the controls each client provides.
If an operation does not support cancellation, do not present it as immediately interruptible. You can limit how long you wait, isolate it in a separate unit of work, or design the flow to check for cancellation before and after it. For child processes, retain the identifier needed to request termination and verify that the process has exited; sending a signal is not the same as confirming its exit.
Stop the work and leave an understandable status
When the deadline expires or cancellation arrives, avoid starting new stages. At safe points, complete the essential local actions needed to record the result and release controllable resources, such as cursors or temporary files. The cleanup block should not attempt to finish pending work: it must also have a time limit and must not obscure the reason for stopping.
Save the task status in durable storage, associated with a stable identifier. At a minimum, record distinguishable statuses such as running, completed, cancelled, and timed_out, along with the current stage and relevant timestamps. Add a reason that is readable by operators, without storing unnecessary sensitive data. Update the status atomically where possible, and account for the possibility that the process may die before completing that update.
The result shown to the person who started the task should distinguish “cancelled” from “failed due to timeout.” If the status still cannot be confirmed after abrupt termination, show it as unknown or pending verification, not as completed. Metrics and structured logs can include duration, stage, and type of termination; avoid logging secrets, private content, or traces without access controls.
Decide whether partial effects can be resumed
An interruption can occur after data has been written but before the stage is recorded as complete. Therefore, deciding whether work can be resumed is not just a matter of saving the stage number: you need to understand what effects may have occurred. For local operations, a transaction can group related changes if its duration and the database engine allow it. Do not keep a transaction open during a long external call.
For batch work, record completed units with a stable key and define when a unit is actually committed. If a write is repeated after a restart, the design must prevent duplicates or recognize that the effect already exists. An external integration that does not offer cancellation may have accepted a request even though the client stopped waiting; the status should reflect that uncertainty rather than assume that no effect occurred.
If it is not safe to continue from the last saved point, mark the task for review or for a specific recovery procedure. Automatically resuming from an imprecise marker can produce an incorrect result. Document which stages are repeatable, which require verification, and what conditions allow the process to be declared complete.
Test limits and interruptions
Tests should verify both termination and the final status, not just that an exception was thrown. Use controllable dependencies to simulate a slow call, a query that exceeds its deadline, and a response that arrives right at the limit. Check that the duration of a stage cannot cause the global deadline to be ignored.
Test cancellation between stages and during an operation that can only be stopped when it returns. Also simulate abrupt termination at relevant points: after an external effect, before saving the status, and during cleanup. After restarting the worker, verify that the status is understandable and that the resume policy does not duplicate or omit work. These tests should use isolated data and must not depend on real external services.
Checklist for an existing process
- Identify the limits imposed by PHP, the server, the worker, and each client in use.
- Define a global deadline and per-stage budgets that do not exceed it in combination.
- Propagate the remaining time to HTTP, the database, and other processes where possible.
- Check for cancellation at safe points and avoid starting new work after receiving it.
- Persist distinct statuses, the current stage, and the reason for termination.
- Describe which partial effects may remain and what conditions allow work to resume.
- Test delays, cancellations, abrupt terminations, and the status observed after restarting.
A sound design does not promise that every operation can be stopped instantly. It makes the available time explicit, limits waiting on each dependency, and preserves enough information to interpret an interruption. This combination turns a long-running process from an opaque execution into an operable and verifiable unit.
