phpstan.el

Emacs interface to PHPStan, includes checker for Flycheck.

Support version

• Emacs 26+
• PHPStan latest/dev-master (NOT support 0.9 seriese)
• PHP 7.1+ or Docker runtime

Tip

This package provides support for the Editor Mode introduced in PHPStan 2.1.17 and 1.12.27.
We strongly recommend that you always update to the latest PHPStan.

How to install

Install from MELPA

1. If you have not set up MELPA, see Getting Started - MELPA.
2. M-x package-install flycheck-phpstan

How to use

For Flycheck user

(defun my-php-mode-setup ()
  "My PHP-mode hook."
  (require 'flycheck-phpstan)
  (flycheck-mode t))

(add-hook 'php-mode-hook 'my-php-mode-setup)

For Flymake user

(add-hook 'php-mode-hook #'flymake-phpstan-turn-on)

Hover type display without diagnostics (experimental)

If you want type-on-hover without adding diagnostics to Flycheck/Flymake, enable phpstan-hover-mode.

(defun my-php-hover-setup ()
  (require 'phpstan-hover)
  (phpstan-hover-mode 1))

(add-hook 'php-mode-hook #'my-php-hover-setup)

By default, it tries posframe-show (GUI), then popup-tip, and falls back to message.

You can customize hover behavior, for example:

(with-eval-after-load 'phpstan-hover
  (setopt phpstan-hover-idle-delay 0.5) ;; Show popups more quickly than the default.
  (setopt phpstan-hover-display-backend 'auto) ;; Auto-select from available popup backends.
  (setopt phpstan-hover-message-prefix "🔖 ") ;; Use a shorter emoji prefix instead of "PHPStan: ".
  (setopt phpstan-hover-show-kind-label t)) ;; Set nil to hide syntax labels in popup messages.

Using Docker (phpstan/docker-image)

Install Docker and phpstan/phpstan image.

If you always use Docker for PHPStan, add the following into your .emacs file (~~/.emacs.d/init.el~)

(setq-default phpstan-executable 'docker)

Put the following into .dir-locals.el files on the root directory of project.

((nil . ((php-project-root . git)
         (phpstan-executable . docker)
         (phpstan-working-dir . (root . "path/to/dir"))
         (phpstan-config-file . (root . "path/to/dir/phpstan-docker.neon"))
	 (phpstan-memory-limit . "1G")
         (phpstan-level . 7))))

Using composer (project specific)

If your project Composer relies on phpstan, you do not need to set anything.

((nil . ((php-project-root . git)
         (phpstan-executable . docker)
         (phpstan-working-dir . (root . "path/to/dir"))
         (phpstan-config-file . (root . "path/to/dir/phpstan-docker.neon"))
         (phpstan-level . 7))))

Using Composer

Please install phpstan/phpstan package for each user environment or project by using Composer.

If you are unfamiliar with resolving dependencies, the following shell commands are recommended.

$ composer global require phpstan/phpstan

NOTICE: phpstan/phpstan-shim is deprecated. Please read PHPStan 0.12 Released!.

Using PHAR archive

NOTICE: phpstan.el requires PHPStan **0.10+**. We strongly recommend using the latest PHPStan.

Please download phpstan.phar from Releases · phpstan/phpstan.

Settings

Variables for phpstan are mainly controlled by directory variables (.dir-locals.el).

Frequently (root. "path/to/file") notation appears in these variables. It is relative to the top level directory of the project. In general, the directory containing one of .projectile, composer.json, .git file (or directory) is at the top level.

Please be aware that the root directory of the PHP project may NOT match either of PHPStan’s %rootDir% and/or %currentWorkingDirectory%.

Typically, you would set the following .dir-locals.el.

((nil . ((php-project-root . auto)
         (phpstan-executable . docker)
         (phpstan-working-dir . (root . "path/to/dir/"))
         (phpstan-config-file . (root . "path/to/dir/phpstan-custom.neon"))
         (phpstan-level . max))))

If there is a phpstan.neon file in the root directory of the project, you do not need to set both phpstan-working-dir and phpstan-config-file.

Commands

This package provides convenient commands for using PHPStan from Emacs.

Command phpstan-insert-dumptype

Add \PHPStan\dumpType(...); to your PHP code and analyze it to make PHPStan display the type of the expression.

(define-key php-mode-map (kbd "C-c ^") #'phpstan-insert-dumptype)

By default, if you press C-u before invoking the command, \PHPStan\dumpPhpDocType() will be inserted.

This feature was added in PHPStan 1.12.7 and will dump types compatible with the @param and @return PHPDoc tags.

Command phpstan-insert-ignore

Insert a @phpstan-ignore tag to suppress any PHPStan errors on the current line.

By default it inserts the tag on the previous line, but if there is already a tag at the end of the current line or on the previous line, the identifiers will be appended there.

If there is no existing tag and C-u is pressed before the command, it will be inserted at the end of the line.

Command phpstan-copy-dumped-type

Copy a PHPStan type to the kill ring.

When phpstan-hover-mode is enabled and hover data is available at point, this command prioritizes that type.

default

Prefer PHPDoc type if available.

with C-u

Prefer non-PHPDoc type.

If hover data is not available, it falls back to dumped messages from PHPStan\dumpType() / PHPStan\dumpPhpDocType() output.

This command looks for messages like Dumped type: int|string|null reported by PHPStan\dumpType() or PHPStan\dumpPhpDocType(), and copies the type string to the kill ring.

If there are multiple dumped types in the buffer, it selects the one closest to the current line.

If no dumped type messages are found, the command signals an error.

Minor mode phpstan-hover-mode

This feature is made possible by SanderRonde/phpstan-vscode, and is extended in this package with additional hover integrations and behavior tuning.

Enable this mode to show PHPStan type information at point without publishing diagnostics to Flycheck/Flymake.

Behavior summary:

• Runs PHPStan on idle and caches hover type data per buffer/project.
• Uses Editor Mode for modified buffers when available.
• Displays with posframe / popup / message depending on phpstan-hover-display-backend.
• Hides popup on cursor move, window change, or buffer state change.

This mode is independent of checker backends, so it can be used with Flycheck, Flymake, or without either.

API

Most variables defined in this package are buffer local. If you want to set it for multiple projects, use setq-default.

Local variable phpstan-working-dir

Path to working directory of PHPStan.

STRING

Absolute path to `phpstan’ working directory.

• ex) "/path/to/phpstan.phar"

(root . STRING)

Relative path to `phpstan’ working directory from project root directory.

• ex) (root . "path/to/dir")

nil

Use (php-project-get-root-dir) as working directory.

Local variable phpstan-config-file

Path to project specific configuration file of PHPStan.

STRING

Absolute path to phpstan configuration file.

(root . STRING)

Relative path to phpstan configuration file from project root directory.

NIL

Search phpstan.neon(.dist) in (phpstan-get-working-dir).

Local variable phpstan-level

Rule level of PHPStan analysis. Please see README #Rule levels of PHPStan. 0 is the loosest and you can also use max as an alias for the highest level. Default level is 0.

Local variable phpstan-executable

STRING

Absolute path to `phpstan’ executable file.

• ex) "/path/to/phpstan.phar"

SYMBOL docker

Use Docker using phpstan/docker-image.

(root . STRING)

Relative path to `phpstan’ executable file from project root directory.

• ex) (root . "script/phpstan")

(STRING . (ARGUMENTS ...))

Command name and arguments.

• ex) ("docker" "run" "--rm" "-v" "/path/to/project-dir/:/app" "your/docker-image")

nil

Auto detect phpstan executable file by composer dependencies of the project or executable command in PATH environment variable.

Custom variable phpstan-flycheck-auto-set-executable

Set flycheck phpstan-executable automatically when non-NIL.

Custom variable phpstan-memory-limit

Use phpstan memory limit option when non-NIL.

STRING

Specifies the memory limit in the same format php.ini accepts.

• ex) "1G"

nil

Use memory limit in php.ini

Custom variable phpstan-activate-editor-mode

Determines whether PHPStan Editor Mode is available.

nil (default)

Dynamically checks the PHPStan version by getting the path of the installed PHPStan executable.

'enabled

Always use Editor Mode (this will cause an error in older versions of PHPStan)

'disabled

Never use Editor Mode (no support for editors provided)

Custom variable phpstan-docker-image

Docker image URL or Docker Hub image name or NIL. Default as "ghcr.io/phpstan/phpstan". See Docker - PHPStan Documentation and GitHub Container Registory - Package phpstan.

Custom variable phpstan-hover-idle-delay

Seconds to wait after idle before requesting hover data.

Custom variable phpstan-hover-display-backend

Display backend for hover text.

'auto

Try posframe-show (GUI), then popup-tip, then message.

'posframe

Use posframe directly.

'popup

Use popup.el directly.

'message

Use minibuffer message.

Custom variable phpstan-hover-message-prefix

Prefix string shown before hover text.

Built-in choices include:

• "PHPStan: " (default)
• "🔖 "

Custom variable phpstan-hover-show-kind-label

Toggle verbose labels like return:, yield:, foo():, and $var: in hover text.

When nil, hover text shows only the type body.

Custom variable phpstan-hover-debug

When non-nil, re-raise internal hover errors to show full backtraces.

Copyright

This package is released under GPLv3. See ~LICENSE~ file.

Copyright (C) 2026  Friends of Emacs-PHP development

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

phpstan-hover-tree-fetcher.php

~phpstan-hover-tree-fetcher.php~ is derived from SanderRonde/phpstan-vscode’s ~TreeFetcher.php~.

We are deeply grateful to Sander Ronde for publishing and maintaining the original implementation.

This file is not relicensed under GPL by this project. The original MIT License continues to apply to php/phpstan-hover-tree-fetcher.php, and we do not claim additional copyright over the upstream-derived portions.

Copyright 2022 Sander Ronde (awsdfgvhbjn@gmail.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.