Skip to content

Support Linux development identity and deep links - #130

Draft
SRWieZ wants to merge 4 commits into
NativePHP:mainfrom
SRWieZ:agent/linux-dev-desktop-identity
Draft

Support Linux development identity and deep links#130
SRWieZ wants to merge 4 commits into
NativePHP:mainfrom
SRWieZ:agent/linux-dev-desktop-identity

Conversation

@SRWieZ

@SRWieZ SRWieZ commented Jul 18, 2026

Copy link
Copy Markdown
Member

What changed

Give Linux development apps a stable desktop identity and make custom protocol delivery reliable across cold and warm application starts.

  • derive a project-scoped Linux development identity from the configured app ID and checkout path
  • write a matching hidden XDG desktop entry with a development icon and StartupWMClass
  • make the development entry launchable for configured protocol URLs and register it with xdg-mime
  • expose the configured protocol in development and packaged application metadata before Laravel starts
  • capture protocol URLs from startup arguments, open-url, and second-instance
  • queue URLs until Laravel is ready and retain them when delivery fails
  • request the non-macOS single-instance lock before application bootstrap
  • restore and focus existing windows when a second instance receives a link

Why

Linux shells resolve a running window identity through a desktop entry. The same entry is also the freedesktop integration point for development protocol handlers. Deep links can reach Electron before Laravel and its event endpoint are available, so immediate delivery can lose OAuth callbacks on cold start.

Production protocol declarations continue to use electron-builder. macOS and Windows use their existing registration mechanisms while sharing the queued delivery path.

Coexistence and DX

Development never reuses the production desktop ID. Its identity includes a nativephp-dev marker and a checkout-path hash, so production builds and parallel checkouts remain separate. The development entry is hidden from launchers and refreshed atomically. Failure to write it or invoke xdg-mime emits a warning without preventing startup.

Validation

  • PHP: 120 tests / 339 assertions
  • PHPStan and Pint pass
  • Electron plugin: 29 tests pass
  • TypeScript plugin build passes
  • Electron production build passes with DevKeepr fixture environment
  • KDE Wayland reports matching resourceClass and desktopFileName

Remaining manual validation

  • exercise a Linux protocol URL while the application is closed
  • exercise a second protocol URL while the application is already running
  • confirm the generated development desktop entry is the active XDG handler

@SRWieZ SRWieZ changed the title Match Linux development window icons Support Linux development identity and deep links Aug 24, 2026
@SRWieZ

SRWieZ commented Aug 24, 2026

Copy link
Copy Markdown
Member Author

CI note: the php-code-styling job fails before Pint starts. Its checkout step requests agent/linux-dev-desktop-identity from NativePHP/desktop, but this pull request branch exists in the SRWieZ/desktop fork. vendor/bin/pint --test passes locally; the complete PHP version/Laravel matrix, PHPStan, plugin tests, and plugin build all pass.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant