polymorphine/cs

Development tools & coding standard scripts for Polymorphine libraries

0.4.1 2023-07-05 04:09 UTC

Requires

• php: ^7.4 || ^8.0
• friendsofphp/php-cs-fixer: 3.9.*
• phpunit/phpunit: ^9.5.21
• shudd3r/skeletons: ^1.0.0
• squizlabs/php_codesniffer: ^3.7.1

MIT

• Shudd3r

README

Development tools & coding standard scripts for Polymorphine libraries

• PHPUnit testing library.
• Combination of PHP-CS-Fixer and CodeSniffer with custom settings added as dev dependency of Polymorphine packages.
• Package skeleton scripted with Skeletons engine.

Installation with Composer

composer require --dev polymorphine/dev

PHP-CS-Fixer

PHP-CS-Fixer will automatically fix code formatting, and CodeSniffer will check style errors that need to be adjusted manually like: naming conventions, line lengths and some phpDoc constraints.

Fixer needs project scope configuration to set up factory with package name used in a file docBlock headers and absolute path to its root directory. Add cs-fixer.php.dist configuration file similar to the one supplied with this package to root directory of your project.

Use this command to run fixer for given file or directory (path):

vendor/bin/php-cs-fixer fix -v --config=cs-fixer.php.dist --using-cache=no --path-mode=intersection path

CodeSniffer

CodeSniffer tool is used only because of Fixer limitations. Not every style constraint violation can be automatically fixed, so this tool will inform you about inconsistencies that need manual fixing.

phpcs.xml file is the configuration for all projects using this package as a composer dependency (in default vendor directory). However, console command running CodeSniffer requires the absolute path to this config file. For example Github Action command may build the absolute path with $GITHUB_WORKSPACE env variable:

vendor/bin/phpcs --extensions=php --standard=$GITHUB_WORKSPACE/vendor/polymorphine/dev/phpcs.xml path

IDE Setup (PhpStorm)

PHP-CS-Fixer

Use Setting > Tools > External Tools to configure php-cs-fixer environment:

• Program: add path to vendor/bin/php-cs-fixer (for Windows: vendor/bin/php-cs-fixer.bat)
• Parameters: add command fixing currently opened project file:

  fix -v --config=cs-fixer.php.dist --using-cache=no --path-mode=intersection "$FileDir$\$FileName$"
  

  If you want to add another tool entry with checking command the command above would need additional --dry-run switch.
• Working directory: set to $ProjectFileDir$
• Add keyboard shortcuts to run commands in Settings > Keymap > External Tool

Code Sniffer

Code sniffer does not change the code by itself, so it's better to set is as one of the inspections:

• Add path to local phpcs script in Settings > Languages & Frameworks > PHP > Code Sniffer
• Set custom ruleset in Settings > Editor > Inspections > PHP Code Sniffer validation with absolute path to phpcs.xml file provided with this package - as a project dependency it will be located in vendor/polymorphine/cs/ directory, and composer's autoload script will be two levels above.

CodeSniffer custom PhpDoc requirements

• Original public method signatures require phpDoc block comments (their contents are not inspected). Original method is the one that introduces new signature - it doesn't override parent's method nor provides implementation for method defined by an interface. In case of traits every method is considered original.
• PhpDoc's @param and @return tags with callable or Closure type require additional description formatted similar to short lambda notation - example:

  /**
   * @param Closure $callback fn(Param1Type, Param2Type) => ReturnType
   *
   * @return callable fn(bool) => \FQN\Return\Type
   */