{"id":238,"date":"2024-11-18T22:41:15","date_gmt":"2024-11-18T22:41:15","guid":{"rendered":"https:\/\/www.mitango.app\/?p=238"},"modified":"2025-01-06T21:48:56","modified_gmt":"2025-01-06T21:48:56","slug":"you-think-phpstan-as-a-side-tool-you-missed-the-real-deal","status":"publish","type":"post","link":"https:\/\/www.mitango.app\/fr\/2024\/11\/18\/you-think-phpstan-as-a-side-tool-you-missed-the-real-deal\/","title":{"rendered":"You think PHPStan as a side tool? You missed the real\u00a0deal"},"content":{"rendered":"<div class=\"wp-block-rank-math-toc-block\" id=\"rank-math-toc\"><h2>Table of Contents<\/h2><nav><ul><li><a href=\"#share-your-mistakes\">Share your\u00a0mistakes<\/a><\/li><li><a href=\"#what-is-a-custom-rule\">What is a custom\u00a0rule<\/a><\/li><li><a href=\"#create-a-custom-rule\">Create a custom\u00a0rule<\/a><\/li><li><a href=\"#a-rule-to-prevent-var-dump\">A rule to prevent\u00a0var_dump<\/a><\/li><li><a href=\"#testing-the-rule\">Testing the\u00a0rule<\/a><\/li><li><a href=\"#create-an-extension\">Create an extension<\/a><\/li><\/ul><\/nav><\/div>\n\n\n\n<p>PHPStan is one of the base tools for a PHP developer as it helps a lot to double check types are coherent in the application.<\/p>\n\n\n\n<p>However, by using it this way you are passing aside of its key features, sharing knowledge.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"share-your-mistakes\">Share your&nbsp;mistakes<\/h3>\n\n\n\n<p>Often on a project, different developers tends to make the same mistakes when manipulating the same notions.<\/p>\n\n\n\n<p>The issue being the knowledge is not shared from one developer to another.<\/p>\n\n\n\n<p>So what is possible to prevent this? The first idea that comes to mind would be to mention it inside the documentation or using code review to share that knowledge.<\/p>\n\n\n\n<p>However, both of theses have flaws as the documentation needs to be read and the code review needs to be done by a developer with that knowledge.<\/p>\n\n\n\n<p>That is why we need another solution which would fit better the problem we have.<\/p>\n\n\n\n<p>This is where PHPStan step in offering us custom rules.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"what-is-a-custom-rule\">What is a custom&nbsp;rule<\/h3>\n\n\n\n<p>A rule is some class that contains the logic necessary to decide if PHPStan reports an error.<\/p>\n\n\n\n<p>Due to that a PHPStan rule will have have access to the code analyzed under the form of a tree called the AST, Abstract Syntax Tree, to facilitate the navigation.<\/p>\n\n\n\n<p>To help us even more PHPStan will provide us only with the type of node that interest us.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"create-a-custom-rule\">Create a custom&nbsp;rule<\/h3>\n\n\n\n<p>Any custom rule needs to implement the following interface, \\PHPStan\\Rules\\Rule&nbsp;.<\/p>\n\n\n\n<p>This interface has two methods:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>getNodeType<\/code> which is here to let you pick the node type the rule will be executed on. To get the list of all node types available a list is provided on <a href=\"https:\/\/phpstan.org\/developing-extensions\/rules#choosing-the-right-ast-node\" target=\"_blank\" rel=\"noreferrer noopener nofollow\">PHPStan documentation<\/a>.<\/li>\n\n\n\n<li><code>processNode<\/code> which contains the main logic that will return potential errors.<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"a-rule-to-prevent-var-dump\">A rule to prevent&nbsp;var_dump<\/h3>\n\n\n\n<p>Now that we understood the base setup a custom rule, it is now time for an example.<\/p>\n\n\n\n<p>For that we will create a rule that detect if the function <code>var_dump<\/code> is used and if it the case display an error message.<\/p>\n\n\n\n<p>For that we will have to attach our rule to the <code>\\PhpParser\\Node\\Expr\\FuncCall<\/code> node type the following way:<\/p>\n\n\n\n<pre class=\"wp-block-code is-style-light\"><code> public function getNodeType(): string<br> {<br>     return \\PhpParser\\Node\\Expr\\FuncCall::class;<br> }<\/code><\/pre>\n\n\n\n<p>Next it is time to write the main logic to raise the error.<\/p>\n\n\n\n<p>For this we will be using the name from the current node and compare it to <code>var_dump<\/code>&nbsp;.<\/p>\n\n\n\n<p>If it is the case then the error message will be returned:<\/p>\n\n\n\n<pre class=\"wp-block-code is-style-light\"><code>public function processNode( Node $node, Scope $scope ): array {<br>  $name = (string) $node-&gt;name;<br>  if( 'var_dump' !== $name ) {<br>     return &#91;];<br>  }<br>  return &#91;<br>   RuleErrorBuilder::message(<br>    'var_dump function is not allowed'<br>   )<br>   -&gt;identifier('varDumpForbidden')<br>   -&gt;build(),<br>  ];<br>}<\/code><\/pre>\n\n\n\n<p>That way our rule will finally look like that:<\/p>\n\n\n\n<pre class=\"wp-block-code is-style-light\"><code><br>use PhpParser\\Node;<br>use PHPStan\\Analyser\\Scope;<br>use PHPStan\\Rules\\Rule;<br>use PHPStan\\Rules\\RuleErrorBuilder;<br><br>class VarDumpRule implements Rule {<br> public function getNodeType(): string<br> {<br>     return \\PhpParser\\Node\\Expr\\FuncCall::class;<br> }<br><br> public function processNode( Node $node, Scope $scope ): array {<br>  $name = (string) $node-&gt;name;<br>  if( 'var_dump' !== $name ) {<br>     return &#91;];<br>  }<br>  return &#91;<br>   RuleErrorBuilder::message(<br>    'var_dump function is not allowed'<br>   )<br>   -&gt;identifier('varDumpForbidden')<br>   -&gt;build(),<br>  ];<br>}<br>}<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"testing-the-rule\">Testing the&nbsp;rule<\/h3>\n\n\n\n<p>Now that we added the logic inside the custom rule we now need to test it works correctly.<\/p>\n\n\n\n<p>For that we will have to write some automated tests.<\/p>\n\n\n\n<p>PHPStan rules tests are based on code template that will be analyzed with the rule and a match between error raised from that analysis with what was expected.<\/p>\n\n\n\n<p>To create a testcase for a PHPStan rule it needs to extend PHPStan\\Testing\\RuleTestCase:<\/p>\n\n\n\n<pre class=\"wp-block-code is-style-light\"><code>use PHPStan\\Testing\\RuleTestCase;<br><br>class VarDumpRuleTest extends RuleTestCase {<br><br>}<\/code><\/pre>\n\n\n\n<p>This testcase always needs to implement the method getRule to return the instance of the tested rule:<\/p>\n\n\n\n<pre class=\"wp-block-code is-style-light\"><code>  protected function getRule(): Rule {<br>  return new VarDumpRule();<br> }<\/code><\/pre>\n\n\n\n<p>To create a test a new method should be created starting with the word test.<\/p>\n\n\n\n<p>In our example we will have two cases:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>A function <code>var_dump<\/code> is present inside the file.<\/li>\n\n\n\n<li>No function <code>var_dump<\/code> is present inside the file.<\/li>\n<\/ul>\n\n\n\n<p>For the first case, we will have to write the following method:<\/p>\n\n\n\n<pre class=\"wp-block-code is-style-light\"><code>public function testMethodPresentShouldRaiseError() {<br> <br>}<\/code><\/pre>\n\n\n\n<p>Once this is done we will create a template file with the following content:<\/p>\n\n\n\n<pre class=\"wp-block-code is-style-light\"><code>function test ($var_dump) {<br>  var_dump(1000);<br>}<\/code><\/pre>\n\n\n\n<p>Then we gonna link both of theses file using the <code>analyse<\/code>method inside the test:<\/p>\n\n\n\n<pre class=\"wp-block-code is-style-light\"><code>public function testMethodPresentShouldRaiseError() {<br> $this-&gt;analyse(&#91;__DIR__ . '\/..\/data\/present.php'], &#91;<br>   &#91;<br>    'var_dump function is not allowed',<br>    2,<br>   ],<br> ]);<br>}<\/code><\/pre>\n\n\n\n<p>The first parameter we pass to the <code>analyse<\/code> method is the list of paths from files to analyse and the second is the list of error expected to be raised with the following syntax:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Message from the error.<\/li>\n\n\n\n<li>Line from the error.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"use-the-custom-rule\">Use the custom&nbsp;rule<\/h2>\n\n\n\n<p>Creating a rule is only useful if it is used.<\/p>\n\n\n\n<p>This is why inside this part we will see how to use it.<\/p>\n\n\n\n<p>For that there are two options.<\/p>\n\n\n\n<p>Using it inside the same project or creating a PHPStan extension.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\" id=\"register-a-rule\">Register a&nbsp;rule<\/h4>\n\n\n\n<p>To use a rule in the same project then it needs to be added to the PHPStan configuration from the project.<\/p>\n\n\n\n<p>For that it is possible to use the <code>rules<\/code> key:<\/p>\n\n\n\n<pre class=\"wp-block-code is-style-light\"><code>rules:<br>   - VarDumpRule<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"create-an-extension\">Create an extension<\/h3>\n\n\n\n<p>The second way of using a custom rule is to create a PHPStan library.<\/p>\n\n\n\n<p>For that we need to create first a composer project with the following command <code>composer init<\/code> and make the wiring between the namespace and the <code>src<\/code> folder.<\/p>\n\n\n\n<p>Then the rule <code>VarDumpRule<\/code> should be moved to the <code>src<\/code> folder.<\/p>\n\n\n\n<p>Finally we need to create a configuration file <code>extension.nano<\/code> for the extension:<\/p>\n\n\n\n<pre class=\"wp-block-code is-style-light\"><code>rules:<br>   - VarDumpRule <\/code><\/pre>","protected":false},"excerpt":{"rendered":"<p>PHPStan is one of the base tools for a PHP developer as it helps a lot to double check types are coherent in the application.<\/p>\n<p>However, by using it this way you are passing aside of its key features, sharing knowledge.<\/p>","protected":false},"author":1,"featured_media":239,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":false,"jetpack_social_options":{"image_generator_settings":{"template":"highway","enabled":false},"version":2}},"categories":[35],"tags":[52,19,15],"class_list":["post-238","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-coding","tag-beginners-guide","tag-php","tag-programming"],"jetpack_publicize_connections":[],"acf":[],"_links":{"self":[{"href":"https:\/\/www.mitango.app\/fr\/wp-json\/wp\/v2\/posts\/238","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.mitango.app\/fr\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.mitango.app\/fr\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.mitango.app\/fr\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.mitango.app\/fr\/wp-json\/wp\/v2\/comments?post=238"}],"version-history":[{"count":2,"href":"https:\/\/www.mitango.app\/fr\/wp-json\/wp\/v2\/posts\/238\/revisions"}],"predecessor-version":[{"id":401,"href":"https:\/\/www.mitango.app\/fr\/wp-json\/wp\/v2\/posts\/238\/revisions\/401"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.mitango.app\/fr\/wp-json\/wp\/v2\/media\/239"}],"wp:attachment":[{"href":"https:\/\/www.mitango.app\/fr\/wp-json\/wp\/v2\/media?parent=238"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.mitango.app\/fr\/wp-json\/wp\/v2\/categories?post=238"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.mitango.app\/fr\/wp-json\/wp\/v2\/tags?post=238"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}