Make package more friendly to extending and overriding

[gbespyatykh]

There is no way to add custom phpdoc directives or plain text to generated docblocks. Any existed class-level comments are erased and replaced by generated dockblock after running the command.

I propose to implement the following features:

1. Ability to override lists of applied renderers and amenders in models command. It can be done: via package config; changing visibility of corresponding methods; customizeable container bindings

2. Entity methods that allow to add custom comments before or after the generated dockblocks which can be used in resolvers

[bastien-phi]

Hi @gbespyatykh

Can you provide an example of what you would like to be able to add and how it should be rendered in the docblock ?

[gbespyatykh]

@bastien-phi, hi!

Any text or docblock tags:

/**
 * Comment that will not be overwritten after docblock generation
 *  
 * @author John Doe
 * @package Foo Bar
 * @deprecated since 1.0.0
 * @api 
 * @see https://github.com/Soyhuce/next-ide-helper/discussions/70 for more info (eg)
 * ....
 * 
 * @generated content next...
 */
class SomeModel {}

Now, I use temporary hardcoded solution to keep comments. Ugly and quick implemented

/**
 * Full copy of this packages' command, that contains overrides for almost all private methods
 */
class NextIdeHelperModelsCommand extends ModelsCommand
{
    protected $name = 'next-ide-helper:models';


    // ...

    private function renderers(Model $model): array
    {
        return [
            $this->extendModelDocBlock($model),
            $this->extendQueryBuilderDocBlock($model),
        ];
    }
    private function extendModelDocBlock(Model $model): Renderer
    {
        return new class ($model) extends ModelDocBlock
        {
            use IdeHelperTempMixin;
        };
    }

    private function extendQueryBuilderDocBlock(Model $model): Renderer
    {
        return new class ($model) extends QueryBuilderDocBlock
        {
            use IdeHelperTempMixin;
        };
    }
}

/**
 * Keep any comments before @generated tag. Add it before generated comments
 */
trait IdeHelperTempMixin
{
    protected function replacePreviousBlock(string $docBlock, string $fqcn, string $file): void
    {
        $start = '/**';
        $directive = PHP_EOL . ' * @generated';

        $content = File::get($file);
        $previousDocBlock = $this->previousDocBlock($fqcn);

        if (Str::contains($previousDocBlock, $directive)) {
            $custom = Str::between($previousDocBlock, $start, $directive);
            $docBlock = Str::replaceFirst($start, $start . $custom . $directive, $docBlock);
        } else {
            $docBlock = Str::replaceFirst($start, $start . $directive, $docBlock);
        }

        $class = Str::afterLast($fqcn, '\\');

        $updatedContent = str_replace(
            "{$previousDocBlock}class {$class}",
            "{$docBlock}class {$class}",
            $content
        );

        File::put($file, $updatedContent);
    }

    private function previousDocBlock(string $fqcn): string
    {
        $docBlock = (new ReflectionClass($fqcn))->getDocComment();

        if ($docBlock === false) {
            return '';
        }

        return $docBlock . PHP_EOL;
    }
}

[bastien-phi]

I like the idea of having a @generated directive to mark begining of generated docblock. Would it fit your need ?

[bastien-phi]

Done via #74

[gbespyatykh]

I believe that you package is more clean and promising solution than barryvdh/laravel-ide-helper, but it needs more flexibility now

[bastien-phi]

Barry's ide helper is great and offers more flexibility. This package will stay quite opinionated in order to keep it simple. I think it will never be as configurable as the original one but if few adjustments make it more usable for other people, let's go for it !

[gbespyatykh]

Another example.

I use dedicated traits for relations. It deduplicates the code and provides correct type inference for completion of builder-related methods (using hacky suppression tag). And there is no need to generate _ide_models.php globally. So i need ability to exclude relations from generated docs for properties in models

class FoundationDetail extends AbstractModel
{
    use BelongsToFoundation;

    // ...
}

<?php

namespace App\Relations;

use App\Models\Foundation\Foundation;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

/**
 * @property-read \App\Models\Foundation\Foundation $foundation
 * @mixin \App\Lib\Database\AbstractModel
 */
trait BelongsToFoundation
{
    /**
     * @noinspection PhpDocSignatureInspection
     * @return \Illuminate\Database\Eloquent\Relations\BelongsTo|\App\Builders\Foundation\FoundationBuilder
     */
    public function foundation(): BelongsTo
    {
        return $this->belongsTo(Foundation::class, 'foundation_id', 'id');
    }
}

[bastien-phi]

What about using config models.overrides ?

For example

'models' => [
    'overrides' => [
        FoundationDetail::class => [
            'foundation' => false,
        ]
    ]
]

Not yet implemented but shouldn't be too difficult
What do you think about it ?

[bastien-phi]

@gbespyatykh Can you try #73 and tell me if it fits your need ?