IDE Helper генератор

IDE Helper генератор

Этот пакет создает вспомогательные файлы, которые позволяют вашей среде IDE обеспечить точное автозаполнение. Генерация выполняется на основе файлов вашего проекта, поэтому они всегда актуальны.

Он поддерживает Laravel 8+ и PHP 7.3+.

Источник(github): barryvdh/laravel-ide-helper


Монтаж

Требуйте этот пакет с композитором, используя следующую команду:

composer require --dev barryvdh/laravel-ide-helper

В этом пакете используется механизм автоматического обнаружения пакетов Laravel , что означает, что если вы не установите зависимости разработки в рабочей среде, он также не будет загружен.

Если по какой-то причине вы хотите вручную управлять этим:

  • добавить пакет к extra.laravel.dont-discoverключу composer.json, например
"extra": {
  "laravel": {
    "dont-discover": [
      "barryvdh/laravel-ide-helper"
    ]
  }
}
  • Добавьте следующий класс в providersмассив в config/app.php:
Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider::class,
  • Если вы хотите вручную загружать его только в непроизводственных средах, вместо этого вы можете добавить это в свой метод AppServiceProviderс помощью register():
public function register()
{
    if ($this->app->isLocal()) {
        $this->app->register(\Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider::class);
    }
    // ...
}
Примечание. Избегайте кэширования конфигурации в вашей среде разработки, это может вызвать проблемы после установки этого пакета; соответственно очистите кеш заранее через php artisan cache:clearесли у вас возникнут проблемы при выполнении команд


Применение

Посмотрите это видео Laracasts для быстрого введения/объяснения!

Примечание. Вам нужен CodeComplice для Sublime Text: https://github.com/spectacles/CodeComplice .


Автоматическая генерация PHPDoc для фасадов Laravel

Теперь вы можете повторно сгенерировать документы самостоятельно (для будущих обновлений).

php artisan ide-helper:generate

Примечание: bootstrap/compiled.phpсначала необходимо очистить, поэтому запустите php artisan clear-compiledперед генерацией.

Это создаст файл, _ide_helper.phpкоторый, как ожидается, будет дополнительно проанализирован вашей IDE для автозаполнения. Вы можете использовать конфиг filename, чтобы изменить его имя.

Вы можете настроить composer.jsonэто каждый раз, когда вы обновляете свои зависимости:

"scripts": {
    "post-update-cmd": [
        "Illuminate\\Foundation\\ComposerScripts::postUpdate",
        "@php artisan ide-helper:generate",
        "@php artisan ide-helper:meta"
    ]
},

Вы также можете опубликовать файл конфигурации, чтобы изменить реализации (например, интерфейс для определенного класса) или установить значения по умолчанию для --helpers.

php artisan vendor:publish --provider="Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider" --tag=config

Генератор пытается определить настоящий класс, но если он не может быть найден, вы можете определить его в файле конфигурации.

Некоторым классам требуется работающее соединение с базой данных. Если у вас нет рабочего соединения по умолчанию, некоторые фасады не будут включены. Вы можете использовать драйвер SQLite в памяти, добавив -Mпараметр.

Вы можете включить вспомогательные файлы. Это не включено по умолчанию, но вы можете переопределить его с помощью --helpers (-H)опции. Он Illuminate/Support/helpers.phpуже настроен, но вы можете добавлять/удалять свои собственные файлы в файле конфигурации.


Автоматическая генерация PHPDoc для макросов и миксинов

Этот пакет может генерировать PHPDocs для макросов и миксинов, которые будут добавлены в _ide_helper.phpфайл.

Но это работает, только если вы используете подсказку типа при объявлении макроса.

Str::macro('concat', function(string $str1, string $str2) : string {
    return $str1 . $str2;
});


Автоматические PHPDocs для моделей

Если вы не хотите писать свои свойства самостоятельно, вы можете использовать команду php artisan ide-helper:modelsдля создания PHPDocs на основе столбцов таблицы, отношений и геттеров/сеттеров.

Примечание: для этой команды требуется работающее соединение с базой данных для самоанализа таблицы каждой модели.

По умолчанию вам будет предложено перезаписать или записать в отдельный файл ( _ide_helper_models.php). Вы можете написать комментарии непосредственно в файл модели, используя --write (-W)опцию, или запретить запись с помощью --nowrite (-N).

В качестве альтернативы использование этой --write-mixin (-M)опции добавит только тег миксина в файл модели, а остальное запишет в ( _ide_helper_models.php). Имя класса будет отличаться от модели, чтобы избежать раздражения IDE дублированием.

Пожалуйста, не забудьте сделать резервную копию ваших моделей, прежде чем писать информацию.

Запись в модели должна сохранять существующие комментарии и добавлять только новые свойства/методы. Существующий PHPDoc заменяется или добавляется, если не найден. С этой --reset (-R)опцией существующие PHPDocs игнорируются, и только вновь найденные столбцы/отношения сохраняются как PHPDocs.

php artisan ide-helper:models "App\Models\Post"
/**
 * App\Models\Post
 *
 * @property integer $id
 * @property integer $author_id
 * @property string $title
 * @property string $text
 * @property \Illuminate\Support\Carbon $created_at
 * @property \Illuminate\Support\Carbon $updated_at
 * @property-read \User $author
 * @property-read \Illuminate\Database\Eloquent\Collection|\Comment[] $comments
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post newModelQuery()
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post newQuery()
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post query()
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post whereTitle($value)
 * @method static \Illuminate\Database\Eloquent\Builder|\App\Models\Post forAuthors(\User ...$authors)
 * …
 */

С --write-mixin (-M)опцией

/**
 * …
 * @mixin IdeHelperPost
 */


Каталоги моделей

По умолчанию модели app/modelsсканируются. Необязательный аргумент указывает, какие модели использовать (в том числе вне приложений/моделей).

php artisan ide-helper:models "App\Models\Post" "App\Models\User"

Вы также можете сканировать другой каталог, используя --dirопцию (относительно базового пути):

php artisan ide-helper:models --dir="path/to/models" --dir="app/src/Model"

Вы можете опубликовать файл конфигурации ( php artisan vendor:publish) и установить каталоги по умолчанию.


Игнорировать модели

Модели можно игнорировать с помощью --ignore (-I)опции

php artisan ide-helper:models --ignore="App\Models\Post,App\Models\User"

Или можно игнорировать, установив в ignored_modelsконфиге

'ignored_models' => [
    App\Post::class,
    Api\User::class
],


Магические where*методы

Eloquent позволяет вызывать where<Attribute>ваши модели, например, Post::whereTitle(…)и автоматически переводит это, например, в Post::where('title', '=', '…').

Если по какой-то причине нежелательно, чтобы они генерировались (по одному для каждого столбца), вы можете отключить это через конфиг write_model_magic_whereи установить для него значение false.


Магические *_countсвойства

Вы можете использовать этот ::withCountметод для подсчета числовых результатов связи без их фактической загрузки. Затем эти результаты помещаются в атрибуты в соответствии с <columname>_countсоглашением.

По умолчанию эти атрибуты генерируются в файле phpdoc. Вы можете отключить их, установив в конфигурации write_model_relation_count_propertiesзначение false.


Общие аннотации

Laravel 9 представил аннотации дженериков в DocBlocks для коллекций. PhpStorm 2022.3 и более поздние версии поддерживают использование общих аннотаций внутри @propertyи @property-readобъявлений в DocBlocks, например, Collection<User>вместо Collection|User[].

Их можно отключить, установив в конфигурации use_generics_annotationsзначение false.


Поддержка @commentна базе DocBlock

Чтобы лучше поддерживать IDE, отношения и геттеры/сеттеры также могут добавлять комментарий к свойству, такому как столбцы таблицы. Поэтому используется пользовательский блок документов @comment:

class Users extends Model
{
    /**
     * @comment Get User's full name
     *
     * @return string
     */
    public function getFullNameAttribute(): string
    {
        return $this->first_name . ' ' .$this->last_name ;
    }
}

// => after generate models

/**
 * App\Models\Users
 * 
 * @property-read string $full_name Get User's full name
 * …
 */


Выделенные методы Eloquent Builder

В красноречивые модели был добавлен новый метод под названием newEloquentBuilder Reference , где мы можем добавить поддержку создания нового выделенного класса вместо использования локальных областей в самой модели.

Если по какой-то причине нежелательно, чтобы они генерировались (по одному для каждого столбца), вы можете отключить это через конфиг write_model_external_builder_methodsи установить для него значение false.


Неподдерживаемые или настраиваемые типы баз данных

Общие типы столбцов (например, varchar, integer) правильно отображаются на типы PHP ( stringint).

Но иногда вы можете захотеть использовать настраиваемые типы столбцов в своей базе данных, такие как geographyjsonbcitextbitи т. д., которые могут вызвать исключение «Неизвестный тип базы данных».

Для этих особых случаев вы можете сопоставить их через config custom_db_types. Пример:

'custom_db_types' => [
    'mysql' => [
        'geography' => 'array',
        'point' => 'array',
    ],
    'postgresql' => [
        'jsonb' => 'string',
        '_int4' => 'array',
    ],
],


Пользовательские типы отношений

Если вы используете отношения, не встроенные в Laravel, вам нужно будет указать имя и возвращаемый класс в конфигурации, чтобы получить правильную генерацию.

'additional_relation_types' => [
    'externalHasMany' => \My\Package\externalHasMany::class
],

Найденные отношения обычно генерируют возвращаемое значение на основе имени отношения.

Если ваши пользовательские отношения не следуют этой традиционной схеме именования, вы можете определить возвращаемый тип вручную. Доступные варианты: manyи morphTo.

'additional_relation_return_types' => [
    'externalHasMultiple' => 'many'
],


Крючки для моделей

Если вам нужна дополнительная информация о вашей модели из источников, которые не обрабатываются по умолчанию, вы можете подключиться к процессу генерации с помощью обработчиков модели, чтобы добавлять дополнительную информацию на лету. Просто создайте реализующий класс ModelHookInterfaceи добавьте его в model_hooksмассив в конфиге:

'model_hooks' => [
   MyCustomHook::class,
],

Метод runбудет вызываться во время генерации для каждой модели и получает текущий запуск ModelsCommandи текущий Model, например:

class MyCustomHook implements ModelHookInterface
{
    public function run(ModelsCommand $command, Model $model): void
    {
        if (! $model instanceof MyModel) {
            return;
        }

        $command->setProperty('custom', 'string', true, false, 'My custom property');
        $command->unsetMethod('method');
        $command->setMethod('method', $command->getMethodType($model, '\Some\Class'), ['$param']);
    }
}
/**
 * MyModel
 *
 * @property integer $id
 * @property-read string $custom


Автоматическое создание PHPDocs для методов Laravel Fluent

Если вам нужна поддержка PHPDocs для методов Fluent при миграции, например

$table->string("somestring")->nullable()->index();

После публикации поставщика просто измените include_fluentстроку в вашем config/ide-helper.phpфайле на:

'include_fluent' => true,

Затем запустите php artisan ide-helper:generate, теперь вы увидите все методы Fluent, распознаваемые вашей IDE.


Автодополнение для заводских строителей

Если вы хотите, чтобы factory()->create()методы factory()->make()и возвращали правильный класс модели, вы можете включить пользовательские сборщики фабрик с помощью include_factory_buildersстроки в вашем config/ide-helper.phpфайле. Устарело для Laravel 8 или более поздней версии.

'include_factory_builders' => true,

Чтобы это работало, вы также должны опубликовать метафайл PhpStorm (см. ниже).


PhpStorm Meta для экземпляров контейнера

Можно создать метафайл PhpStorm, чтобы добавить поддержку шаблона проектирования factory . Для Laravel это означает, что мы можем заставить PhpStorm понять, какой тип объекта мы разрешаем из контейнера IoC. Например, eventsвернет Illuminate\Events\Dispatcherобъект, поэтому с помощью метафайла вы можете вызвать app('events'), и он будет автоматически заполнять методы Dispatcher.

php artisan ide-helper:meta
app('events')->fire();
\App::make('events')->fire();

/** @var \Illuminate\Foundation\Application $app */
$app->make('events')->fire();

// When the key is not found, it uses the argument as class name
app('App\SomeClass');
// Also works with
app(App\SomeClass::class);
Примечание. Возможно, вам придется перезапустить PhpStorm и убедиться, что .phpstorm.meta.phpон проиндексирован.
Примечание. Когда вы получаете FatalException: класс не найден, проверьте свою конфигурацию (например, удалите S3 в качестве облачного драйвера, если у вас не настроен S3. Удалите Redis ServiceProvider, если вы его не используете).

Вы можете изменить сгенерированное имя файла через config meta_filename. Это может быть полезно в тех случаях, когда вы хотите воспользоваться поддержкой каталога .phpstorm.meta.php/ PhpStorm : все файлы, размещенные там, анализируются, если вы хотите предоставить дополнительные файлы для PhpStorm.


Использование с Люменом

Этот пакет ориентирован на разработку Laravel, но его также можно использовать в Lumen с некоторыми обходными путями. Поскольку Lumen работает немного по-другому, так как он похож на голую версию Laravel, а основные параметры конфигурации вместо этого расположены в bootstrap/app.php, необходимо внести некоторые изменения.


Включение фасадов

В то время как Laravel IDE Helper может автоматически генерировать фасады по умолчанию для подсказки кода, Lumen не поставляется с активированными фасадами. Если вы планируете их использовать, вы должны включить их в Create The Applicationразделе, раскомментировав эту строку:

// $app->withFacades();

Оттуда вы сможете использовать эту create_alias()функцию для добавления дополнительных фасадов в ваше приложение.


Добавление поставщика услуг

Вы можете установить Laravel IDE Helper в app/Providers/AppServiceProvider.php, и раскомментировать эту строку, которая регистрирует поставщиков услуг приложений, чтобы она могла правильно загружаться.

// $app->register(App\Providers\AppServiceProvider::class);

Если вы не используете эту строку, которая обычно удобна для изящного управления несколькими установками Laravel/Lumen, вам нужно будет добавить эту строку кода в Register Service Providersраздел вашего файла bootstrap/app.php.

if ($app->environment() !== 'production') {
    $app->register(\Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider::class);
}

После этого Laravel IDE Helper должен работать корректно. В процессе генерации скрипт может генерировать исключения, говорящие о том, что некоторые классы не существуют или существуют неопределенные индексы. Это нормально, поскольку в Lumen удалены некоторые пакеты по умолчанию, такие как Cookies, Storage и Session. Если вы планируете добавить эти пакеты, вам придется добавить их вручную и при необходимости создать дополнительные Фасады.


Добавление дополнительных фасадов

В настоящее время Lumen IDE Helper не учитывает дополнительные фасады, созданные bootstrap/app.phpс помощью create_alias(), поэтому вам нужно создать config/app.phpфайл и aliasesснова добавить свои пользовательские псевдонимы в массив, например так:

return [
    'aliases' => [
        'CustomAliasOne' => Example\Support\Facades\CustomAliasOne::class,
        'CustomAliasTwo' => Example\Support\Facades\CustomAliasTwo::class,
        //...
    ]
];

После запуска php artisan ide-helper:generateрекомендуется (но не обязательно) переименовать config/app.phpего во что-то другое, пока вам не потребуется повторно сгенерировать документы или после перехода в производственную среду. Lumen 5.1+ будет читать этот файл для параметров конфигурации, если он присутствует, и может перекрывать некоторые конфигурации, если он полностью заполнен.