Skip to content

Commit 6b7cb5d

Browse files
jasonmccrearyjasonmccreary
committed
Generate PHPDoc based on configuration
1 parent 0956e01 commit 6b7cb5d

File tree

15 files changed

+208
-38
lines changed

15 files changed

+208
-38
lines changed

‎config/blueprint.php‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,4 +44,16 @@
4444
*/
4545
'app_path' => app_path(),
4646

47-
];
47+
/*
48+
|--------------------------------------------------------------------------
49+
| Generate PHPDocs
50+
|--------------------------------------------------------------------------
51+
|
52+
| Here you may enable generate PHPDocs for classes like Models. This
53+
| not only serves as documentation, but also allows your IDE to
54+
| map to the dynamic properties used by Laravel Models.
55+
|
56+
*/
57+
'generate_phpdocs' => false,
58+
59+
];

‎src/Generators/ModelGenerator.php‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,12 +56,31 @@ protected function populateStub(string $stub, Model $model)
5656

5757
private function buildClassPhpDoc(Model $model)
5858
{
59-
$phpDoc = '/**' . PHP_EOL;
59+
if (!config('blueprint.generate_phpdocs')) {
60+
return '';
61+
}
62+
63+
$phpDoc = PHP_EOL;
64+
$phpDoc .= '/**';
65+
$phpDoc .= PHP_EOL;
6066
/** @var Column $column */
6167
foreach ($model->columns() as $column) {
6268
$phpDoc .= sprintf(' * @property %s $%s', $this->phpDataType($column->dataType()), $column->name());
6369
$phpDoc .= PHP_EOL;
6470
}
71+
72+
if ($model->usesSoftDeletes()) {
73+
$phpDoc .= ' * @property \Carbon\Carbon $deleted_at';
74+
$phpDoc .= PHP_EOL;
75+
}
76+
77+
if ($model->usesTimestamps()) {
78+
$phpDoc .= ' * @property \Carbon\Carbon $created_at';
79+
$phpDoc .= PHP_EOL;
80+
$phpDoc .= ' * @property \Carbon\Carbon $updated_at';
81+
$phpDoc .= PHP_EOL;
82+
}
83+
6584
$phpDoc .= ' */';
6685

6786
return $phpDoc;

‎stubs/model/class.stub‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
namespace DummyNamespace;
44

55
use Illuminate\Database\Eloquent\Model;
6-
76
/** DummyPHPDocClass **/
87
class DummyClass extends Model
98
{

‎tests/Feature/Generator/ModelGeneratorTest.php‎

Lines changed: 50 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ protected function setUp(): void
3030
/**
3131
* @test
3232
*/
33-
public function output_writes_nothing_for_empty_tree()
33+
public function output_generates_nothing_for_empty_tree()
3434
{
3535
$this->files->expects('stub')
3636
->with('model/class.stub')
@@ -45,7 +45,7 @@ public function output_writes_nothing_for_empty_tree()
4545
* @test
4646
* @dataProvider modelTreeDataProvider
4747
*/
48-
public function output_writes_migration_for_model_tree($definition, $path, $model)
48+
public function output_generates_models($definition, $path, $model)
4949
{
5050
$this->files->expects('stub')
5151
->with('model/class.stub')
@@ -112,6 +112,45 @@ public function output_respects_configuration()
112112
$this->assertEquals(['created' => ['src/path/Models/Comment.php']], $this->subject->output($tree));
113113
}
114114

115+
/**
116+
* @test
117+
* @dataProvider docBlockModelsDataProvider
118+
*/
119+
public function output_generates_phpdoc_for_model($definition, $path, $model)
120+
{
121+
$this->app['config']->set('blueprint.generate_phpdocs', true);
122+
123+
$this->files->expects('stub')
124+
->with('model/class.stub')
125+
->andReturn(file_get_contents('stubs/model/class.stub'));
126+
127+
$this->files->expects('stub')
128+
->with('model/fillable.stub')
129+
->andReturn(file_get_contents('stubs/model/fillable.stub'));
130+
131+
$this->files->expects('stub')
132+
->with('model/casts.stub')
133+
->andReturn(file_get_contents('stubs/model/casts.stub'));
134+
135+
if ($definition === 'definitions/readme-example.bp') {
136+
$this->files->expects('stub')
137+
->with('model/dates.stub')
138+
->andReturn(file_get_contents('stubs/model/dates.stub'));
139+
}
140+
141+
$this->files->shouldReceive('stub')
142+
->with('model/method.stub')
143+
->andReturn(file_get_contents('stubs/model/method.stub'));
144+
145+
$this->files->expects('put')
146+
->with($path, $this->fixture($model));
147+
148+
$tokens = $this->blueprint->parse($this->fixture($definition));
149+
$tree = $this->blueprint->analyze($tokens);
150+
151+
$this->assertEquals(['created' => [$path]], $this->subject->output($tree));
152+
}
153+
115154
public function modelTreeDataProvider()
116155
{
117156
return [
@@ -123,4 +162,13 @@ public function modelTreeDataProvider()
123162
['definitions/nested-components.bp', 'app/Admin/User.php', 'models/nested-components.php'],
124163
];
125164
}
165+
166+
public function docBlockModelsDataProvider()
167+
{
168+
return [
169+
['definitions/readme-example.bp', 'app/Post.php', 'models/readme-example-phpdoc.php'],
170+
['definitions/soft-deletes.bp', 'app/Comment.php', 'models/soft-deletes-phpdoc.php'],
171+
['definitions/disable-auto-columns.bp', 'app/State.php', 'models/disable-auto-columns-phpdoc.php'],
172+
];
173+
}
126174
}

‎tests/fixtures/definitions/disable-auto-columns.bp‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
models:
2+
State:
3+
name: string
4+
code: string
5+
timestamps: false

‎tests/fixtures/models/comment.php‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,6 @@
55
use Illuminate\Database\Eloquent\Model;
66
use Illuminate\Database\Eloquent\SoftDeletes;
77

8-
/**
9-
* @property integer $id
10-
*/
118
class Comment extends Model
129
{
1310
use SoftDeletes;

‎tests/fixtures/models/disable-auto-columns-phpdoc.php‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<?php
2+
3+
namespace App;
4+
5+
use Illuminate\Database\Eloquent\Model;
6+
7+
/**
8+
* @property int $id
9+
* @property string $name
10+
* @property string $code
11+
*/
12+
class State extends Model
13+
{
14+
/**
15+
* The attributes that are mass assignable.
16+
*
17+
* @var array
18+
*/
19+
protected $fillable = [
20+
'name',
21+
'code',
22+
];
23+
24+
/**
25+
* The attributes that should be cast to native types.
26+
*
27+
* @var array
28+
*/
29+
protected $casts = [
30+
'id' => 'integer',
31+
];
32+
}

‎tests/fixtures/models/model-configured.php‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,6 @@
44

55
use Illuminate\Database\Eloquent\Model;
66

7-
/**
8-
* @property integer $id
9-
* @property integer $post_id
10-
* @property integer $author_id
11-
*/
127
class Comment extends Model
138
{
149
/**

‎tests/fixtures/models/nested-components.php‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,6 @@
44

55
use Illuminate\Database\Eloquent\Model;
66

7-
/**
8-
* @property integer $id
9-
* @property string $name
10-
*/
117
class User extends Model
128
{
139
/**

‎tests/fixtures/models/readme-example-phpdoc.php‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
<?php
2+
3+
namespace App;
4+
5+
use Illuminate\Database\Eloquent\Model;
6+
7+
/**
8+
* @property int $id
9+
* @property string $title
10+
* @property string $content
11+
* @property \Carbon\Carbon $published_at
12+
* @property \Carbon\Carbon $created_at
13+
* @property \Carbon\Carbon $updated_at
14+
*/
15+
class Post extends Model
16+
{
17+
/**
18+
* The attributes that are mass assignable.
19+
*
20+
* @var array
21+
*/
22+
protected $fillable = [
23+
'title',
24+
'content',
25+
'published_at',
26+
];
27+
28+
/**
29+
* The attributes that should be cast to native types.
30+
*
31+
* @var array
32+
*/
33+
protected $casts = [
34+
'id' => 'integer',
35+
];
36+
37+
/**
38+
* The attributes that should be mutated to dates.
39+
*
40+
* @var array
41+
*/
42+
protected $dates = [
43+
'published_at',
44+
];
45+
}

0 commit comments

Comments
 (0)