Laravel Model Doc Laravel Package

Getting Started

• Install as a dev dependency so it never ships to production:

  composer require --dev romanzipp/laravel-model-doc
  

• Make sure your app has a working database connection and migrated schema. The generator introspects real tables/columns, not migration files.
• Publish the package config if you need to change model paths, excluded models, or docblock templates:

  php artisan vendor:publish
  # select the model-doc provider/tag from the list
  

• Run the generator:

  php artisan model-doc:generate
  # or target one model if the command supports it:
  php artisan model-doc:generate --model=User
  

• Open app/Models/User.php and inspect the generated docblock. You should see @property entries for columns and @property-read entries for relations, e.g.:

  /**
   * @property int $id
   * @property string $email
   * @property-read Collection|Post[] $posts
   */
  class User extends Model {}
  

• First use case: let PhpStorm/VS Code and Larastan/PHPStan understand Eloquent attributes without manually maintaining docblocks. Run the generator after schema changes, commit the result, and keep static analysis green.

Where to look first: the published config file, php artisan model-doc:generate --help, and the diff in one small model before running it across the whole app.

Implementation Patterns

• Local schema-change loop: after php artisan migrate or a schema edit, run the generator and commit the docblock diff. Treat generated annotations like compiled artifacts: regenerate locally, review, commit.
• CI drift check: in a pipeline with a disposable database, run migrations and then the generator. Use git diff --exit-code to fail if generated docblocks are stale. If the command exposes a --check flag, prefer that.
• Selective generation: configure only your application models, or pass a model class when iterating. Avoid generating vendor/framework models; they are not yours to annotate.
• IDE Helper coexistence: barryvdh/laravel-ide-helper:models can also generate model docblocks. Pick one source of truth for @property annotations to avoid conflicting/duplicated blocks. Use model-doc for attributes/relations and IDE Helper for facades/helpers if needed.
• Static analysis workflow: generate docblocks before running PHPStan/Larastan/Psalm. This turns $user->email from mixed into string, and $user->posts into Collection<int, Post>, which materially improves analysis results.
• Relationship coverage: ensure relation methods have explicit return types:

  public function posts(): HasMany
  {
      return $this->hasMany(Post::class);
  }
  

  The generator relies on return types and relation calls. For custom keys, polymorphic relations, or hasManyThrough, verify the generated annotation and patch manually if needed.
• Team template: if the package exposes a stub/template config, standardize on your team’s docblock style (@property-read vs @property, ordering, spacing). Keep custom templates in version control, not in vendor/.
• Monorepo/modules: if you have models outside app/Models, configure multiple paths or run the command per module. Keep generated annotations close to the models they describe.
• Wrapper script: wrap the command in a Composer script so developers and CI use the same invocation:

  "scripts": {
      "model-doc": [
          "@php artisan model-doc:generate"
      ]
  }
  

Gotchas and Tips

• Database required: the generator needs a live, migrated schema. It cannot infer columns from migrations alone. In CI, use SQLite in-memory or a disposable database, but remember SQLite type mapping differs from MySQL/Postgres (json, enum, unsignedBigInteger, etc.).
• Generate against the right engine: if production is Postgres and CI uses SQLite, generated types may be less precise. Prefer generating against a schema dump or read-only replica of the production engine.
• Do not run against production: avoid writing model files in production. Run generation locally or in CI, commit the result, and deploy only the generated files.
• Manual annotations can be overwritten: the generator may replace the whole docblock. Move hand-written annotations to an interface, trait, or a separate docblock section if the tool does not merge them. Always review the diff before committing.
• Accessors and casts: appended attributes, accessors, and custom casts may not appear or may be typed generically (mixed, array). Add precise @property annotations manually for those, or extend the generator if it supports custom type mapping.
• Enums and JSON: PHP 8.1 enum casts and JSON columns often become mixed/array. Refine manually if static analysis matters.
• Relation edge cases: dynamic relations, relations defined via variables, and custom polymorphic mappings can be missed. Check generated @property-read lines for every relation and patch the exceptions.
• Config caching: after changing package config, run php artisan config:clear. Do not run config:cache before generation in CI.
• File permissions and silent failures: if the command cannot write to a model file, it may fail quietly. Run with -v and check permissions on app/Models.
• Small package risk: 32 stars and 0 dependents means limited ecosystem feedback. Pin the version in composer.json, review changelogs, and keep a wrapper script so you can swap tools later.
• Extension points: check the service provider for bindings you can override (formatters, generators, templates). If undocumented, prefer a local fork/patch over relying on internals.
• Git hygiene: commit generated docblocks in a dedicated commit or mark them as generated in .gitattributes. Use the CI drift check to keep them fresh.
• Performance: generating every model on every file save is slow because the command boots Laravel and queries the schema. Run it per model during development, or on demand before analysis/commit.