Этот пакет создает вспомогательные файлы, которые позволяют вашей среде 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 для быстрого введения/объяснения!
php artisan ide-helper:generate
- Генерация PHPDoc для фасадов Laravelphp artisan ide-helper:models
- PHPDocs для моделейphp artisan ide-helper:meta
- Метафайл PhpStorm
Примечание. Вам нужен 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 ( string
, int
).
Но иногда вы можете захотеть использовать настраиваемые типы столбцов в своей базе данных, такие как geography
, jsonb
, citext
, bit
и т. д., которые могут вызвать исключение «Неизвестный тип базы данных».
Для этих особых случаев вы можете сопоставить их через 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+ будет читать этот файл для параметров конфигурации, если он присутствует, и может перекрывать некоторые конфигурации, если он полностью заполнен.