mirror of
https://github.com/barryvdh/laravel-ide-helper.git
synced 2026-08-17 17:47:13 +00:00
Improve readme in certain areas (#980)
* readme: sublime command has been removed Was removed in https://github.com/barryvdh/laravel-ide-helper/pull/976 as it was already deprecated for 7 years. * readme: old link only redirects, use the destination link directly * readme: mention that the default _ide_helper.php name can be changed * readme: document `meta_filename` and hint it can be written into a special subdirectory * readme: remove hint about \Eloquent or `@mixin`, as the latter is automatically added nowadays * readme: update how the current phpdoc looks like * readme: document `write_model_magic_where` * readme: document `write_model_relation_count_properties` * readme: document `custom_db_types` * readme: clarify installation regarding auto-discovery vs. manual * readme: mention to avoid caching the config in dev Inspired by https://github.com/barryvdh/laravel-ide-helper/issues/832
This commit is contained in:
Markus Podar
@@ -31,26 +31,35 @@ Require this package with composer using the following command:
|
||||
composer require --dev barryvdh/laravel-ide-helper
|
||||
```
|
||||
|
||||
If you are using Laravel versions older than 5.5, add the service provider to the `providers` array in `config/app.php`:
|
||||
This package makes use of [Laravels package auto-discovery mechanism](https://medium.com/@taylorotwell/package-auto-discovery-in-laravel-5-5-ea9e3ab20518), which means if you don't install dev dependencies in production, it also won't be loaded.
|
||||
|
||||
```php
|
||||
Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider::class,
|
||||
```
|
||||
|
||||
In Laravel, instead of adding the service provider in the `config/app.php` file,
|
||||
you can add the following code to your `app/Providers/AppServiceProvider.php` file, within the `register()` method:
|
||||
|
||||
```php
|
||||
public function register()
|
||||
{
|
||||
if ($this->app->environment() !== 'production') {
|
||||
$this->app->register(\Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider::class);
|
||||
If for some reason you want manually control this:
|
||||
- add the package to the `extra.laravel.dont-discover` key in `composer.json`, e.g.
|
||||
```json
|
||||
"extra": {
|
||||
"laravel": {
|
||||
"dont-discover": [
|
||||
"barryvdh/laravel-ide-helper",
|
||||
]
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
- Add the following class to the `providers` array in `config/app.php`:
|
||||
```php
|
||||
Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider::class,
|
||||
```
|
||||
If you want to manually load it only in non-production environments, instead you can add this to your `AppServiceProvider` with the `register()` method:
|
||||
```php
|
||||
public function register()
|
||||
{
|
||||
if ($this->app->environment() !== 'production') {
|
||||
$this->app->register(\Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider::class);
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
This will allow your application to load the Laravel IDE Helper on non-production environments.
|
||||
> Note: Avoid caching the configuration in your development environment, it may cause issues after installing this package; respectively clear the cache beforehand via `php artisan cache:clear` if you encounter problems when running the commands
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -73,6 +82,8 @@ php artisan ide-helper:generate
|
||||
|
||||
Note: `bootstrap/compiled.php` has to be cleared first, so run `php artisan clear-compiled` before generating.
|
||||
|
||||
This will generate the file `_ide_helper.php` which is expected to be additionally parsed by your IDE for autocomplete. You can use the config `filename` to change its name.
|
||||
|
||||
You can configure your `composer.json` to do this each time you update your dependencies:
|
||||
|
||||
```js
|
||||
@@ -85,7 +96,7 @@ You can configure your `composer.json` to do this each time you update your depe
|
||||
},
|
||||
```
|
||||
|
||||
You can also publish the config file to change implementations (ie. interface to specific class) or set defaults for `--helpers` or `--sublime`.
|
||||
You can also publish the config file to change implementations (ie. interface to specific class) or set defaults for `--helpers`.
|
||||
|
||||
```bash
|
||||
php artisan vendor:publish --provider="Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider" --tag=config
|
||||
@@ -104,6 +115,8 @@ The `Illuminate/Support/helpers.php` is already set up, but you can add/remove y
|
||||
If you don't want to write your properties yourself, you can use the command `php artisan ide-helper:models` to generate
|
||||
PHPDocs, based on table columns, relations and getters/setters.
|
||||
|
||||
> Note: this command requires a working database connection to introspect the table of each model
|
||||
|
||||
By default, you are asked to overwrite or write to a separate file (`_ide_helper_models.php`).
|
||||
You can write the comments directly to your Model file, using the `--write (-W)` option, or
|
||||
force to not write with `--nowrite (-N)`.
|
||||
@@ -120,7 +133,7 @@ php artisan ide-helper:models Post
|
||||
|
||||
```php
|
||||
/**
|
||||
* An Eloquent Model: 'Post'
|
||||
* App\Models\Post
|
||||
*
|
||||
* @property integer $id
|
||||
* @property integer $author_id
|
||||
@@ -130,6 +143,11 @@ php artisan ide-helper:models Post
|
||||
* @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)
|
||||
* …
|
||||
*/
|
||||
```
|
||||
|
||||
@@ -164,14 +182,38 @@ Or can be ignored by setting the `ignored_models` config
|
||||
|
||||
> Note: With namespaces, wrap your model name in double-quotes (`"`): `php artisan ide-helper:models "API\User"`, or escape the slashes (`Api\\User`).
|
||||
|
||||
For properly recognition of `Model` methods (i.e. `paginate`, `findOrFail`) you should extend `\Eloquent` or add
|
||||
#### Magic `where*` methods
|
||||
|
||||
Eloquent allows calling `where<Attribute>` on your modes, e.g. `Post::whereTitle(…)` and automatically translates this to e.g. `Post::where('title', '=', '…')`.
|
||||
|
||||
If for some reason it's undesired to have them generated (one for each column), you can disable this via config `write_model_magic_where` and setting it to `false`.
|
||||
|
||||
#### Magic `*_count` properties
|
||||
|
||||
You may use the [`::withCount`](https://laravel.com/docs/master/eloquent-relationships#counting-related-models) method to count the number results from a relationship without actually loading them. Those results are then placed in attributes following the `<columname>_count` convention.
|
||||
|
||||
By default, these attributes are generated in the phpdoc. You can turn them off by setting the config `write_model_relation_count_properties` to `false`.
|
||||
|
||||
#### Unsupported or custom database types
|
||||
|
||||
Common column types (e.g. varchar, integer) are correctly mapped to PHP types (`string`, `int`).
|
||||
|
||||
But sometimes you may want to use custom column types in your database like `geography`, `jsonb`, `citext`, `bit`, etc. which may throw an "Unknown database type"-Exception.
|
||||
|
||||
For those special cases, you can map them via the config `custom_db_types`. Example:
|
||||
```php
|
||||
/** @mixin \Eloquent */
|
||||
'custom_db_types' => [
|
||||
'mysql' => [
|
||||
'geography' => 'array',
|
||||
'point' => 'array',
|
||||
],
|
||||
'postgresql' => [
|
||||
'jsonb' => 'string',
|
||||
'_int4' => 'array',
|
||||
],
|
||||
],
|
||||
```
|
||||
|
||||
for your model class.
|
||||
|
||||
### Automatic PHPDocs generation for Laravel Fluent methods
|
||||
|
||||
If you need PHPDocs support for Fluent methods in migration, for example
|
||||
@@ -201,7 +243,7 @@ For this to work, you must also publish the PhpStorm Meta file (see below).
|
||||
|
||||
## PhpStorm Meta for Container instances
|
||||
|
||||
It's possible to generate a PhpStorm meta file to [add support for factory design pattern](https://confluence.jetbrains.com/display/PhpStorm/PhpStorm+Advanced+Metadata).
|
||||
It's possible to generate a PhpStorm meta file to [add support for factory design pattern](https://www.jetbrains.com/help/phpstorm/ide-advanced-metadata.html).
|
||||
For Laravel, this means we can make PhpStorm understand what kind of object we are resolving from the IoC Container.
|
||||
For example, `events` will return an `Illuminate\Events\Dispatcher` object,
|
||||
so with the meta file you can call `app('events')` and it will autocomplete the Dispatcher methods.
|
||||
@@ -219,12 +261,17 @@ $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);
|
||||
```
|
||||
|
||||
> Note: You might need to restart PhpStorm and make sure `.phpstorm.meta.php` is indexed.
|
||||
>
|
||||
> Note: When you receive a FatalException: class not found, check your config
|
||||
> (for example, remove S3 as cloud driver when you don't have S3 configured. Remove Redis ServiceProvider when you don't use it).
|
||||
|
||||
You can change the generated filename via the config `meta_filename`. This can be useful for cases you want to take advantage the PhpStorm also supports the _directory_ `.phpstorm.meta.php/` which would parse any file places there, should your want provide additional files to PhpStorm.
|
||||
|
||||
## Usage with Lumen
|
||||
|
||||
This package is focused on Laravel development, but it can also be used in Lumen with some workarounds.
|
||||
|
||||
@@ -14,6 +14,16 @@ return array(
|
||||
'filename' => '_ide_helper',
|
||||
'format' => 'php',
|
||||
|
||||
/*
|
||||
|--------------------------------------------------------------------------
|
||||
| Where to write the PhpStorm specific meta file
|
||||
|--------------------------------------------------------------------------
|
||||
|
|
||||
| PhpStorm also supports the directory `.phpstorm.meta.php/` with arbitrary
|
||||
| files in it, should you need additional files for your project; e.g.
|
||||
| `.phpstorm.meta.php/laravel_ide_Helper.php'.
|
||||
|
|
||||
*/
|
||||
'meta_filename' => '.phpstorm.meta.php',
|
||||
|
||||
/*
|
||||
|
||||
Reference in New Issue
Block a user