Jan Mikoláš
Glossary
Debugging
The goal is not to silence an error message. It is to find the cause and confirm that the same error will not return.
Short definition
From an observed problem to a verified cause.
Debugging starts with a concrete symptom: an error page, wrong result, slow response, or unexpected data state. The developer creates a repeatable scenario, gathers evidence, and rules out hypotheses until they find where expected and actual behaviour diverge.
It is not the same as logging or testing. Logging records selected runtime information and can provide a clue. A test checks expected behaviour in advance. Debugging investigates an observed problem; after the fix, a test should ensure the problem cannot quietly return.
When it helps
When a symptom does not explain its cause
Start with a small, precisely described case instead of reading the entire project.
- an error from one form or HTTP request that appears only for some inputs
- an unexpected exception or empty application response
- a wrong result of a calculation, import, or order update
- a problem that appeared after deployment or with a particular combination of data
- a regression after a code, configuration, or dependency change
Practical example
An order discount sometimes ends in an error
Support reports that an order with a gift voucher ends on an error page. First, collect the same inputs: voucher type, cart items, locale, and the time of the error. Without reproduction, the developer could inspect an entirely different application path.
The stack trace shows that the problem appears while calculating the discount. A breakpoint or safe local value inspection reveals that one branch passed an empty value where the calculator expects a number. The fix adds an explicit rule for the missing value, and a PHPUnit test with the same inputs becomes a regression test.
Process
Five steps from error to fix
Every step should reduce the number of possible causes. Skipping steps often creates only a temporary patch.
- Describe the symptom Write down what happened, to whom, when, and what result was expected. Attach a safe request or error identifier, not a password or complete sensitive payload.
- Reproduce the problem Find the smallest repeatable procedure and the same conditions. If it cannot be reproduced, widen observation instead of guessing a fix.
- Form a hypothesis For example: “The error happens only when the discount is missing.” The hypothesis must be possible to disprove with one focused observation.
- Gather evidence Read the stack trace, compare inputs and state, or use a breakpoint in a local or safe development environment. Follow the path to the cause, not only the final line of the error message.
- Fix and prevent a return Fix the cause, repeat the scenario, and add a regression test. Then check nearby edge cases that use the same rule.
Tools and boundaries
What each technique can and cannot do
Good diagnosis combines a small amount of relevant evidence. More output does not automatically mean more understanding.
Logging
A log preserves selected runtime information, such as time, request ID, or error type. It is a useful clue, but it does not expose every value or decision. Sensitive data, tokens, and full personal payloads do not belong in logs.
Stack trace and breakpoint
A stack trace shows the call path to the error. A breakpoint pauses execution and lets you inspect values and branches. Breakpoints are mainly for local work; a production request must not be delayed or expose data.
Testing
An automated test checks a scenario described in advance. Debugging finds the cause of a scenario that already failed. After the fix, add a PHPUnit regression test so the error appears earlier on the next change.
Static analysis
Static analysis examines possible types and contradictions without running one specific scenario. It can catch a similar error earlier, but it does not replace reproduction or investigating real production data.
Benefits and risks
Faster investigation without dangerous shortcuts
What works
- one concrete scenario and a clearly described expected result
- small hypotheses that can be confirmed or disproved quickly
- a stack trace, error context, and carefully chosen safe observations
- a regression test added with the fix
What to avoid
- random code changes without evidence of the cause
- disabling an exception or quieting a log instead of fixing the rule
- debug output and public stack traces in production
- catching only the symptom while the wrong state arises earlier
Practical use
First reduce the problem, then reduce the change.
For a common error, reproduction, a stack trace, and one focused test are enough. A problem across several services needs safe correlation IDs, a timeline, and the boundaries between systems. Even then, it is better to test a few small hypotheses than to read every available log.
When the problem is performance-related, the approach changes: measure time and call counts instead of stopping at a breakpoint. In a Symfony application, a profiler can help during local development. In production, diagnostics belong in secure monitoring, not a public debug panel.
Checklist
What should remain after solving an error
The aim is more than a green screen: it is a traceable cause and confidence that the fix covers the affected rule.
- a short description of the symptom, expectation, and reproduction steps
- a safe context record without secrets or unnecessary personal data
- a named cause, not only a list of changed files
- a regression test and, where suitable, static analysis for a nearby type risk
- a small traceable change in version history with an explanation of its impact
Common questions
What debugging means in practice
Is debugging the same as adding a log?
No. A log is one source of evidence. Debugging includes reproduction, hypotheses, comparing expectations with reality, and confirming the fix.
Why add a regression test after a fix?
A test catches the same scenario before a user does on the next change. It should verify the observable rule that was broken, not only one implementation line.
Can I use a breakpoint in production?
Usually no. Pausing a process can delay users, expose sensitive data, and make an outage worse. In production, use secure logs, metrics, and tracing with restricted access.
Does a stack trace always show the real cause?
It shows where the error appeared and how the program got there. The cause may be earlier: wrong input, configuration, data state, or an incorrect assumption.
How I work with quality in practice
I follow an error from its cause to verified protection against its return.
I combine repeatable scenarios, tests, and static checks so that changes remain understandable and safe for the next iteration.