Phpinsights: [Discussion] Generating coding style document

[olivernybroe]

| Q | A
| ---------------- | -----
| Bug report? | no
| Feature request? | yes

So I have this idea of automatically generating a coding style document based on what insights you have added.

Basically it would gather all insights you have and return a website with information about each insight. This would allow companies to easily create a coding style document and at the same time keeping it up to date, as they don't have to write new sections to it, when they add something new to their coding style.

Implementation

A new interface would be added giving three new methods

• description
• badCode
• goodCode

All sniffs we use would have to be wrapped in a Insight class, where this insight class can then implement the interface to give us the needed information. Some sniffs wouldn't have to be wrapped or implement the interface, as you for example wouldn't write in your coding style that the composer file must be valid or that you shouldn't leave unused code around.

Having a class for each insight would also give us a lot more control over what we are actually checking for and could potentially give us a bunch of cool features in the future.
For example it could do so we can easily merge a sniff and a fixer together in one insight, when the fixer is fixing the issue that the sniff is reporting. It could also do so we can define what type of insight it is directly in the insight instead (so we don't by mistake add the same sniff multiple times).
Having a insight class per sniff also allows some really nice naming opportunity, as some sniffs has kinda bad naming.

@nunomaduro @Jibbarth What do you guys think? Do you feel that it would be a cool feature, or is it not something you could see yourself ever use? Does it belong in php insights?

[Jibbarth]

I really like the idea to generate a CodingStandard rules on a website.

However, maybe it a little bit "out of scope" of the package ? In my mind, it would be awesome to have something like a Wrapper around PHPInsights that could generate this.
We give it a phpinsights.php configuration in input and it generate the website.

For describing good and bad code, this wrapper can contains a "base" for main insights, but should be easily extensible, to let anyone rewrite them ?

[olivernybroe]

@Jibbarth Yeah so I also thought about writing an extension package for php insights to add this.

So my thought was that we write the standard text, but users should be able to overwrite it. Maybe in a config file, like so:

However I think in like 99% of the time, users don't really care about overwriting it, as it is just describing what we are checking for. Users should be able to supply a base text, like an introduction with company APS coding style was made because bla bla bla...

If it should be able to do it using the phpinsights.php file, then we need to open up the ConfigResolver, so we can resolve what rules are used. The package would need it's own config file, as we else have to open up the Configuration::resolveConfig method, so we can add stuff to it.

I think my idea of us starting to wrap sniffs, might still be really nice. As that would for example allow this package to be tied up to an insight, were it could change the sniff later on, without any impact. Also this would also be possible with the normal configuration file. For example there might be a bunch of sniffs, we want to replace with fixers, as some of them check the same thing, but fixers can also fix them. By wrapping each sniff/fixer in an insight class, we allow us to change that without breaking the users code.

[nunomaduro]

This would be dope.

[olivernybroe]

@nunomaduro What approach do you think is best? Doing it as a separate package or building it into phpinsights?

[nunomaduro]

I think should be a different package.

[olivernybroe]

Alright, so I generate some vuepress files and do it that way, right now the configuration looks like this

<?php

return [
    'title' => 'Php Insights generated coding style',
    'short_description' => 'Auto generated coding style by PHP Insights',
    'description' => 'Auto generated coding style by PHP Insights',
    'groups' => [
        'Generic PHP' => [
            'groups' => [
                'Functions' => [
                    'insights' => [
                        \PHP_CodeSniffer\Standards\PSR1\Sniffs\Methods\CamelCapsMethodNameSniff::class => [
                            'badCode' => /** @lang PHP */ <<<BAD_CODE
                            function my_private_method() {
                                return 'private';
                            }
                            BAD_CODE,
                            'goodCode' => /** @lang PHP */ <<<GOOD_CODE
                            function myPrivateMethod() {
                                return 'private';
                            }
                            GOOD_CODE,
                            'title' => 'Camel case naming',
                            'description' => 'When creating a method the name should always be following camel case naming.',
                        ],
                        \SlevomatCodingStandard\Sniffs\TypeHints\ReturnTypeHintSniff::class => [
                            'badCode' => /** @lang PHP */ <<<BAD_CODE
                            function myMethod() {
                                return 'works';
                            }
                            BAD_CODE,
                            'goodCode' => /** @lang PHP */ <<<GOOD_CODE
                            function myMethod(): string {
                                return 'works';
                            }
                            GOOD_CODE,
                            'title' => 'Must declare return type',
                            'description' => 'Always add return types.',
                        ],
                    ],
                ],
            ],
        ],
        'Laravel' => [
            'groups' => [
                'Functions' => [
                    'insights' => [
                        \PHP_CodeSniffer\Standards\Generic\Sniffs\PHP\ForbiddenFunctionsSniff::class => [
                            'title' => 'Disallow debug methods',
                            'description' => 'Usage of `dd`, `ddd`, `dump` and `tinker` is not allowed.',
                        ],
                    ],
                ],
            ],
        ],
    ],
];

Cases like this has to be added in for all sniffs, this is our internal configuration file. User's should then be able to have their own configuration file, where they can overwrite whatever they feel like. (they will prob. just overwrite, title, description and short_description.

The user can then just do whatever styling they would like as with any other vuepress site, or they can use our default style. A readme.md file is also present in the generated output, this is the index site, which we won't override.

[olivernybroe]

I actually have a working example in my thesis project repository.
The PR can be found here https://github.com/worksome/phpinsights-app/pull/16

This repo does not only contain stuff for generating coding style.

Closing this issue as it is out of scope for phpinsights.