Laravel Relation Parser Laravel Package

Getting Started

• Install with Composer using a constraint that matches your Laravel version. For Laravel 13, use ^1.4:

  composer require salamwaddah/laravel-relation-parser:^1.4
  

• v1.4.0 is a compatibility release: it adds Laravel 13 support. No new parser features or breaking API changes are called out in the release notes. If you are not on Laravel 13, v1.4.0 is not urgent; stay on your current working version unless you want the latest constraint.
• Look first at:
  • the package README for the public entry point (facade, service class, or helper),
  • config/relation-parser.php if the package publishes config,
  • the package service provider for container bindings and discovery behavior,
  • the package tests for expected input/output shapes.
• First use case: run the parser against one model, such as App\Models\User::class, from php artisan tinker or a small Artisan command. Inspect the returned relation list before wiring it into anything larger. This gives you the package’s output shape and confirms it sees the relations you expect.
• After install or upgrade, run:

  php artisan package:discover
  php artisan config:clear
  

  If you cache config in production, rebuild it after deployment.

Implementation Patterns

• Single-model inspection: use the parser to list relations for one model when building admin filters, API include lists, relation dropdowns, or model detail screens. Treat the parser as metadata discovery, not as a query builder.
• Batch model inventory: build a small service or Artisan command that scans app_path('Models'), resolves model classes, and parses each one. Cache the result:

  $inventory = Cache::rememberForever('model-relations', function () {
      // loop models and call the package parser for each
  });
  

  Refresh the cache during deploy or via a dedicated command.
• Documentation and ERD generation: convert parsed relations into graph edges, then feed them into Mermaid, Graphviz, or an internal model map. This is a good day-to-day use: keep relationship docs from drifting without manually maintaining a list.
• CI drift checks: commit a generated JSON snapshot of model relations, regenerate it in CI, and fail the build if it changes. This catches accidental relation removals or renames during refactors.
• API include allow-lists: use parsed relation names to validate ?include= parameters or to build a safe list of relations that may be exposed. Still apply your own authorization and serialization rules; the parser only tells you what relations exist.
• Integration tip: bind the parser behind your own small inventory service. That keeps package calls out of controllers and makes it easy to mock or swap in tests.
• Extension pattern: if the parser misses a custom relation type or dynamic relation, keep manual overrides in your own config or inventory service rather than patching vendor code. Merge parsed results with overrides before caching.

Gotchas and Tips

• v1.4.0 is mainly a Laravel 13 compatibility update. Check composer why-not salamwaddah/laravel-relation-parser ^1.4 if Composer refuses the update; the issue is usually another package pinning Laravel or PHP.
• The parser can only report relations it can discover from model code. Relations registered at runtime with resolveRelationUsing, package-provided dynamic relations, or relations hidden behind generated code may not appear. Verify against a model that uses those patterns.
• Add return types to relation methods where possible. Untyped or unusual relation methods are more likely to be missed or misclassified by static/reflection-based discovery.
• Be careful with inherited relations, traits, and abstract base models. Confirm whether your version includes parent/trait methods or only methods declared directly on the model.
• Morph relations, custom relation classes, and relations with nonstandard naming can produce labels that are technically correct but awkward for UI. Normalize names in your own inventory layer.
• Do not call the parser in a hot request path unless results are cached. Parsing many models repeatedly is metadata work you should do at deploy time, in a command, or behind a cache.
• If the parser invokes model methods internally, keep relation methods free of side effects. Avoid relation methods that perform writes, dispatch jobs, or depend on request state.
• Clear caches after model changes and deployments. A stale relation inventory is worse than no inventory because it silently drives UI/API behavior.
• Treat parsed relations as metadata, not as a security boundary. Always enforce authorization and visibility rules separately.
• For debugging, start with one model and compare the parser output to get_class_methods() and a manual review of the model. If a relation is missing, check method visibility, return type, trait usage, and whether the method actually returns an Eloquent relation.