Redesign the playground and homepage by alies-dev · Pull Request #143 · psalm/psalm.dev

alies-dev · 2026-11-08T09:24:38Z

Redesigns the playground and the homepage.

Layout: editor and output side by side with a draggable split, a toolbar on top and a status bar below. Settings open in a drawer, with links to the config docs.
Error level: chosen in Settings (default 2), saved with snippets and accepted as ?level= on /check and snippet result URLs; snippet JSON includes error_level. A non-default level is part of the snippet hash, so default-level links are unchanged.
Output: the Issues tab shows each issue's error level and marks auto-fixable ones; a new Types tab lists inferred types; taint traces are numbered steps. Hovering an item highlights its code.
Editor: Ctrl/Cmd+click goes to a definition (php.net for built-ins), signature help while typing a call, auto-closing brackets, #L5-L12 line links. Psalm's byte offsets are converted to character offsets, so issue markers no longer shift after non-ASCII text.
Shortcuts: Ctrl/Cmd+Enter runs, Ctrl/Cmd+S shares, F8 steps through issues.
Fix: "Fix N issues" shows Psalm's fix as a diff to apply or cancel; after applying, the toolbar toggles between the original and fixed code.
Share copies the link and stays on the page.
/play is the full-page playground; /playground, /demo, /try, /sandbox and bare /r redirect there (/r/<hash> is unchanged).
Homepage: 1024px wide again, with a compact widget (editor, Expand, Share), a Get started button and articles from the last 14 days.
Nav: Docs · Playground · Plugins · Blog · Paid support · GitHub icon; page titles (support, blog, docs home) match it.
Stylesheets and scripts are versioned by file mtime instead of hand-bumped ?N keys.

Deploy: run the phinx migration (codes.error_level) before deploying the code; saving snippets needs the column.

Known gap:

Error level 1 still shows MixedAssignment and a few other Mixed issues as info (forced in OnlineChecker).

… status bars The editor sits left and the output right, below a bar holding the PHP version select, Settings and Share, above a status bar with the run state and Psalm version. Markup is shared by the homepage and snippet pages via includes/playground.php, and the styles live in a hand-written assets/css/playground.css that overrides the legacy rules in site.css. Expand/Shrink are gone; their functions are kept as no-ops.

Drag, arrow keys or double-click (reset) on the splitter; the split is kept in localStorage when it is available.

Cmd/Ctrl+Enter re-runs the analysis, Cmd/Ctrl+S shares, F8 and Shift+F8 jump to the next and previous issue (wrapping). Issue locations in the output also jump to the issue.

…efaults Settings open as a right-hand column instead of replacing the output, split into Unused code, Inference and Checks, with a Reset button. The Settings button reads "Settings · N changed" when the settings differ from Settings::defaultValues(). Toggling no longer rebuilds the panel, so keyboard focus stays on the checkbox.

…tus bar Jumping to an issue scrolls only the output pane and marks the issue with a black rule. Below 600px the status items wrap onto their own lines.

… and report in the status bar

… their code

#L5 or #L5-L12 highlights editor lines on / and /r/<hash>; clicking a line number sets the fragment (Shift+click extends, re-click clears) via replaceState. The highlight follows edits through CodeMirror line handles, Share keeps the fragment in the copied link and address bar, and popstate no longer reloads when only the fragment changed.

- Share is the only filled button and shows "Copied ✓", "Copy failed" or "Share failed" for 2s; the status bar message stays. - Fix code becomes a ghost button. It is kept: it rewrites the code, while the "fixable issue(s)" link in the results opens the docs. - Config on the left (compact "PHP 8.6" picker, Settings next to it), actions on the right; the full explanation moves to the picker's title and aria-label, and the drawer header shows the version. - Slow runs (>150ms) dim the output and show "running…" in the tabs bar. - An empty editor says "Write some PHP to analyse". - "Skip to editor" link on playground pages; Share tooltip names the platform shortcut.

…nd page The homepage playground sits next to the intro again (stacked editor over output) with an Expand/Shrink toggle that keeps code, results, settings and the #L fragment. /playground and /r/<hash> open expanded and have no toggle. expandCode() and shrinkCode() work again on the homepage and stay no-ops elsewhere.

Tighten the gap between nav items so seven links fit on one row at 1024px.

/playground now shows only the nav and the playground, which fills the viewport (no heading, no footer). Each setting in the drawer links to its psalm.xml option in the configuration docs, the status bar links the issues, annotations, types, taint analysis and configuration docs, and issue type links get a title.

/check already returns Psalm's IssueData::error_level (the issue class ERROR_LEVEL), so this is client side only. Each issue shows a muted "level N", "any level" (-1, 8) or "feature" (-2) linking to its section of the error levels docs, with a tooltip saying at which errorLevel it is an error. Bug reports include it too.

Per-setting docs links and issue type links stay.

Psalm reports issues in analysis order. The list showed that order while F8 jumped by position, so the highlight hopped around the list, and F8 with the cursor on an issue skipped it. Issues are now sorted by line, column, errors before info, then type, and the list, F8/Shift+F8, lint markers and bug reports all use that order.

…n the status bar Uses the version_tag, version_compare_url and version_commit fields from psalm#127; falls back to version_label when no tag was resolved.

Text nodes directly inside the flex status item became anonymous flex items and lost their leading and trailing spaces, so it read "Psalm7.0.0+2(ca4690d)". Render the label inside one inline wrapper.

…the toolbar Share, Fix code and Report bug on the left; the PHP picker, Settings (above its drawer) and Expand/Shrink on the right. On narrow screens the actions row comes first.

…e version

The playground always ran at errorLevel 2, Psalm's default when psalm.xml has none, and never said so. Settings now offer levels 1 to 8 with 2 as the default, sent as `level` to /check and /add_code and kept in ?level= like ?php=. Snippets store the level in a new nullable `error_level` column; NULL (older snippets) runs at 2. The default level is left out of the snippet hash, so existing links still dedupe. /r/<hash>.json returns the stored level and /r/<hash>/results accepts ?level=.

The toolbar picker right above already shows it.

/playground, /r, /demo, /try and /sandbox redirect to /play. The nav is now Docs, Playground, Plugins, Blog, Paid support and a GitHub icon; "Get started" moves to a button on the homepage.

asset_url() appends ?v=<mtime>, replacing the hand-bumped ?N keys.

The homepage is 1024px wide again with a 492px playground widget, as on the old site. Articles from the last 14 days (up to three) are listed under the widget, or under the intro on narrow screens.

"Paid support for Psalm" on /support, "Blog - Psalm" for the blog index and "Psalm documentation" for the docs home.

views/play.php only set $playground_page and required index.php, so Psalm analysed index.php with that variable fixed to true and reported every homepage branch as dead. The baseline now also lists the template variables that includes/playground.php reads from its includer.

…te request input Clears the Psalm alerts the PR's code scanning raised on touched lines: the include-scope variables become function parameters, check.php rejects non-string code/settings and parses the fix flag as a boolean, and the signature label no longer concatenates a nullable method name.

The not-found branch now exits explicitly, so Psalm knows $result is the row array afterwards instead of mixed.

It bypassed the error-level validation and lacked the navigation data, and its hash matches neither the current nor the previous homepage example.

Rollback replays change() to record what to invert, so the existing-column guard must only apply when migrating up.

…ed symbol field Functions Psalm knows only from its callmap (e.g. ctype_digit) have no FunctionStorage; fall back to the callmap entry.

…te consistent - Non-ASCII text before an issue no longer shifts markers, links and hints - Share saves the PHP version and level it sent, even if changed meanwhile - A stale failed fix request no longer overwrites the run state - Rename navigation to codeNavigation so it does not shadow window.navigation

Also fixes the Expand button disappearing at 1000-1021px widths.

orklah · 2026-11-08T11:25:54Z

Seems good!

One thing to discuss though, there used to be a specific cache for the code example on the root page. It disappears with this PR.
That specific code is pretty simple and it seems doubtful that we will change its result often so the cache seemed a good idea

That cache was persistent so it was never checked, this could be an issue for long period of times but it could probably put in a CI somewhere instead.

Without this cache, the number of analysis is bound to increase a lot

alies-dev · 2026-11-08T11:38:26Z

Good catch, but that cache wasn't being hit: its hash (6ca8d27d...) doesn't match the homepage example on master (65095c36…), and production /check currently returns a live result (Psalm 04cec8e…, 5 issues vs 4 in the cached JSON). It also predates the navigation data and error level, so it would have bypassed the new level validation.

I agree the homepage example is worth caching though. I'll add a small cache in check.php for that example with default settings, keyed by code hash, settings, PHP version, level and Psalm version, so it refreshes itself after a Psalm update without needing CI.

Every homepage view analyzes the same example. Its results are now stored in a temp-dir file keyed by settings, PHP version, level, fix flag, the installed Psalm version and the checker's mtime, so they refresh on their own after a Psalm update or deploy. The example code moves to HomepageExample::CODE so the page and the check share one copy.

Arbitrary settings keys from a client would otherwise create unlimited cache files. The playground always sends every known setting as a boolean, so its requests still hit the cache.

alies-dev · 2026-11-08T11:55:56Z

cache: done in fbae1db and e9767da: any combination of the known boolean settings is cached, unknown keys bypass the cache.

Production deploys don't run composer scripts, so the codes.error_level migration from psalm#143 has most likely not run; add_code.php writes that column, so saving snippets needs it.

Production deploys don't run composer scripts, so the codes.error_level migration from #143 has most likely not run; add_code.php writes that column, so saving snippets needs it.

alies-dev added 30 commits November 8, 2026 01:07

Make the editor and output split draggable and remember it

1c71e56

Drag, arrow keys or double-click (reset) on the splitter; the split is kept in localStorage when it is available.

Add keyboard shortcuts to run, share and step through issues

54ebd10

Cmd/Ctrl+Enter re-runs the analysis, Cmd/Ctrl+S shares, F8 and Shift+F8 jump to the next and previous issue (wrapping). Issue locations in the output also jump to the issue.

Space out the shortcut hints in the status bar

b51e10d

Keep issue navigation from scrolling the page and tidy the narrow sta…

ea75ed6

…tus bar Jumping to an issue scrolls only the output pane and marks the issue with a black rule. Below 600px the status items wrap onto their own lines.

Stop showing the server PHP version in the status bar

a2a12eb

Share without leaving the page: copy the link, update the address bar…

68c36ae

… and report in the status bar

Add a Types tab listing inferred types, each selectable in the editor

2fd17df

Show taint traces and related locations as numbered steps that select…

7466075

… their code

Restore the version format psalm-github-bot parses

95d06de

feat(playground): restore the link icon on Share and drop the run timing

61be2c6

feat(nav): link the playground

0b2b649

Tighten the gap between nav items so seven links fit on one row at 1024px.

feat(playground): redirect /r, /demo, /try and /sandbox to /playground

87d2095

feat(playground): drop the Docs links from the status bar

91c2e65

Per-setting docs links and issue type links stay.

feat(playground): link release, commits ahead and commit separately i…

57600fd

…n the status bar Uses the version_tag, version_compare_url and version_commit fields from psalm#127; falls back to version_label when no tag was resolved.

fix(playground): keep the spaces in the status bar Psalm version

702e6bc

Text nodes directly inside the flex status item became anonymous flex items and lost their leading and trailing spaces, so it read "Psalm7.0.0+2(ca4690d)". Render the label inside one inline wrapper.

feat(playground): put actions on the left and config on the right of …

c6d0764

…the toolbar Share, Fix code and Report bug on the left; the PHP picker, Settings (above its drawer) and Expand/Shrink on the right. On narrow screens the actions row comes first.

fix(playground): link only the commit count, not the plus sign, in th…

2fec213

…e version

fix(playground): drop the PHP version from the Settings drawer header

9a8eb03

The toolbar picker right above already shows it.

style(playground): widen the Settings drawer to 380px

08b5711

fix(playground): draw the Settings select focus outline outside its text

54001fa

fix(playground): keep two-digit taint step numbers off the trace border

67c5c7a

alies-dev added 5 commits November 8, 2026 01:08

feat(site): serve the playground at /play and trim the main nav

84b68d8

/playground, /r, /demo, /try and /sandbox redirect to /play. The nav is now Docs, Playground, Plugins, Blog, Paid support and a GitHub icon; "Get started" moves to a button on the homepage.

build: version stylesheet and script URLs by file mtime

76347f1

asset_url() appends ?v=<mtime>, replacing the hand-bumped ?N keys.

feat(home): narrow the page, add Get started and recent blog articles

9b1bdd6

The homepage is 1024px wide again with a 492px playground widget, as on the old site. Articles from the last 14 days (up to three) are listed under the widget, or under the intro on narrow screens.

fix(site): make page titles match the nav

89c71ec

"Paid support for Psalm" on /support, "Blog - Psalm" for the blog index and "Psalm documentation" for the docs home.

alies-dev self-assigned this Nov 8, 2026

github-advanced-security Bot found potential problems Nov 8, 2026

View reviewed changes

Comment thread views/snippet.php Fixed

alies-dev mentioned this pull request Nov 8, 2026

Update CodeMirror to v6 #95

Open

alies-dev added 6 commits November 8, 2026 10:50

fix(snippet): narrow the fetched row before reading it

f4a23a1

The not-found branch now exits explicitly, so Psalm knows $result is the row array afterwards instead of mixed.

fix(site): drop the hard-coded /check cached result

9e3addd

It bypassed the error-level validation and lacked the navigation data, and its hash matches neither the current nor the previous homepage example.

fix(db): let the error_level migration roll back

1b08d88

Rollback replays change() to record what to invert, so the existing-column guard must only apply when migrating up.

fix(playground): signature help for callmap-only built-ins, drop unus…

de7eacf

…ed symbol field Functions Psalm knows only from its callmap (e.g. ctype_digit) have no FunctionStorage; fall back to the callmap entry.

style(site): remove CSS for the old playground markup

3442a74

Also fixes the Expand button disappearing at 1000-1021px widths.

github-advanced-security Bot found potential problems Nov 8, 2026

View reviewed changes

Comment thread src/HomepageExample.php Fixed

alies-dev added 2 commits November 8, 2026 12:41

fix(site): type the decoded homepage cache entry

35c9082

fix(site): cache the homepage example only for known boolean settings

e9767da

Arbitrary settings keys from a client would otherwise create unlimited cache files. The playground always sends every known setting as a boolean, so its requests still hit the cache.

alies-dev merged commit b79ec8e into psalm:master Nov 8, 2026
2 checks passed

alies-dev deleted the playground-redesign branch November 8, 2026 12:56

alies-dev mentioned this pull request Nov 8, 2026

Enable /migrate to apply the error_level column #151

Merged

This was referenced Nov 8, 2026

Disable /migrate again now that error_level is migrated #152

Merged

Report /check timings in Server-Timing #155

Merged

Navigation Menu

Repository navigation

Redesign the playground and homepage - #143

Redesign the playground and homepage#143
alies-dev merged 46 commits into
psalm:masterfrom
alies-dev:playground-redesign

alies-dev commented Nov 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

orklah commented Nov 8, 2026

Uh oh!

alies-dev commented Nov 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

alies-dev commented Nov 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

alies-dev commented Nov 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

orklah commented Nov 8, 2026

Uh oh!

alies-dev commented Nov 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

alies-dev commented Nov 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alies-dev commented Nov 8, 2026 •

edited

Loading

alies-dev commented Nov 8, 2026 •

edited

Loading

alies-dev commented Nov 8, 2026 •

edited

Loading