Preparing Code Reviews in PhpStorm: Diffs, History, Blame and TODOs

1. Preparing code reviews in the IDE, why it makes sense

A code review is only as good as the context the reviewer has. Anyone reviewing a pull request in the GitHub interface sees flat diffs without access to the full file history, without live static code analysis, and without the ability to navigate directly into the code. PhpStorm solves this problem by integrating all review-relevant tools, the Diff Viewer, Git Log, Annotate view and TODO tracker, deep into the IDE.

For PHP teams working on Magento projects or other large PHP codebases, the difference is especially clear: a diff in the GitHub interface shows that a method was changed. The PhpStorm diff simultaneously shows whether the method still fulfills the interface contract, whether an unresolved dependency is introduced, and whether the PHPDoc comments match the new signature. This combination of version control and static analysis makes reviews more thorough and faster.

This article shows how the individual PhpStorm tools are used for structured reviews, which keyboard shortcuts matter most, and which settings improve the workflow, with the goal of making reviews part of the normal development routine inside the IDE rather than a separate browser process.

2. The Diff Viewer: understanding changes in context

PhpStorm's Diff Viewer opens in several contexts: when opening a file from the Changes panel (Alt+9), when comparing two branches from the Git Log, or when directly invoking Ctrl+D on a file. The decisive advantage over web diffs is the side by side view with full syntax highlighting, navigation between change blocks via arrow buttons, and the ability to edit directly in the right panel.

All of PhpStorm's navigation features are available in the diff view: Ctrl+Click on a class name navigates to its declaration, Alt+F7 shows all usages, Ctrl+Q opens the Quick Documentation popup. This makes it possible, while reviewing a method, to immediately see whether the called methods exist, expect the correct parameters and are documented, without ever leaving the Diff Viewer.

For branch comparisons, open the Git panel via Alt+9, right-click a branch and choose "Compare with Current". PhpStorm shows all changed files together with their diff previews. The filter function in the Changes panel makes it possible to filter files by type, for example only PHP files or only template files, and thereby systematically split reviews of large feature branches.

<?php
// Before: method without return type (visible in left diff panel)
class OrderProcessor
{
    public function process($order)
    {
        // implementation
    }
}

// After: typed, with interface contract (visible in right diff panel)
// PhpStorm diff highlights: return type added, interface implemented
class OrderProcessor implements OrderProcessorInterface
{
    public function process(OrderInterface $order): ProcessResultInterface
    {
        // PhpStorm: Ctrl+Click on ProcessResultInterface -> navigate to declaration
        // PhpStorm: Alt+F7 on process() -> find all usages instantly
        return $this->executeProcessing($order);
    }
}

3. File History and Log: why was this line changed?

File History in PhpStorm shows the complete Git commit history of a single file, accessible via right-click on the file in the Project tree and then "Git > Show History", or via Alt+9 and the History tab in the Git panel. Every commit in the list shows author, date, commit message, and can be opened directly as a diff against its predecessor.

Particularly valuable during review is the "Show History for Selection" feature: select a code block and call up the history for that block only. This shows exactly which commits touched that area in the past, ideal for answering why a complex algorithm was written the way it was. In Magento projects, where plugin chains and event dispatching are not always obvious from the code alone, this view provides essential context.

The Git Log in full screen (Alt+9, then the "Log" tab) shows the entire repository history with filter options by branch, author, date and commit message. The "Show Diff" action directly from the log opens the full diff of the commit. With the branch comparison function, the exact commit difference between a feature branch and main can be visualized, as a list of all commits with their diffs, in the same order they were created.

<?php
// PhpStorm File History workflow for reviewing legacy code:
//
// 1. Right-click on file -> Git -> Show History
// 2. Each commit listed: date, author, message, changed lines
// 3. Double-click commit -> full diff opens in Diff-Viewer
// 4. For specific block: select lines -> Right-click -> Git -> Show History for Selection
//
// Example: complex Magento plugin chain, understanding WHY it exists
class ProductPricePlugin
{
    /**
     * Applied in commit a3f8b2: hotfix for rounding error in EUR pricing
     * Visible in File History: "Fix: EUR price rounding SC-1042"
     * Without history: looks like unnecessary complexity
     */
    public function afterGetFinalPrice(
        \Magento\Catalog\Model\Product $subject,
        float $result
    ): float {
        // Two-decimal rounding enforced after discount calculation
        return round($result, 2);
    }
}

4. Annotate (Git Blame): tracing the origin of every line

The Annotate view in PhpStorm corresponds to git blame on the command line, but is significantly more comfortable to use: via right-click in the editor gutter (the left margin with line numbers) and "Annotate with Git Blame", the associated commit, author and timestamp are displayed for every line. Clicking a commit hash opens the full diff of that commit.

In a review context, the Annotate view is especially valuable for lines that were not changed in the current diff but are still relevant. When a new method calls an existing helper function, Annotate immediately shows when and by whom that function was last changed, and whether it is part of another feature currently in progress that has not yet been merged.

PhpStorm also supports "Annotate Previous Revision": you can work backwards through the blame history of a line and see how it evolved across multiple commits. This is the most powerful tool for understanding why an implementation exists and whether it was designed that way intentionally. Combined with the ability to jump directly from the Annotate panel into the commit diff, this produces complete context without a terminal.

5. TODO tracker: making open items visible

The TODO tracker in PhpStorm aggregates all TODO comments in the project into a searchable list, accessible via "View > Tool Windows > TODO" or Alt+6. By default, PhpStorm recognizes TODO, FIXME, HACK and XXX as markers. Custom markers can be defined under "Settings > Editor > TODO" with regular expressions and highlighted in color.

For code reviews, the TODO tracker is valuable in two ways: first, it shows which TODOs were newly introduced by the current branch, and these should be explicitly commented on during the review. Second, TODOs can be used to leave review notes directly in the code: a temporary // REVIEW: Why no interface? comment appears immediately in the TODO panel and can easily be removed again after the review.

PhpStorm can also filter TODOs by scope: only the current branch, only changed files, or only specific directories. In Magento projects with thousands of PHP files, this filtering is essential to avoid getting lost in the noise of every TODO present across the whole project. Integration with changelists (next section) makes it possible to show TODOs only for the files in the current changelist.

<?php
// PhpStorm TODO markers, configurable under Settings > Editor > TODO
// Default recognized: TODO, FIXME, HACK, XXX

class CheckoutSessionPlugin
{
    // TODO: Extract to separate service class after SC-2045 is merged
    // FIXME: Race condition possible when two tabs submit simultaneously
    // REVIEW: Is this plugin order correct? Check plugin.xml di.xml priority
    public function afterGetQuote(
        \Magento\Checkout\Model\Session $subject,
        \Magento\Quote\Api\Data\CartInterface $result
    ): \Magento\Quote\Api\Data\CartInterface {
        // HACK: Workaround for Magento bug MGT-1234, remove after 2.4.9
        if ($result->getItemsCount() === 0) {
            $this->logger->warning('Empty quote returned from session', [
                'customer_id' => $subject->getCustomerId(),
            ]);
        }
        return $result;
    }
}

// In PhpStorm: Alt+6 -> TODO panel shows all markers
// Filter: "Scope: Changed Files" -> only shows TODOs in current diff
// Custom marker regex: \bREVIEW\b.* -> highlighted in orange

6. Changelists: grouping changes and preparing a review

Changelists are a PhpStorm-specific feature that many teams are not aware of: instead of leaving all local changes in a single uncommitted group, files can be split into named changelists. Each changelist represents a logical unit, for example a bugfix, a feature or a refactoring step. New changelists are created in the commit dialog or via the Changes panel (Alt+9).

This is particularly useful for review preparation when a branch contains several independent changes. Instead of confronting the reviewer with a mixed diff, changelists can be used to point deliberately to individual parts of the change during a review conversation. In PhpStorm, a single changelist can be exported as a patch (Ctrl+Shift+A, then "Create Patch from Changelist") and shared with the team, as an alternative to a complex PR.

Changelists also have a practical advantage when committing: you can commit only the files of one changelist, even when other files have already been changed. This supports atomic commits and clean Git histories, a prerequisite for reviews where every commit represents an independent, verifiable unit.

<?php
// PhpStorm Changelists, organizing changes for review

// Changelist 1: "SC-1042 Fix EUR price rounding"
// Files: Model/Pricing/Calculator.php, Test/Unit/Model/Pricing/CalculatorTest.php

// Changelist 2: "Refactor: extract OrderValidator"
// Files: Model/Order/Validator.php (new), Service/OrderService.php (modified)

// Changelist 3: "REVIEW: WIP, do not commit"
// Files: scratch notes, debug traces

// In PhpStorm: Alt+9 -> Changes panel
// Right-click on file -> Move to Another Changelist
// To commit only one changelist: Commit dialog -> select changelist -> commit

// Create patch from changelist for sharing:
// Ctrl+Shift+A -> "Create Patch from Changelist" -> save .patch file
// Team member applies: VCS menu -> Apply Patch

// Shortcut to move file between changelists: Ctrl+Shift+M (default)

7. The complete review workflow in PhpStorm

A complete review workflow in PhpStorm begins by checking out the branch to be reviewed locally: select the branch in the Git panel and choose "Checkout", or use the branch selector at the bottom right of the status bar. PhpStorm automatically updates all indexes. Next, open the branch comparison: Alt+9, right-click the branch, "Compare with Current".

In the next step, work systematically through the changed files: double-click opens the Diff Viewer. For each changed file, use Annotate to make sense of older lines, File History for complex sections, and the TODO tracker for open items. Review notes are left as temporary TODO comments directly in the code, they appear in the TODO panel and can be removed again after the review.

To wrap up the review, all review TODOs are removed from the code, the reviewer's changelist is cleared, and the branch is checked back to your own state. The result of the review flows into GitHub or GitLab as comments, that is where the team makes the formal review decisions. PhpStorm is the tool for content preparation, not for the formal decision.

8. Comparison: PhpStorm vs. the GitHub UI for code reviews

Both tools have their strengths. The GitHub review interface is the shared place where formal decisions are made, comments are visible to everyone, and review status is documented. PhpStorm is where the actual content analysis happens, with full IDE context, static analysis and navigation.

9. Summary

Preparing code reviews in PhpStorm means keeping the content analysis inside the IDE and making only the formal decision in GitHub or GitLab. The Diff Viewer offers side by side comparisons with full IDE context. File History and "Show History for Selection" provide the why behind changes. The Annotate view shows the origin of every line and navigates directly to the associated commit. The TODO tracker makes open items visible and allows temporary review notes directly in the code. Changelists group changes logically and enable atomic commits.

The biggest gain lies in combining these tools: a review starts with the branch comparison, uses Annotate for context, File History for background, and the TODO tracker for tracking. This makes reviews more thorough and less time consuming, because the reviewer does not have to switch between IDE, terminal and browser to gather all relevant information.

10. FAQ: Code Reviews in PhpStorm