PHPDoc autocomplete for Fluent (creating a migration)

In this GitHub pull request, I was told to create a post on the forum because it was deemed a "support request" instead of a "feature request." So instead of going through the GitHub route (where the conversation can be tracked), I will post something on the forum.

The pull request argues that PHPDoc comments should be added to the Fluent class so that IDEs that support introspection will be able to provide suggestions for the magic methods when adding columns to a schema in a migrations class. Currently, whenever you create a new column through ->integer('test')->unique(), the unique() call is marked as invalid because the IDE doesn't know the method exists. On top of that, I have to refer to the Laravel documentation every time I want to create a new column instead of just letting my IDE tell me what functions are available.

I've noticed this is a common pattern in Laravel, so I thought I would try to contribute and fix it where I could. Unfortunately, I was met with criticism of my comments and the ultimate locking of the thread (even though I was asking what I thought were valid questions).

So I will ask my question again here: Where in Laravel would the inclusion of those PHPDoc comments be considered a hinderance, or where would they be inaccurate?

crynobone

10 years ago

Level 5

The problem is that you avoid to understand the simplest answer, Illuminate\Support\Fluent is not only meant for migrations.

Let's first check the usage http://packanalyst.com/class?q=Illuminate%5CSupport%5CFluent by everyone else. Most of these external packages is not even related to building schema let alone using ->integer('test')->unique().
Laravel itself use it outside of migrations:
- https://github.com/laravel/framework/blob/5.1/src/Illuminate/Support/Traits/CapsuleManagerTrait.php#L35 is used as an alternative to config when using Capsule Database (Illuminate\Database outside of Laravel app).
- https://github.com/laravel/framework/blob/5.1/src/Illuminate/Validation/Validator.php#L243 even in Validation.
It's defined under Illuminate\Support namespace, and not Illuminate\Database\Schema\FluentColumn etc. That should suggest that it's a generic class that many consider as alternative to stdClass, just as how people use Collection instead of simple array.

sammarks15

10 years ago

Level 1

Thank you for the more detailed response. You might want to consider re-opening the GitHub thread and posting that information there, because other developers who are Googling for the same problem are more likely to find that thread than this one.

I was asking for more information on where it is used to see if we could come up with a common denominator and document that instead of documenting nothing, not because I "avoid to understand the simplest answer."

Going back to the GitHub thread, the easiest way to allow for IDEs to introspect on the code is to create sub-classes for the different use-cases and document that, but creating a class purely for documentation isn't the greatest idea, so it looks like this is something better-suited for an IDE plugin than documentation in the framework itself.

I would again suggest that we include this information somehow on the GitHub PR so that other developers can find this explanation.

ryne-andal

10 years ago

Level 1

Yeah, cause only migrations would use a method such as unique(). #DocumentationIsTheDevil

Please or to participate in this conversation.