Scratch Files and Scratch Buffers in PhpStorm for Quick Experiments

1. What Scratch Files are for

Scratch Files are files edited in PhpStorm with full editor comfort, yet they are not part of the currently open project and, once saved, do not land in its directory structure. They live in their own, IDE managed area outside the project tree, which is why they never show up in git status and can be reused across any number of projects without ever being accidentally committed.

The typical use case is a quick experiment that does not need a permanent home in the project: a colleague sends a JSON response for analysis, a short regular expression needs checking against sample data, or an idea for a PHP function needs to be thought through in isolation before it moves into the actual class. Creating a new file inside the project for all of that, and deleting it again later, would be an unnecessary detour.

2. Creating a new Scratch File

The fastest route is the shortcut Ctrl+Alt+Shift+Insert (on macOS Cmd+Shift+N), which opens a language selection dialog: PHP, SQL, JSON, YAML, Markdown, and practically every language PhpStorm supports are available. After selecting one, an empty editor tab opens immediately with full syntax highlighting, code completion, and inspections, exactly like in a real project file, just without any project context.

It also works the other way around: selected code from any source, such as an email or a chat, can be pasted directly into a new Scratch File tab, and PhpStorm usually detects the language automatically from the syntax. Right clicking a selection in an existing project and choosing New, Scratch File also lets you copy a code snippet from a real project directly into a new, independent scratch context.

Creating a new Scratch File:

Windows/Linux: Ctrl+Alt+Shift+Insert
macOS:          Cmd+Shift+N

-> pick a language (PHP, SQL, JSON, YAML, ...)
-> the file gets an automatic name like scratch_12.php
-> renaming: right click in the Scratches panel -> Rename

Open the Scratches panel: View -> Tool Windows -> Scratches and Consoles

3. Language detection and highlighting without a project

Because a Scratch File is permanently tied to a file extension through the language selection, the same highlighting and inspection rules apply as for any real file of that type, including PHP specific warnings such as unused variables or missing return types. The only notable difference is that project specific features like framework autocompletion for Magento classes do not apply, since the Scratch File has no connection to the project's Composer autoloading.

For pure language experiments without a framework context, such as trying out a new PHP 8.4 feature or testing a regular expression, this is no drawback. For Magento specific snippets, a temporary test inside the project itself is preferable instead, or moving an already finished Scratch File into a real project file later, once the framework's autocompletion context is actually needed.

4. A quick PHP experiment in practice

An everyday example: a colleague asks how to cleanly express a price calculation with discount tiers in PHP. Instead of creating a new project or a test file inside the running Magento project for this, you open a PHP Scratch File, write the function in isolation along with a couple of var_dump calls, and run it directly via right click, Run against the locally configured PHP CLI, with zero framework overhead.

The result can be iterated on in seconds, without ending up with a forgotten debug file accidentally committed to the project, a mistake that happens regularly with quickly created test files inside a real project directory. Once the logic is solid, you copy it directly into the actual class, while the Scratch File can stay around as a reference for similar questions later on.

<?php
declare(strict_types=1);

// scratch_14.php -- quick experiment, no project context

function calculateDiscountedPrice(float $price, array $tiers): float
{
    foreach ($tiers as $threshold => $discountPercent) {
        if ($price >= $threshold) {
            return round($price * (1 - $discountPercent / 100), 2);
        }
    }
    return $price;
}

$tiers = [100.0 => 10, 50.0 => 5];
var_dump(calculateDiscountedPrice(120.0, $tiers)); // 108.0
var_dump(calculateDiscountedPrice(60.0, $tiers));  // 57.0
var_dump(calculateDiscountedPrice(20.0, $tiers));  // 20.0

5. Scratch Files versus Scratch Buffers

Alongside Scratch Files, PhpStorm also has Scratch Buffers, short lived, unnamed editor tabs that open even faster but by default have no permanent language assignment and can be lost after closing without an explicit save. They suit the absolute shortest intermediate step, such as briefly reformatting a pasted line of text, while a real Scratch File is meant for anything that outlives a few seconds.

In practice, most developers use Scratch Files almost exclusively, because their persistence across IDE restarts and their fixed language assignment are considerably more reliable. Scratch Buffers show their strength more in specialized contexts, for example as a temporary buffer inside certain plugin tools that do not want to create a permanent file themselves.

6. SQL scratches and HTTP client requests

Scratch Files with the SQL language are especially useful combined with an already configured database connection: a new SQL Scratch File can be run directly against a Magento database registered in the Database panel, complete with autocompletion for table names and columns, without any detour through the MySQL command line or a separate admin tool like phpMyAdmin.

Equally practical is a Scratch File with the .http extension for PhpStorm's built in HTTP client: a quick request against the Magento REST or GraphQL API, for example to check a new endpoint, can be written as a Scratch File, executed directly inside the IDE, and its response viewed inline, without opening an external tool such as Postman.

### scratch_http.http -- quickly testing a REST endpoint

GET http://magento.test/rest/V1/products/24-MB01
Authorization: Bearer {{admin_token}}
Accept: application/json

### Fetch an admin token (separate request in the same Scratch File)

POST http://magento.test/rest/V1/integration/admin/token
Content-Type: application/json

{
  "username": "admin",
  "password": "admin_password"
}

7. Organizing many Scratch Files in daily use

Anyone using Scratch Files regularly quickly accumulates two or three digit numbers of them, and the automatically generated names like scratch_7.php help little with that. A look at the Scratches and Consoles panel via View, Tool Windows, Scratches and Consoles shows every existing file in its own tree structure, where right click, Rename lets you assign meaningful names like price-discount-test.php, which makes finding them later much easier.

The same panel also lets you create subfolders to group thematically related Scratch Files, for example magento-api-tests or sql-queries, by dragging them within the tree. Consistently deleting old, no longer needed Scratch Files instead of letting them pile up keeps the panel manageable, much like browser tabs that quietly accumulate into dozens without any cleanup.

8. Versioning and sharing: what is missing

Scratch Files are not versioned by default and sit outside any Git repository, which turns their biggest advantage, no accidental commits, into their biggest weakness at the same time: there is no built in history beyond the already mentioned Local History mechanism, and content cannot be shared directly with a colleague without copying it manually. Anyone wanting to keep a Scratch File permanently should deliberately export it into a small, dedicated snippets repository.

JetBrains Settings Sync can mirror Scratch Files between several of a single user's own machines, provided Settings Sync is enabled and the corresponding option for scratches is turned on. For handing files to colleagues, the only route remains manual: copying, a shared snippet collection in the team wiki, or a small dedicated repository into which especially useful Scratch Files get deliberately moved when needed.

9. Limits and comparison to alternatives

Compared to alternatives like a separate terminal tab or a disposable project folder of its own, a Scratch File offers the decisive advantage of keeping the full comfort of the IDE right next to the actual work, without switching window or project context. This very comfort, combined with the lack of permanent versioning, makes Scratch Files the ideal tool for anything that is allowed to appear quickly and disappear just as quickly.

The table below compares four options for quick experiments, measured by IDE comfort, versioning, and the effort of cleaning up afterward.

10. Summary

11. FAQ: Scratch Files: The Essentials at a Glance