User:ArielGlenn/Emacs as a PHP IDE

I love my emacs. I like its multiple buffers and its key bindings and its split windows and all the rest. I don't love grep -r in the mediawiki git repo.

What's to be done? There's no open source PHP IDE that lets one use emacs as the editor in some sub-window, to my knowledge. How about closed source? Nope.

I looked at docs for PHPStorm, CodeLite, Atom, Aptana, and others. No joy. Enter LSP to save the day! Drumroll please...

Emacs with LSP step by step
The TL;DR:
 * build emacs 28-pre with native compilation and with a C json library
 * choose an LSP backend and install it
 * install the LSP-related emacs packages from elpa
 * install a few other elpa packages to round out the IDE experience
 * configure the packages and the use of the specific LSP backend
 * curse when it doesn't work until you determine that PEBCAK is to blame
 * tweak and enjoy

We'll go through each of these in detail.

What I wanted from a PHP IDE
There are really only four capabilities that I had to have:
 * 1) code navigation: moving to the code defining a class or method, from some other code using it
 * 2) docs on hover: display of the arguments and any related docs for a class or method, when the cursor is on a reference to it
 * 3) completion: variable, method and class name completion when coding
 * 4) speed: waiting for project indexing on first use is ok, but not afterwards.

No refactoring, no extra debugging features, none of that. Just the basics. Remember, my ide until now had been grep -r.

LSP, the game-changer
Language Server Protocol is a Microsoft specification for a protocol intended for use by a stand-alone server that responds to well-defined requests (where is the definition of this method? Where is this class used?) with the information requested in a specific format. Any number of clients may communicate with the server as long as they support the protocol. If your favorite editor supports it, and there's a server you like for your language, you can use it.

In other words, instead of having to build all of the capabilities we want into emacs or any other editor, a separate PHP language server can do the heavy lifting for emacs or any other editor that supports LSP from the client end.

I guess that most IDEs do not use this approach; they directly implement every feature that is desired. That's fine for IDEs with a large and demanding user base. But for just the basics, LSP is a fine choice. For more incindiary rhetoric on this topic, see the relevant HackerNews thread.

Building emacs
First things first; we need json handled by a C library: libjansson. Emacs 27 supports this, but I had only emacs 26.

We also would like native compilation, also known as gccemacs. This provides support for compiling el files into binary (elf files)! This feature is not available in Emacs 27, but may be merged into master "soon" with an eye to making it available in emacs 28. For now, it's in a separate branch. Lots more information about gcc emacs is available on the updates page for the project.

I built emacs in the following environment:


 * OS: Fedora 31, nearly two versions old
 * GCC: 9.3.1 but GCC 10 will work as well

I did NOT build with mailutils support. If you want that, adjust the below accordingly.

Steps to build for installation in /usr/local:


 * git clone https://git.savannah.gnu.org/git/emacs.git
 * git checkout -b native-comp origin/feature/native-comp
 * dnf install libgccjit libgccjit-devel jansson jansson-devel
 * dnf install webkit2gtk3 webkit2gtk3-devel libXpm-devel giflib-devel
 * install any other devel packages you'll need, or wait until configure complains about them
 * cd emacs
 * ./autogen.sh
 * ./configure --with-json --with-nativecomp --with-xwidgets --with-x-toolkit=gtk3
 * make check
 * as root, make install

If you have any packages in your .emacs.d, update them now. I used development packages where I could.

Test out your new emacs binary. The first time you run it, it will compile all of those packages. If you try to exit out before it's done, it will ask you whether you really want to interrupt those running compiles. You'll encounter this any time you install or upgrade a package. If you're curious about the output, have a look in .emacs.d/eln-cache.

Selecting an LSP backend
There are a few free as in beer PHP LSP servers, most of which are also free software. I looked at several of them: Intelephense, Serenata, Felix Becker's php language server. I did not try out the Tenkawa PHP Language Server. Have a look at the features, how active the project is, and the license if you are a FLOSS supporter.

In the end, I went for Serenata, as it is currently maintained, open source, and has the features I needed. After setting up lsp-mode (see below), I double-checked the enabled features list in emacs for each server, and Serenata was the winner.

Installing Serenata is easy enough:


 * download the PHAR file corresponding to your version of PHP from the list of releases
 * put it in a location that doesn't trigger your OCD
 * make sure it is executable; if you don't, you will spend hours wondering why emacs cannot find it and offers to download intelephense

Installing emacs packages for LSP
You may decide to use some other combination of things, but you will want at a minimum:
 * php-mode (duh!)
 * lsp-mode
 * lsp-ui-mode (highly recommended)
 * company and company-lsp (for lsp-mode)
 * flycheck (for lsp-mode)
 * treemacs and lsp-treemacs (for lsp-mode)
 * which-key (for lsp-mode)
 * xref (for lsp-mode and lsp-ui-mode)
 * yasnippet (for lsp-mode)

I use treemacs for code navigation of the project as well as for display of trees via lsp. You may choose some other means. I also have phpunit installed.

Note that in very case where I could, I installed the latest development package.

Package configuration
I use "use-package" for everything, with a mix of cargo-cult copy-pasting and rolling my own.

PHP mode configuration
MediaWiki PHP coding style is its own thing, so setting up for appropriate tabs is a must. Here is the stanza I use for that, stolen shamelessly from Stack Overflow. Note that there's a whole section in the MW coding conventions manual for that, but I haven't looked at that at all.
 * php-mode setup

(defun my-php-mode-hook  (setq indent-tabs-mode t)  (let ((my-tab-width 4)) (setq tab-width my-tab-width) (setq c-basic-indent my-tab-width) (set (make-local-variable 'tab-stop-list)        (number-sequence my-tab-width 200 my-tab-width))))

And here's the stanza for php-mode itself. (use-package php-mode :ensure t  :hook  (php-mode-hook. my-php-mode-hook) :mode  ("\\.php\\'". php-mode) ("\\.inc\\'". php-mode))

which-key, flycheck, phpunit
(use-package flycheck :ensure t  :init  (global-flycheck-mode))

(use-package which-key :ensure t  :config  (which-key-mode))

(use-package phpunit :ensure t  :after php-mode)

The Good Stuff (lsp-mode and friends)
The key bindings chosen are an odd mix of crap which I will surely change later.

Note the setting for lsp-serenata-server-path which you should change to the directory where you put the PHAR you downloaded, or if yo are not using Serenata, follow the instructions on the emacs LSP-mode page for your back end.

(use-package company :ensure t  :after php-mode  :init  :config  (setq company-idle-delay 0.3)  (push 'company-files company-backends)  (global-set-key (kbd "C- ") 'company-complete))

(use-package lsp-mode :init  (setq lsp-keymap-prefix "C-c l")  :config  (define-key lsp-mode-map (kbd "C-c l") lsp-command-map)  (setq lsp-prefer-flymake nil lsp-serenata-server-path (substitute-in-file-name "$HOME/bin/php-7.3-serenata-distribution.phar")) :hook  (php-mode. lsp) (lsp-mode. lsp-enable-which-key-integration) :commands  lsp)

(use-package company-lsp :ensure t  :after company lsp-mode  :config  (push 'company-lsp company-backends)  :commands  company-lsp)

(use-package lsp-ui :requires flycheck  :after lsp-mode  :config  (setq lsp-ui-doc-enable t  lsp-ui-doc-use-childframe t   lsp-ui-doc-position 'top lsp-ui-doc-include-signature t

lsp-ui-flycheck-enable t  lsp-ui-flycheck-list-position 'right lsp-ui-flycheck-live-reporting t

lsp-ui-imenu-enable t

lsp-ui-peek-enable t  lsp-ui-peek-list-width 60 lsp-ui-peek-peek-height 25

lsp-ui-sideline-enable t  lsp-ui-sideline-update-mode 'line lsp-ui-sideline-show-code-actions t  lsp-ui-sideline-show-hover nil)

(:map lsp-ui-mode-map	("C-c C-j". lsp-ui-peek-find-definitions)	("C-c i". lsp-ui-peek-find-implementation)	("C-c m". lsp-ui-imenu))

(lsp-mode . lsp-ui-mode))

(use-package treemacs :ensure t  :commands treemacs  :bind  (:map global-map ("M-0"      . treemacs-select-window) ("C-x t 1"  . treemacs-delete-other-windows) ("C-x t t"  . treemacs) ("C-x t B"  . treemacs-bookmark) ("C-x t C-t" . treemacs-find-file) ("C-x t M-t" . treemacs-find-tag)) :after lsp-mode)

(use-package lsp-treemacs :ensure t  :after (lsp-mode treemacs)  :commands lsp-treemacs-errors-list  :bind (:map lsp-mode-map ("C-c 9" . lsp-treemacs-errors-list)))

Cursing and stuff
When I first started this up, I didn't have treemacs in there. Serenata spent some time indexing the entire mediawiki core repo, and then proceeded to one of the vendor subdirs with PHPStorm stubs. There, it died. If it does that to you too, you should NOT agree to a restart when asked, but should exit out of emacs, restart it, and Serenata will take up where it left off. If you restart, it will start from the beginning, dying once again somewhere in the vendor dir.

When I added treemacs and created a project (coincidentally the mediawiki core repo), Serenata indexed the entire thing again, dying once again in the vendor subdir, so I went through the same don't-restart-it-or-you'll-be-sorry song and dance. Now everything seeeeeems to be indexed properly.

Tweak and enjoy

 * According to the docs there's a single location where Serenata saves its indexing; I need to look into that and see if it is per project or what.
 * I need to see whether treemacs is really necessary, how xref is used, what lsp-sideline features I might want, etc.
 * What happens when I use some other PHP project? (OK realistically I won't, but still.)
 * Treemacs to the left, hovercards in the upper right, one window for the code I'm writing/reading and a second for surfing around, is that the layout I want?
 * Do I want to run unit tests in an emacs window? Right now I don't run phan or any of that via emacs but in another terminal tab.
 * To activate treemacs I needed to type, and to active lsp-ui-imenu I needed to type  . Should I activate them automatically?
 * And the big question: emacs in the terminal, always my default until now, or emacs as a separate window??

Comments welcome
I'm just getting started with this. Today as I write this first draft, I will literally have used this setup for part of one day. Comments and suggestions are more than welcome! You now where the talk page is :-)

Please note that this draft doc is still being cleaned up. I want to also add a section with screenshots showing the whole thing in action, so people know what they would be getting with this setup.