Allow writing directly to models

Load the original docblock and append the changes. This way, you can
just copy the new comments in whole (next step, replace in file..)

composer.json

@@ -1,6 +1,8 @@
 {
     "name": "barryvdh/laravel-ide-helper",
     "description": "Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.",
+    "keywords": ["laravel", "autocomplete", "phpstorm", "netbeans", "sublime", "codeintel", "phpdoc"],
+    "license": "MIT",
     "authors": [
         {
             "name": "Barry vd. Heuvel",
@@ -12,7 +14,7 @@
         "illuminate/support": "4.0.x",
         "illuminate/console": "4.0.x",
         "illuminate/filesystem": "4.0.x",
-        "phpdocumentor/reflection-docblock": "2.0.*",
+        "phpdocumentor/reflection-docblock": "dev-master#6d705c1a0f9e2a6d73d2e9ec0e538b9dfaf4315f",
         "symfony/class-loader": "2.3.*"
     },
     "autoload": {

readme.md

@@ -1,4 +1,4 @@
-## Laravel IDE Helper & Generator
+## Laravel IDE Helper Generator
 
 ### Complete phpDocs, directly from the source
 
@@ -11,7 +11,7 @@ Add the helper file to your laravel folder (not in a public folder). The file is
 
 Require this package in your composer.json:
 
-    "barryvdh/laravel-ide-helper": "dev-master"
+    "barryvdh/laravel-ide-helper": "1.*"
 
 And add the ServiceProvider to the providers array in app/config/app.php
 
@@ -52,18 +52,23 @@ The Illuminate/Support/helpers.php is already set-up, but you can add/remove you
 ### Work in progress: Model docs
 
 If you don't want to write your properties yourself, you can use the (experimental) command `ide-helper:models` to generate
-phpDocs, based on table columns, relations and getters/setters. Very alpha, so please provide feedback if you want.
-Docs are written to a phpfile in the root of the project, so you can move the docs to the real model.
+phpDocs, based on table columns, relations and getters/setters. Still in beta, so please provide feedback if you want.
+Docs are written to a phpfile (_ide_helper_models.php) in the root of the project, so you can move the docs to the real model.
 
-For now, only models in app/models are scanned. The optional argument tells what models to use.
+You can now also write the comments directly to your Model file, using the -W argument. Please make sure to backup your models, before writing the info.
+It should keep the existing comments and only append new properties/methods.
+
+For now, only models in app/models are scanned. The optional argument tells what models to use (also outside app/models).
 `php artisan ide-helper:models Post,User`
 
 Note: With namespaces, uses \\ instead of \
 `php artisan ide-helper:models API\\User`
 
 This creates a file with the phpDocs for each Model. You should check and change them to be more accurate.
-It doesn't know if datetimes are returned as string or DateTime/Carbon, but I assume they are.
 Also, all relations are Eloquent|Eloquent[] by default, you can change them to the actual Model.
 After copying the phpdocs to your model, you can clear the file, so your IDE only uses the real source.
 
 
+### License
+
+The Laravel IDE Helper Generator is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT)

src/Barryvdh/LaravelIdeHelper/GeneratorCommand.php

@@ -1,9 +1,22 @@
-<?php namespace Barryvdh\LaravelIdeHelper;
+<?php
+/**
+ * Laravel IDE Helper Generator
+ *
+ * @author    Barry vd. Heuvel <[email protected]>
+ * @copyright 2013 Barry vd. Heuvel / Fruitcake Studio (http://www.fruitcakestudio.nl)
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      https://github.com/barryvdh/laravel-ide-helper
+ */
+
+namespace Barryvdh\LaravelIdeHelper;
 use Illuminate\Console\Command;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Input\InputArgument;
-use DocBlock\Parser;
 use Illuminate\Foundation\AliasLoader;
+use phpDocumentor\Reflection\DocBlock;
+use phpDocumentor\Reflection\DocBlock\Context;
+use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\DocBlock\Serializer as DocBlockSerializer;
 /**
  * A command to generate autocomplete information for your IDE
  *
@@ -25,6 +38,12 @@ class GeneratorCommand extends Command {
      */
     protected $description = 'Generate a new IDE Helper file.';
 
+    protected $extra;
+    protected $nonstatic;
+    protected $onlyExtend;
+    protected $helpers;
+    protected $sublime;
+
 
     /**
      * Execute the console command.
@@ -39,19 +58,19 @@ class GeneratorCommand extends Command {
             $this->useMemoryDriver();
         }
 
-        $extra = \Config::get('laravel-ide-helper::extra');
-        $nonstatic = \Config::get('laravel-ide-helper::nonstatic');
-        $onlyExtend = \Config::get('laravel-ide-helper::only_extend');
+        $this->extra = \Config::get('laravel-ide-helper::extra');
+        $this->nonstatic = \Config::get('laravel-ide-helper::nonstatic');
+        $this->onlyExtend = \Config::get('laravel-ide-helper::only_extend');
 
         if( $this->option('helpers') || (\Config::get('laravel-ide-helper::include_helpers') && ! $this->option('nohelpers'))){
-            $helpers = \Config::get('laravel-ide-helper::helper_files');
+            $this->helpers = \Config::get('laravel-ide-helper::helper_files');
         }else{
-            $helpers = array();
+            $this->helpers = array();
         }
 
-        $sublime = $this->option('sublime') || \Config::get('laravel-ide-helper::sublime');
+        $this->sublime = $this->option('sublime') || \Config::get('laravel-ide-helper::sublime');
 
-        $content = $this->generateDocs($extra, $nonstatic, $onlyExtend, $helpers, $sublime);
+        $content = $this->generateDocs();
 
         $written = \File::put($filename, $content);
 
@@ -99,14 +118,11 @@ class GeneratorCommand extends Command {
     }
 
     /**
-     * @param array $extra
-     * @param array $nonstatic
-     * @param array $onlyExtend
-     * @param array $helpers
-     * @param bool $sublime
+     * Generate the docs for all facades in the AliasLoader
+     *
      * @return string
      */
-    protected function generateDocs($extra = array(), $nonstatic = array(), $onlyExtend = array(), $helpers = array(), $sublime = false){
+    protected function generateDocs(){
 
         $aliasLoader = AliasLoader::getInstance();
 
@@ -155,7 +171,7 @@ namespace {\n\tdie('Only to be used as an helper for your IDE');\n}\n\n";
 
                 $output .= "namespace $namespace {\n";
 
-                if($root !== $facade or in_array($alias, $onlyExtend)){
+                if($root !== $facade or in_array($alias, $this->onlyExtend)){
                     //If the root class is not the same as the facade extend it.
                     $output .= " class $alias extends $facade{\n";
                 }else{
@@ -163,11 +179,11 @@ namespace {\n\tdie('Only to be used as an helper for your IDE');\n}\n\n";
                 }
                 $output .= "\t/**\n\t * @var \\$root \$root\n\t */\n\t static private \$root;\n\n";
 
-                if(!in_array($alias, $onlyExtend))
+                if(!in_array($alias, $this->onlyExtend))
                 {
                     $usedMethods = array();
-                    if(array_key_exists($alias, $nonstatic) ){
-                        $nonstaticMethods = $nonstatic[$alias];
+                    if(array_key_exists($alias, $this->nonstatic) ){
+                        $nonstaticMethods = $this->nonstatic[$alias];
                     }else{
                         $nonstaticMethods = array();
                     }
@@ -180,15 +196,15 @@ namespace {\n\tdie('Only to be used as an helper for your IDE');\n}\n\n";
                         {
                             if(!in_array($method->name, $usedMethods)){
                                 $static = !in_array($method->name, $nonstaticMethods);
-                                $output .= $this->parseMethod($method, $alias, $root, $sublime, $static);
+                                $output .= $this->parseMethod($method, $alias, $root, $static);
                                 $usedMethods[] = $method->name;
                             }
                         }
                     }
 
-                    if(array_key_exists($alias, $extra)){
+                    if(array_key_exists($alias, $this->extra)){
                         $i = 2;
-                        foreach($extra[$alias] as $extraClass){
+                        foreach($this->extra[$alias] as $extraClass){
                             if(!class_exists($extraClass) && !interface_exists($extraClass)){
                                 continue;
                             }
@@ -203,7 +219,7 @@ namespace {\n\tdie('Only to be used as an helper for your IDE');\n}\n\n";
                                 {
                                     if(!in_array($method->name, $usedMethods)){
                                         $static = !in_array($method->name, $nonstaticMethods);
-                                        $output .= $this->parseMethod($method, $alias, $extraClass, $sublime, $static, $rootParam);
+                                        $output .= $this->parseMethod($method, $alias, $extraClass, $static, $rootParam);
                                         $usedMethods[] = $method->name;
                                     }
 
@@ -236,33 +252,30 @@ namespace {\n\tdie('Only to be used as an helper for your IDE');\n}\n\n";
      * @param \ReflectionMethod $method
      * @param string $alias
      * @param string $root
-     * @param bool $sublime
      * @param bool $static
      * @param string $rootParam
      * @return string
      */
-    protected function parseMethod($method, $alias, $root, $sublime, $static = true, $rootParam = 'root'){
+    protected function parseMethod($method, $alias, $root, $static = true, $rootParam = 'root'){
         $output = '';
         if($method->name === '__clone'){
             return $output;
         }
 
-        $phpdoc = new \phpDocumentor\Reflection\DocBlock($method);
+        $namespace = $method->getDeclaringClass()->getNamespaceName();
+
+        $phpdoc = new DocBlock($method, new Context($namespace));
+        $serializer = new DocBlockSerializer(1, "\t");
+
+        $description = $phpdoc->getText();
 
-        $description = $phpdoc->getShortDescription();
-        $longDescription = $phpdoc->getLongDescription()->getContents();
-        if($longDescription){
-            $description .= "\n".$longDescription;
-        }
         if(strpos($description, '{@inheritdoc}') !== false){
             $inheritdoc = $this->getInheritDoc($method);
-            $inheritDescription = $inheritdoc->getShortDescription();
+            $inheritDescription = $inheritdoc->getText();
 
-            $inheritLongDescription = $inheritdoc->getLongDescription()->getContents();
-            if($inheritLongDescription){
-                $inheritDescription .= "\n".$inheritLongDescription;
-            }
             $description = str_replace('{@inheritdoc}', $inheritDescription, $description);
+            $phpdoc->setText($description);
+
             $inheritTags = $inheritdoc->getTags();
             if($inheritTags){
                 foreach($inheritTags as $tag){
@@ -271,46 +284,44 @@ namespace {\n\tdie('Only to be used as an helper for your IDE');\n}\n\n";
                 }
             }
         }
-        $description = str_replace("\n", "\n\t * ", $description);
-        $output .= "\t/**\n\t * ".$description."\n";
-        $output .= "\t *\n\t * @static\n";
 
+        $phpdoc->appendTag(Tag::createInstance('@static', $phpdoc));
+
+        //Looping through the parameters and re-setting the type, to get the expanded type (with namespace)
+        //Should be fixed in a future version of ReflectionDocBlock I hope..
         $paramTags = $phpdoc->getTagsByName('param');
-        if(!empty($paramTags)){
-            foreach ($paramTags as $tag)
-            {
-                $output .="\t * @param\t".$tag->getType()."\t".$tag->getVariableName()."\t".$tag->getDescription()."\n";
+        if($paramTags){
+            /** @var  $tag */
+            foreach($paramTags as $tag){
+                $content = $tag->getContent();
+                //Closure should be \Closure..
+                $content = str_replace('\Closure', 'Closure', $content);
+                $content = str_replace('Closure', '\Closure', $content);
+                $tag->setContent($content);
+                $tag->setContent($tag->getType() . ' ' . $tag->getVariableName() . ' ' . $tag->getDescription());
             }
         }
 
         $returnTags = $phpdoc->getTagsByName('return');
         if($returnTags){
+            /** @var  $tag */
             $tag = reset($returnTags);
             $returnValue = $tag->getType();
 
-            if(!$sublime and $alias == 'Eloquent' and
+            if(!$this->sublime and $alias == 'Eloquent' and
                 (in_array($method->name, array('pluck', 'first', 'fill', 'newInstance', 'newFromBuilder', 'create', 'find', 'findOrFail'))
                     or $returnValue === '\Illuminate\Database\Query\Builder')){
                 //Reference the calling class, to provide more accurate auto-complete
                 $returnValue = "static";
-            }elseif(!$sublime and $alias == 'Eloquent' and in_array($method->name, array('all', 'get'))){
-                $returnValue .= "|Eloquent[]|static[]";
+            }elseif(!$this->sublime and $alias == 'Eloquent' and in_array($method->name, array('all', 'get'))){
+                $returnValue .= "|\Eloquent[]|static[]";
             }
-            $output .= "\t * @return\t".$returnValue."\t".$tag->getDescription()."\n";
+           $tag->setContent($returnValue . " ". $tag->getDescription());
         }else{
             $returnValue = null;
         }
 
-        $allTags = $phpdoc->getTags();
-        if($allTags){
-            foreach($allTags as $tag){
-                if(!in_array($tag->getName(), array('return', 'param'))){
-                    $output .= "\t * @".$tag->getName() ." ". $tag->getContent()."\n";
-                }
-            }
-        }
-
-        $output .= "\t */\n\t public ".($static ? 'static' : '')." function ".$method->name."(";
+        $output .= $serializer->getDocComment($phpdoc) ."\n\t public ".($static ? 'static' : '')." function ".$method->name."(";
 
         $params = array();
         $paramsWithDefault = array();
@@ -337,9 +348,9 @@ namespace {\n\tdie('Only to be used as an helper for your IDE');\n}\n\n";
         $output .= implode($paramsWithDefault, ", ");
         $output .= "){\r\n";
 
-        $return = $returnValue !== "void" ? 'return' : '';
+        $return = ($returnValue && $returnValue !== "void") ? 'return' : '';
 
-        if($sublime){
+        if($this->sublime){
             $output .= "\t\t\$$rootParam = new $root();\r\n";
             $output .=  "\t\t$return \$$rootParam->";
         }else{
@@ -364,8 +375,8 @@ namespace {\n\tdie('Only to be used as an helper for your IDE');\n}\n\n";
             $method = $reflectionMethod->getPrototype();
         }
         if($method){
-            $phpdoc = new \phpDocumentor\Reflection\DocBlock($method);
-            if(strpos($phpdoc->getShortDescription(), '{@inheritdoc}') !== false || strpos($phpdoc->getLongDescription(), '{@inheritdoc}') !== false ){
+            $phpdoc = new DocBlock($method);
+            if(strpos($phpdoc->getText(), '{@inheritdoc}') !== false ){
                 //Not at the end yet, try another parent/interface..
                 return $this->getInheritDoc($method);
             }else{

src/Barryvdh/LaravelIdeHelper/IdeHelperServiceProvider.php

@@ -1,4 +1,14 @@
-<?php namespace Barryvdh\LaravelIdeHelper;
+<?php
+/**
+ * Laravel IDE Helper Generator
+ *
+ * @author    Barry vd. Heuvel <[email protected]>
+ * @copyright 2013 Barry vd. Heuvel / Fruitcake Studio (http://www.fruitcakestudio.nl)
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      https://github.com/barryvdh/laravel-ide-helper
+ */
+
+namespace Barryvdh\LaravelIdeHelper;
 
 use Illuminate\Support\ServiceProvider;
 

src/Barryvdh/LaravelIdeHelper/ModelsCommand.php

@@ -1,8 +1,22 @@
-<?php namespace Barryvdh\LaravelIdeHelper;
+<?php
+/**
+ * Laravel IDE Helper Generator
+ *
+ * @author    Barry vd. Heuvel <[email protected]>
+ * @copyright 2013 Barry vd. Heuvel / Fruitcake Studio (http://www.fruitcakestudio.nl)
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      https://github.com/barryvdh/laravel-ide-helper
+ */
+
+namespace Barryvdh\LaravelIdeHelper;
 use Illuminate\Console\Command;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\ClassLoader\ClassMapGenerator;
+use phpDocumentor\Reflection\DocBlock;
+use phpDocumentor\Reflection\DocBlock\Context;
+use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\DocBlock\Serializer as DocBlockSerializer;
 /**
  * A command to generate autocomplete information for your IDE
  *
@@ -27,6 +41,9 @@ class ModelsCommand extends Command {
     protected $properties = array();
     protected $methods = array();
 
+    protected $write = false;
+
+
 
     /**
      * Execute the console command.
@@ -36,18 +53,22 @@ class ModelsCommand extends Command {
     public function fire()
     {
         $filename = $this->option('filename');
+        $this->write = $this->option('write');
         $model = $this->argument('model');
 
         $content = $this->generateDocs($model);
 
-        $written = \File::put($filename, $content);
-
-        if($written !== false){
-            $this->info("Model information was written to $filename");
-        }else{
-            $this->error("Failed to write model information to $filename");
+        if(!$this->write){
+            $written = \File::put($filename, $content);
+            if($written !== false){
+                $this->info("Model information was written to $filename");
+            }else{
+                $this->error("Failed to write model information to $filename");
+            }
         }
 
+
+
     }
 
 
@@ -73,6 +94,7 @@ class ModelsCommand extends Command {
     {
         return array(
             array('filename', 'F', InputOption::VALUE_OPTIONAL, 'The path to the helper file', '_ide_helper_models.php'),
+            array('write', 'W', InputOption::VALUE_NONE, 'Write to Model file'),
         );
     }
 
@@ -126,17 +148,23 @@ class ModelsCommand extends Command {
         return $models;
     }
 
+    /**
+     * Load the properties from the database table.
+     *
+     * @param \Illuminate\Database\Eloquent\Model $model
+     */
     protected function getPropertiesFromTable($model){
         $table = $model->getTable();
         $schema = $model->getConnection()->getDoctrineSchemaManager($table);
+        $schema->getDatabasePlatform()->registerDoctrineTypeMapping('enum', 'string');
 
         $columns = $schema->listTableColumns($table);
 
-        $properties = array();
         if($columns){
             foreach ($columns as $column) {
                 $name = $column->getName();
                 $type =  $column->getType()->getName();
+
                 switch($type){
                     case 'string':
                     case 'text':
@@ -170,6 +198,9 @@ class ModelsCommand extends Command {
         }
     }
 
+    /**
+     * @param \Illuminate\Database\Eloquent\Model $model
+     */
     protected function getPropertiesFromMethods($model){
         $methods = get_class_methods($model);
         if($methods){
@@ -232,6 +263,12 @@ class ModelsCommand extends Command {
         }
     }
 
+    /**
+     * @param string $name
+     * @param string|null $type
+     * @param bool|null $read
+     * @param bool|null $write
+     */
     protected function setProperty($name, $type = null, $read = null, $write = null){
         if(!isset($this->properties[$name])){
             $this->properties[$name] = array();
@@ -260,18 +297,37 @@ class ModelsCommand extends Command {
         }
     }
 
+    /**
+     * @param string $class
+     * @return string
+     */
     protected function createPhpDocs($class){
 
-        if(strpos($class, '\\') !== false){
-            $parts = explode('\\', $class);
-            $class = array_pop($parts);
-            $namespace = implode($parts, '\\');
-        }else{
-            $namespace = '';
+        $reflection = new \ReflectionClass($class);
+        $namespace = $reflection->getNamespaceName();
+        $originalDoc = $reflection->getDocComment();
+        $phpdoc = new DocBlock($reflection, new Context($namespace));
+
+        if(!$phpdoc->getText()){
+            $phpdoc->setText("Generated properties for $class");
         }
-        $output = "namespace $namespace{\n";
-        $output .= "\t/**\n\t *\n\t * Generated properties for $class\n\t *\n";
+
+        $properties = array();
+        $methods = array();
+        foreach($phpdoc->getTags() as $tag){
+            $name = $tag->getName();
+            if($name == "property" || $name == "property-read" || $name == "property-write"){
+                $properties[] =$tag->getVariableName();
+            }elseif($name == "method"){
+                $methods[] = $tag->getMethodName();
+            }
+        }
+
         foreach($this->properties as $name => $property){
+            $name = "\$$name";
+            if(in_array($name, $properties)){
+                continue;
+            }
             if($property['read'] && $property['write']){
                 $attr = 'property';
             }elseif($property['write']){
@@ -279,16 +335,43 @@ class ModelsCommand extends Command {
             }else{
                 $attr = 'property-read';
             }
-            $type = $property['type'];
-            $output .= "\t * @$attr $type \$$name \n";
+            $tag = Tag::createInstance("@{$attr} {$property['type']} {$name}", $phpdoc);
+            $phpdoc->appendTag($tag);
         }
 
         foreach($this->methods as $name => $method){
-            $type = $method['type'];
-            $output .= "\t * @method $type $name() \n";
+            if(in_array($name, $methods)){
+                continue;
+            }
+            $name = "$name()";
+            $tag = Tag::createInstance("@method {$method['type']} {$name}", $phpdoc);
+            $phpdoc->appendTag($tag);
         }
 
-        $output .= "\t *\n\t */\n\tclass $class {}\n}\n\n";
+        $serializer = new DocBlockSerializer();
+        $serializer->getDocComment($phpdoc);
+        $docComment = $serializer->getDocComment($phpdoc);
+
+
+        if($this->write){
+            $filename = $reflection->getFileName();
+            $contents = \File::get($filename);
+            if($originalDoc){
+                $contents = str_replace($originalDoc, $docComment, $contents);
+            }else{
+                $needle = "class {$class}";
+                $replace = "{$docComment}\nclass {$class}";
+                $pos = strpos($contents,$needle);
+                if ($pos !== false) {
+                    $contents = substr_replace($contents,$replace,$pos,strlen($needle));
+                }
+            }
+            if(\File::put($filename, $contents)){
+                $this->info('Written new phpDocBlock to '.$filename);
+            }
+        }
+
+        $output = "namespace {$namespace}{\n{$docComment}\n\tclass {$class} {}\n}\n\n";
         return $output;
     }