Improving code-completion for scaffolded classes

Created 6 years ago by radic

I'm currently adding docblocks myself on some classes, pretty much every time the same repetition.

Example:

If you would create a stream character. You'd end up using the Foo\BarModule\Character\Contract\CharacterRepositoryInterface when using type hinting to inject the Foo\BarModule\Character\CharacterRepository.

/**
 * Interface CharacterRepositoryInterface
 *
 * @method \Foo\BarModule\Character\Contract\CharacterInterface find(int $id)
 * @method \Foo\BarModule\Character\Contract\CharacterInterface findBy(string $column, mixed $value)
 * @method \Foo\BarModule\Character\CharacterCollection|\Foo\BarModule\Character\Contract\CharacterInterface[] findAll(int[] $ids)
 * @method \Foo\BarModule\Character\CharacterCollection|\Foo\BarModule\Character\Contract\CharacterInterface[] all()
 * @method \Foo\BarModule\Character\Contract\CharacterInterface findTrashed(int $id)
 * @method \Foo\BarModule\Character\Contract\CharacterInterface create(array $attributes)
 * 
 * intellij only, and i guess it's bad practice on interfaces for most situations.. but just as a reminder that mixin is really powerfull. I use it on some generated classes
 * @mixin \Foo\BarModule\Character\CharacterRepository
 */
interface CharacterRepositoryInterface extends EntryRepositoryInterface {}

What do you think about adding this to the stubs? maby making it an optional feature when using the command. Pretty much asking this because i was about to do such a thing for my project, but i'd rather avoid it if this idea is looked upon favourably and could be implemented (can do a PR to kick it off, if wanted)

radic — 6 years ago

some more examples

/**
 * @method \Foo\BarModule\Character\Contract\CharacterInterface findBy($key, $value)
 * @method \Foo\BarModule\Character\Contract\CharacterInterface find($key, mixed $default = null)
 * @method \Foo\BarModule\Character\Contract\CharacterInterface get($key, mixed $default = null)
 */
class CharacterCollection extends EntryCollection{}

/**
 * maby better to add to EntryCriteria??
 * @mixin \Anomaly\Streams\Platform\Entry\EntryQueryBuilder
 */
class CharacterCriteria extends EntryCriteria {}

etc

Link

ryanthompson — 6 years ago

What IDE do you use? These methods are inherited and should auto-populate already. Just the returned value is not hinted but at that point you're writing your own code and I do it like this:

/* @var CharacterInterface $character */
$character = $characters->find($id);

Which seems easy enough IMHO.

Link

radic — 6 years ago

It's indeed the return value hinting i'm talking about. Forgot to mention that. It's easy enough to make an inline annotation for sure. But it is also completely avoidable and repetitive task that (imo) doesn't make the code any more readable.

A bit of a overexaggerated example with silly logic, but something similar can occur. It's fine for 1 method, but might get annoying for multiple methods/classes.:

/** @var CharacterCollection $characters */
$characters = $repo->all();
/* @var CharacterInterface $character */
$character = $characters->find($id);
/** @var CharacterCollection $charactersToDelete */
$charactersToDelete = $repo->findAll([1,2]);
foreach($charactersToDelete as $char){
   /* @var CharacterInterface $char */
   $char->find($id);
}
/** @var CharacterCollection $charactersToBlock */
$charactersToBlock = $repo->findAll([3,4])

ps: to answer the first question i use IntelliJ/PHPStorm 😄

Link

ryanthompson — 6 years ago

Ok cool - so we both have actual IDEs lol. I get what you are saying. Honestly I wish this could be back traced into a core compiled model instead of the make:stream bit. But I definitely get where you are heading with this. Let me sit on it a bit. Perhaps spread it about the slack channels and see what others think? I'll do the same.

Link