Problem/Motivation

The connections can only be viewed on the report page. Site builders, developers and auditors often need them outside of Drupal: in project documentation, in audit or migration spreadsheets, or rendered as a large diagram.

Proposed resolution

Add three export formats:

  • Mermaid (.mmd): a flowchart LR diagram that renders directly in GitLab, GitHub, Confluence and other Markdown tools.
  • DOT (.dot): for Graphviz, to render large graphs to PNG, SVG or PDF.
  • CSV (.csv): one row per connection (source entity type, bundle and label; field name and label; cardinality; target entity type, bundle and label).

Unlike the graph, exports list every field separately, even when several fields connect the same two bundles.

Available from:

  • Download links on the report page, served by /admin/reports/entity-connections/entities/export/{format} with the same permission as the report.
  • A Drush command: drush entity-connections:export --format=mermaid|dot|csv (alias ec-export), writing to standard output.

Implementation:

  • New entity_connections.report service which collects and sorts the connections. It is shared by the table view, the downloads and Drush.
  • New entity_connections.exporter service with one method per format.
  • Labels are escaped for Mermaid and DOT. CSV values starting with =, +, - or @ are protected against formula injection.
  • Tests: Unit tests for the formats (escaping, CSV injection, empty site), Kernel tests for the report service and the Drush command, Functional tests for the download route (headers, access, unknown format).

Remaining tasks

  • Implement, review, document in the README.

User interface changes

Download links (Mermaid, DOT, CSV) on the report page.

API changes

New services entity_connections.report and entity_connections.exporter, a new route and a Drush command. No changes to existing APIs.

Data model changes

None.

Issue fork entity_connections-3625494

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

bsztreha created an issue. See original summary.

bsztreha opened merge request !5

bsztreha’s picture

bsztreha commented

Update: pluggable export formats

Before this is released, the export gets a plugin system, so other modules can add their own formats. This is done in this issue, not in a follow-up.

  • New #[ExportFormat] plugin attribute and ExportFormatInterface / ExportFormatBase, managed by plugin.manager.entity_connections.export_format.
  • Mermaid, DOT and CSV are now plugins in src/Plugin/EntityConnections/ExportFormat. Their output is unchanged.
  • Formats receive a read-only ConnectionGraph value object with helpers for labels, colors and node keys.
  • hook_entity_connections_export_format_info_alter() can remove or reorder formats. It is documented in entity_connections.api.php, with an example JSON format.
  • The download menu, the export route and drush entity-connections:export all use the plugin manager. An unknown format gives a 404, or in Drush the list of available formats.
  • Plugin IDs and extensions are validated after the alter hook ([a-z0-9_] and [a-z0-9]), so an invalid definition fails at cache rebuild with a clear message instead of breaking the report page.
  • Only text/* formats are sent with charset=utf-8. Mermaid colors are validated, and connection endpoints that are missing from the nodes are added to the graph.

A test module provides an extra format and removes one with the alter hook, to prove the extension point works end to end in unit, kernel and functional tests.

bsztreha’s picture

bsztreha commented
Status: Active » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

  • bsztreha committed fc800604 on 1.0.x 
    Issue #3625494 by bsztreha: Export the connections as Mermaid, DOT and...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.