Optionally write missing Laravel Model DocBlock (#700)

* Fix missing doc-block.

* Fixes a bug where a missing DocBlock caused errors.

* Change Option Shorthand to W
Because it is not allowed to have two char shorthands for options.

* Revert code refactoring.

* Fix copied config header.

config/ide-helper.php

@@ -38,6 +38,21 @@ return array(
 
     'write_model_magic_where' => true,
 
+    /*
+    |--------------------------------------------------------------------------
+    | Write Eloquent Model Mixins
+    |--------------------------------------------------------------------------
+    |
+    | This will add the necessary DocBlock mixins to the model class
+    | contained in the Laravel Framework. This helps the IDE with
+    | auto-completion.
+    |
+    | Please be aware that this setting changes a file within the /vendor directory.
+    |
+    */
+
+    'write_eloquent_model_mixins' => false,
+
     /*
     |--------------------------------------------------------------------------
     | Helper files to include

src/Console/GeneratorCommand.php

@@ -115,6 +115,10 @@ class GeneratorCommand extends Command
 
             if ($written !== false) {
                 $this->info("A new helper file was written to $filename");
+
+                if ($this->option('write_mixins')) {
+                    Eloquent::writeEloquentModelHelper($this, $this->files);
+                }
             } else {
                 $this->error("The helper file could not be created at $filename");
             }
@@ -158,9 +162,11 @@ class GeneratorCommand extends Command
     protected function getOptions()
     {
         $format = $this->config->get('ide-helper.format');
+        $writeMixins = $this->config->get('ide-helper.write_eloquent_model_mixins');
 
         return array(
             array('format', "F", InputOption::VALUE_OPTIONAL, 'The format for the IDE Helper', $format),
+            array('write_mixins', "W", InputOption::VALUE_OPTIONAL, 'Write mixins to Laravel Model?', $writeMixins),
             array('helpers', "H", InputOption::VALUE_NONE, 'Include the helper files'),
             array('memory', "M", InputOption::VALUE_NONE, 'Use sqlite memory driver'),
             array('sublime', "S", InputOption::VALUE_NONE, 'DEPRECATED: Use different style for SublimeText CodeIntel'),

src/Eloquent.php

@@ -32,27 +32,57 @@ class Eloquent
         $reflection  = new \ReflectionClass($class);
         $namespace   = $reflection->getNamespaceName();
         $originalDoc = $reflection->getDocComment();
+
         if (!$originalDoc) {
             $command->info('Unexpected no document on ' . $class);
         }
         $phpdoc = new DocBlock($reflection, new Context($namespace));
 
         $mixins = $phpdoc->getTagsByName('mixin');
-        foreach ($mixins as $m) {
+        $expectedMixins = [
-            if ($m->getContent() === '\Eloquent') {
+            '\Eloquent'                             => false,
-                $command->info('Tag Exists: @mixin \Eloquent in ' . $class);
+            '\Illuminate\Database\Eloquent\Builder' => false,
+            '\Illuminate\Database\Query\Builder'    => false,
+        ];
 
+        foreach ($mixins as $m) {
+            $mixin = $m->getContent();
+
+            if (isset($expectedMixins[$mixin])) {
+                $command->info('Tag Exists: @mixin ' . $mixin . ' in ' . $class);
+
+                $expectedMixins[$mixin] = true;
+            }
+        }
+
+        $changed = false;
+        foreach ($expectedMixins as $expectedMixin => $present) {
+            if ($present === false) {
+                $phpdoc->appendTag(Tag::createInstance('@mixin ' . $expectedMixin, $phpdoc));
+
+                $changed = true;
+            }
+        }
+
+        // If nothing's changed, stop here.
+        if (!$changed) {
             return;
         }
-        }
-
-        // add the Eloquent mixin
-        $phpdoc->appendTag(Tag::createInstance("@mixin \\Eloquent", $phpdoc));
 
         $serializer = new DocBlockSerializer();
         $serializer->getDocComment($phpdoc);
         $docComment = $serializer->getDocComment($phpdoc);
 
+        /*
+            The new DocBlock is appended to the beginning of the class declaration.
+            Since there is no DocBlock, the declaration is used as a guide.
+        */
+        if (!$originalDoc) {
+            $originalDoc = 'abstract class Model implements';
+
+            $docComment .= "\nabstract class Model implements";
+        }
+
         $filename = $reflection->getFileName();
         if ($filename) {
             $contents = $files->get($filename);
@@ -61,7 +91,7 @@ class Eloquent
                 $contents = str_replace($originalDoc, $docComment, $contents, $count);
                 if ($count > 0) {
                     if ($files->put($filename, $contents)) {
-                        $command->info('Wrote @mixin \Eloquent to ' . $filename);
+                        $command->info('Wrote expected docblock to ' . $filename);
                     } else {
                         $command->error('File write failed to ' . $filename);
                     }