How to use Php CS Fixer as a local dependency in your Php projects

Disclaimer: this tutorial assumes that you have Composer installed. If you don't, click here to get started.

In this tutorial, we are going to learn how to install Php CS Fixer as a local dependency and have different configurations for different projects on our computer. In JavaScript userland, local dependencies are preferred over global dependencies except in very rare cases and I think this should be the same in Php userland.

To start, uninstall Php CS fixer if you have it installed globally. composer global remove friendsofphp/php-cs-fixer will do that easily. Skip this step if you don't have Php CS Fixer installed. By uninstalling Php CS Fixer globally, you would have to install it in every project you want to use it in. One of the advantages of this is that you can have different versions of the tool in different projects without conflict. Another advantage is that Project A and Project B can use different style guides or fixes without conflict.

Next, head over to Php CS Configurator. It’s a cool tool to generate a .php_cs config file for the fixes you want Php CS Fixer to apply to your .php files. It comes with a demo of each fix to describe what the fix does and its possible options. The base config I use for my personal projects is located here and tweaked depending on the framework I'm working with.

After configuring to your heart's content, download the generated .php-cs file and place it in the root of the project you want the fixes applied to. Then go ahead and install PHP CS Fixer in the said project using composer require friendsofphp/php-cs-fixer --dev. Note that Php CS Fixer should always be installed as a development dependency as it is not needed in production.

PhpStorm users should read, read the following guidelines while VS Code users should skip to the next paragraph.

1. Launch PhpStorm and open Settings. Go to Tools > External tools. Click on the + button or press Ctrl + N (Windows) or Cmd + N (Mac) to create a new external tool. You should see a dialog screen like the image below.
   

2. Give the tool a name and description that will be easily memorable to you.

3. Fill the program input with the following text $ProjectFileDir$\vendor\bin\php-cs-fixer.bat. $ProjectFileDir$ is a PhpStorm macro that instructs PhpStorm to use the project directory of the currently opened file. In essence, we are telling PhpStorm to always look for the php-cs-fixer executable in the vendor/bin folder of the currently opened project.

4. Fill the argument input with the following text fix –verbose --config=$ProjectFileDir$\.php_cs --path-mode=intersection "$FileDir$/$FileName$". We see two new macros. $FileDir$/$FileName$ which together provide the filepath of the file to be fixed. The config directive tells php-cs-fixer where to look for the configuration file it will use as its ruleset. This current setting tells PhpStorm to look for a .php_cs file in the root of the project we have open.

5. Fill the working directory input with $ProjectFileDir$.

6. If you want PhpStorm’s console to open each time you run this tool, keep the Open console for tool output checkbox checked. If not, uncheck it. To see a list of all PhpStorm macros and their description, click any of the Insert Macros button in the dialog box.

7. Click OK to complete the setup.

8. Head over to Keymapin the Settings dialog. Search for the name you gave the external tool you just created. Double click on it and you should see an options popup. Click on Add Keyboard Shortcut then type a key combo (I use Alt+F) and click OK. Click OK again to close the Settings dialog.

9. Open a .php file and test run the external tool you just created using the keyboard shortcut configured for it. Notice any changes in the file?

VS Code users should follow the guidelines below

1. Install the php cs fixer extension. By default, the extension installs PHP CS Fixer in its directory located at its $extensionPath. On Windows, this is C:\Users\yourUserName\.vscode\extensions\junstyle.php-cs-fixer-{version}. According to the docs, $extensionPath is the absolute file path of the directory containing an extension.

2. If for whatever reason you don't want to use the php-cs-fixer downloaded by the extension, but the one installed locally in your project, you can change the php-cs-fixer.executablePath setting to ${workspaceRoot}\\vendor\\bin\\php-cs-fixer.bat. Even though VS Code has deprecated ${workspaceRoot} for the ${workspaceFolder} variable name as documented here, the variable still works with the extension.

3. The extension will automatically pick up the .php_cs file located in the root of your project courtesy its php-cs-fixer.config which is set to .php_cs by default.

4. Open a .php file, open the VS Code command palette using F1. Use the command php-cs-fixer: fix this file to fix your file. If the extension is not working, open VS Code developer tools via Help > Toggle Developer Tools. Click on Console to see what the error is and troubleshoot.

If you experience any challenges, let me know in the comments. If you find this helpful, also drop a like, reaction or comment. Enjoy!