Optimize PhpStorm for your Laravel projects
I’d like to see potential issues in my projects right away by looking at the source code. Therefore I’d like to keep all inspections “green”. Otherwise I would be prone to the “broken window theory”. If I manage to get all inspections on a file to pass, I see a lot of issues right away. The inspections of PhpStorm are being improved with every new release.
In this article, I’ll show you how you can leverage the power of the PhpStorm inspections for your Laravel projects.
So let’s take a look at an exemplary Laravel controller.
We see some warnings. They are caused by the inspections in PhpStorm. For this the IDE is building an internal model of the code using static code analysis.
You can see the colour-coded level of the worst warning in the upper right corner. This is even more helpful for classes that do not fit on a screen.
BTW: I prefer using the explicit facades over the aliases (I’m not using the explicit facade for “App” here, I will explain the reason for that later on).
If you right click on the file and select “Inspect code…” PhpStorm presents a list of the warnings.
So what can we do to get rid of these warnings?
Laravel IDE helper
Fortunately Barry van den Heuvel already built a helper to fix those issues. We can install it using composer.
Then we can generate the general helper file.
Now the IDE knows the static Log::info() method. It no longer shows a warning (inspection is now satisfied). Code completion is also working. When you ⌘ + click the method you end up in the helper, but there you can click on the non static method to see the underlying code (so navigation is supported OK-ish).
For convenience in Laravel, some non-static methods can be called statically (through so-called facades). But please only use them for cross cutting concerns. Preferably use dependency injection instead.
For the warnings regarding the Eloquent models we need to use another helper.
In order to parse the models the helper relies on the doctrine/dbal package.
Since I like to have full control over my model classes, the helper code goes into an extra file.
After generating the model helper, the IDE resolves the static method calls to models and even knows the type of returned model objects.
Meta file helper
The helper can also generate a PhpStorm meta file.
Using that file the IDE knows the type of objects created by App::make() so no inline type hints are needed. You might have to invalidate caches and restart PhpStorm for this to work.
Unfortunately it is not working when using the explicit App facade (Illuminate\Support\Facades\App), only if you use the Alias.
So… no more warnings… but notices (weak warnings)…
BTW: do not forget to add files generated by helper to .gitignore file.
But what to do about the weak warnings?
Last resort: disable some inspections
Duplicates of some classes now exist in IDE helper files. The only solution I found is to disable the explicit inspection. I guess that’s ok, because it is not severe to disable it.
After that we see no more weak warnings.
There is only a “typo” or rather an unknown word left. In our application we have a German front end, so a lot of german words in the code.
So how do we handle these?
Dictionaries for non English languages and uncommon words
To handle non-English words, I put downloaded dictionaries in a subdirectory in the project root.
You can download dictionaries from http://www.winedt.org/dict.html. You will need to convert them from UTF-16 to UTF-8 to use them in PhpStorm.
I also add uncommon words that are not in the downloaded dictionaries to a custom dictionary file.
To make PhpStorm use them, add the directory to the custom dictionary folders in the IDE settings.
After doing so the inspections are all “green”.
I suggest to keep it green so you notice new issues (even typos) right away.
So: either fix the issues or disable the rules to prevent the broken window effect. If there already is one warning, to cause the second one does not hurt.
… can we do to support Laravel features in PhpStorm?
We can install and enable the Laravel Plugin.
If you do so you get autocompletion and navigation for:
- controllers and routes
- configuration options and services
You also get syntax highlighting, code completion and navigation for blade templates.
With that you
- can navigate to extended/included templates
- get code completion for Blade directives
- PHP type hints now also allowed in Blade templates (was not possible in earlier versions)
You should also also install “.env files support” plugin for navigation and code completion for environment variables.
PhpStorm can also inspect SQL (this is of course not a “Laravel-only” topic).
To get proper support for SQL you have to configure a data source so that the IDE knows your database structure.
You also have to specify an SQL dialect (i.e. MySQL).
You of course also have autocompletion for table and column names and can navigate your data structure.
Some issues are not resolved by the plugins or the helper (i.e. in migrations).
The return types of the Blueprint methods don’t seem to be correct.
You can still suppress the inspection locally. This is not nice but does the trick.
You can find some more detailed information on some of the above topics in this JetBrains tutorial.
Some more options
There is some more stuff you can do to leverage PhpStorm to improve your development workflow and your code base:
- Mark directories as source, resource and test source roots. This makes it easier for the IDE to add the correct namespaces to generated classes, link to static files used in templates, etc.
- Add PHP Code Sniffer inspections to show violations of your coding style (i.e. PSR-2) right away.
- Add PHPMD inspections to see bad practices like overly compex code.
- Enforce rules with pre-commit hooks or detect violations on the CI server (I’d prefer the CI server approach to not torture your teammates too much).
- Use a case sensitive partition for your code base (on OSX) to prevent surprises (like GIT hickups with changed casing in file names).
I cannot repeat this often enough: Keep your code (super)green all the time either by fixing the problems causing the warning, or by disabling/suppressing the inspections (in consultation with your team). Do not allow broken windows… others will follow.