- Power user tip: If the error message or error description sounds familiar, check your list of previous solutions, before you spend hours debugging.
- Otherwise, start gathering evidence:
- From error logs, error messages, unusual behaviour, entities with missing information (e.g. Orders, customers, products)
- Reproducibility: If it can't be reproduced, it'll be hard, if not impossible to debug. Wait for it to occur regularly before investing time in debugging it.
- The most obvious things to try. Spend approx. 30m on these steps.
- What changes have recently been made? Have any modules been enabled recently? What changes were made in recent deployments? Admin logs, commit logs, etc can be worth their weight in gold here
- Example: The customer validation issue
- Problem: Customer entity could no longer be saved; Client reported email validation errors, even though they hadn't edited the email address field.
- Solution: After reviewing the admin action logs (this was an EE/Commerce site), I discovered that an email validation class had been added to a field in the customer entity. The field was not used for email addresses however, which then prevented the customer entity from saving (and also broke a customer CSV import as well).
- If you change something and it doesn't fix the bug, change it back - otherwise, you're chasing a moving target.
- If first level solutions have not brought a fix, then we have to forget about easy wins and commit to spending an hour or more on classic debugging.
- Try the 'Comparison technique'- compare the problematic code to the same thing in the core, or from a trusted module which is confirmed as working.
- Try the 'Last known good technique' - roll back the code (either by commenting out your changes or by reverting to an earlier commit, before the problem was reported).
- Keep a note of all the things you've tried already, so you don't waste time repeating yourself (and so you can tell others what steps you've already taken).
- Example: The mass delete issue
- Problem: Fatal error when trying to mass delete items from a custom admin grid (checkbox ID column name was empty in the where clause of the SQL query which populates the collection of items to delete)
- Solution: My intuition told me that I had missed something, because this was an admin grid which I had built based on an example. So I used the 'comparison technique' and found that the solution was a missing class property which needed to be overridden in the Collection class.
- Example: The schema update issue
- Problem: Integrity constraint violation when enabling a custom module
- Solution: Module names have to be less than 50 characters long, but Magento does not enforce module name length. So the database enforces it by truncating the module name. To Magento, this truncated module name is treated as a new module.
- Usually I only get to this point when debugging very esoteric problems, like performance, cron or resource (e.g. Memory) issues.
- Challenge your assumptions: What is the code actually doing vs what you think (or assume) it is doing. This is a great way of discovering
- Rubber duck debugging: Explain the problem to someone else, or even just to yourself. Speaking out loud is crucial to this.
- Reach out to social networks, slack channels, colleagues, stack exchange
- Deploy profiling tools (e.g. Blackfire), to give visibility of the execution path taken through the code
- Problem: The CSV importer that wouldn't import
- E.g. The Client X feed import performance problem: Feeds were running, then failing, meaning lots of entities were not being updated. Running a profiler on the code revealed bad coding practices which were soaking up all available resources. The short term solution involved refactoring some of the worst offending methods, which allowed the import to run and complete. A long term solution involved re-building the importer to take advantage of newer coding standards and PHP features (e.g. Generators).
- Cover your fix with tests (e.g. unit/integration tests)
- Once you've fixed the bug, add the solution to your own library of bug fixes.
- Develop a deep, fundamental, understanding of the critical (and frequently customised) parts of the system (e.g Catalog, order processing, checkout). This helps you spot differences in how something should be working and how it is actually working.
- If you're not learning, you're stagnating. You can always learn something new from anyone, even someone with less experience.
- The big lesson I've learnt from my last few years of being a senior dev is knowing that I don't know everything - and that's alright.
- When I was a junior dev, I thought I knew everything, though I knew the right way to do everything. The 'zen' moment which allowed me to progress to a senior level was realising that I can't learn everything, that I don't know how to do everything and rather than that being a disadvantage or an admission of failure, it unlocks the next level of self-realisation. It gives you the impetus to keep on learning, discovering and growing as a dev.
- There are dozens of other things I try, but these are my most common approaches to debugging.
--
- Add to basket modal issue
- Problem: Disabled products appear in the basket (cross-sells)
- Solution: This is actually core behaviour, but when the core cross-sells collection was being used in a custom way, it became a problem. Added a filter to the collection to filter out disabled products.