dgtlss/easyerd
Generate ERDs for Laravel apps from models and migrations. Create diagrams as PDF/PNG/SVG/JPG plus a text ERD. Configure output paths, table/relationship styling, exclusions, dark mode, and high-res Graphviz layouts via an Artisan command.
## Technical Evaluation
**Architecture Fit**
Easy ERD integrates seamlessly with Laravel by leveraging Graphviz to generate Entity-Relationship Diagrams (ERDs) directly from database schemas. This aligns well with Laravel’s database-first approach and complements tools like Laravel Scout, Eloquent, and migrations. The package abstracts the complexity of Graphviz configuration, making it ideal for teams prioritizing developer productivity and documentation clarity. However, its utility is limited to projects requiring visual schema representation rather than runtime database operations.
**Integration Feasibility**
The package is designed for Laravel (PHP 8.0+) and requires minimal setup (composer install + configuration). Integration feasibility is high for projects already using:
- Laravel’s Eloquent ORM (for schema introspection).
- Graphviz (dependency for diagram generation).
- Laravel’s service container (for dependency injection).
**Technical Risk**
- **Dependencies**: Graphviz must be installed system-wide, which may introduce deployment friction (e.g., Docker/CI environments). The package does not bundle Graphviz, requiring manual setup.
- **Performance**: Generating ERDs on-demand could impact response times in high-traffic applications if not cached or offloaded to a background job.
- **Schema Accuracy**: Diagrams reflect the *current* database state, which may diverge from migration files if not synced (e.g., during deployments). No built-in diffing or versioning is provided.
- **Customization**: Limited flexibility for non-standard schema representations (e.g., polymorphic relationships, complex many-to-many pivots).
**Key Questions**
1. **Use Case Alignment**: Is the primary value of this package for *development* (local IDE docs) or *production* (runtime schema validation)? This dictates caching strategies and deployment requirements.
2. **Graphviz Compatibility**: How will Graphviz be managed across environments (e.g., Docker, shared hosting)? Will the package support alternative diagram generators (e.g., Mermaid.js) in future versions?
3. **Scaling**: Will ERD generation be triggered by user actions (e.g., admin panel) or automated (e.g., post-deploy)? If the latter, how will concurrency be handled?
4. **Security**: Are there risks of exposing sensitive schema details (e.g., column names, foreign keys) via generated diagrams in public-facing contexts?
5. **Testing**: How will the package be tested in CI/CD pipelines? Graphviz dependency may require additional setup in test environments.
---
## Integration Approach
**Stack Fit**
- **Laravel Core**: Native support for Eloquent and database connections reduces integration overhead.
- **PHP Extensions**: Requires `php-gd` or `php-imagick` for image output (optional but recommended for web-based diagrams).
- **Frontend**: Diagrams can be embedded in Blade templates or returned as API responses (e.g., base64-encoded images or SVG). No frontend framework dependencies.
- **DevOps**: Graphviz must be installed on all deployment targets (e.g., `apt-get install graphviz` for Ubuntu). Consider containerizing the dependency or using a serverless function for generation.
**Migration Path**
1. **Evaluation Phase**:
- Install via Composer: `composer require vendor/easy-erd`.
- Test diagram generation in a staging environment with a representative database schema.
- Validate output quality for critical relationships (e.g., polymorphic, soft deletes).
2. **Production Rollout**:
- **Option A (Dev-Only)**: Restrict usage to local development via environment checks (e.g., `if (app()->environment('local'))`).
- **Option B (Runtime)**: Integrate with a scheduled job (e.g., Laravel Horizon) to regenerate diagrams post-deploy and cache results.
3. **Deprecation**: Monitor for future versions that may introduce breaking changes (e.g., Graphviz version requirements).
**Compatibility**
- **Laravel Versions**: Tested on Laravel 8.0+ (PHP 8.0+). Backward compatibility with older versions is unlikely.
- **Database Support**: Works with MySQL, PostgreSQL, SQLite, and SQL Server via Eloquent. No native support for NoSQL or non-relational schemas.
- **Caching**: No built-in caching layer; integrate with Laravel’s cache drivers (e.g., Redis) for performance.
- **Alternatives**: Consider `laravel-shift/blueprint` or `spatie/laravel-model-stats` for schema-related tools with different focuses.
**Sequencing**
1. **Pre-requisite**: Install Graphviz and PHP extensions before package installation.
2. **Configuration**: Publish and configure the package’s assets (e.g., `php artisan vendor:publish --provider="Vendor\EasyErd\EasyErdServiceProvider"`).
3. **Testing**: Verify diagrams for a subset of models before full adoption.
4. **Documentation**: Update internal docs to reflect the new ERD generation workflow (e.g., "Run `php artisan erd:generate` to update diagrams").
---
## Operational Impact
**Maintenance**
- **Package Updates**: Monitor for breaking changes in Graphviz or Laravel dependencies. The package’s simplicity reduces maintenance burden but may lack long-term roadmap visibility.
- **Schema Drift**: Diagrams become stale if migrations are applied without regeneration. Implement a post-deploy hook or CI check to regenerate diagrams.
- **Customization**: Extending the package (e.g., adding custom node styles) requires PHP template overrides, which may diverge from upstream updates.
**Support**
- **Troubleshooting**: Common issues will revolve around Graphviz installation and PHP configuration. Document these steps for onboarding.
- **Community**: Limited ecosystem; support may rely on GitHub issues or vendor responses. Consider contributing to the package’s development if critical features are missing.
- **Error Handling**: The package lacks detailed error messages for Graphviz failures (e.g., missing DOT syntax). Add custom logging for production debugging.
**Scaling**
- **Performance**: Generating large schemas (e.g., 100+ tables) may timeout or consume excessive memory. Test with production-like data volumes.
- **Concurrency**: If used in a web context, offload generation to a queue (e.g., Laravel Queues) to avoid blocking requests.
- **Storage**: Cached diagrams may grow large; implement a TTL (e.g., 24 hours) or size-based cleanup.
**Failure Modes**
| Failure Scenario | Impact | Mitigation Strategy |
|--------------------------------|---------------------------------|-----------------------------------------------|
| Graphviz not installed | Diagrams fail to generate | Add CI checks for Graphviz availability. |
| Database schema changes | Stale diagrams | Automate regeneration post-migration. |
| High-traffic diagram requests | Server timeouts | Cache results or use a queue. |
| PHP memory limits | Generation fails for large DBs | Increase `memory_limit` or optimize queries. |
| Dependency conflicts | Package incompatibility | Isolate in a dedicated Docker container. |
**Ramp-Up**
- **Developer Onboarding**:
- **Time Estimate**: 1–2 hours to install and generate first diagram.
- **Key Steps**: Install Graphviz, publish config, run `php artisan erd:generate`.
- **Training**: Create a runbook with screenshots of the generated output and common customizations.
- **Team Adoption**:
- **Incentives**: Highlight how diagrams reduce onboarding time for new developers.
- **Governance**: Define when diagrams should be regenerated (e.g., after major schema changes).
- **Tooling Integration**:
- Embed diagrams in Laravel Forge/Envoyer deploy logs or GitHub PR templates.
- Use the package’s CLI commands in custom scripts (e.g., `php artisan erd:generate --output=docs/schema.png`).
How can I help you explore Laravel packages today?