Symfony Integration

The MorphQL Symfony bundle provides first-class support for MorphQL in Symfony applications, including YAML configuration, service autowiring, and a Twig-inspired query discovery system.

Installation

Install the bundle via Composer:

composer require morphql/morphql-symfony

The bundle is fully zero-config. All settings have sensible defaults — no YAML file is needed. Just install, drop a .morphql file in morphql-queries/, and start using the TransformationRegistry.

Configuration (optional)

To customize behavior, create config/packages/morphql.yaml:

morphql:
  # Execution provider: "cli" (standard) or "server" (remote)
  # provider: cli

  # Query directory (default: %kernel.project_dir%/morphql-queries)
  # query_dir: '%kernel.project_dir%/morphql-queries'

  # Server provider settings (uncomment if using provider: server)
  # server_url: '%env(MORPHQL_SERVER_URL)%'
  # api_key: '%env(MORPHQL_API_KEY)%'

The Query Directory

Like Twig templates in templates/, the Symfony bundle looks for MorphQL queries in the morphql-queries/ directory.

morphql-queries/
├── invoices/
│   └── to_xml.morphql        # ID: 'invoices/to_xml'
└── api_response.morphql      # ID: 'api_response'

Your queries automatically benefit from syntax highlighting and validation if you have the MorphQL IDE extension installed.

Usage

Using the Registry

The TransformationRegistry is the recommended way to run queries stored in files. It resolves path-based identifiers to absolute file paths automatically.

use MorphQL\SymfonyBundle\TransformationRegistry;

class InvoiceService
{
    public function __construct(
        private readonly TransformationRegistry $registry
    ) {}

    public function process(array $data): string
    {
        // Resolves to morphql-queries/invoices/to_xml.morphql
        return $this->registry->transform('invoices/to_xml', $data);
    }
}

Direct Service Usage

You can also inject the base MorphQL service for ad-hoc queries:

use MorphQL\MorphQL;

class MyController
{
    public function __construct(
        private readonly MorphQL $morphql
    ) {}

    public function run(string $query, $data): string
    {
        return $this->morphql->run($query, $data);
    }
}

Advanced Patterns

Dot Notation (Optional)

The registry supports both forward slashes and dots as separators. Both 'invoices/to_xml' and 'invoices.to_xml' resolve to the same file.

Environment-specific Config

Use Symfony parameters or environment variables for dynamic configuration:

morphql:
  provider: "%env(MORPHQL_PROVIDER)%"
  server_url: "%env(MORPHQL_SERVER_URL)%"

Troubleshooting

"node" not found

If you use a version manager like NVM, asdf, or Volta, the node binary might not be in the default PATH used by your web server or PHP process.

Solution 1: Use the Node-less QuickJS runtime

If you don't want to deal with Node.js paths, you can switch to the embedded QuickJS runtime which is self-contained and pre-bundled:

Set in .env: MORPHQL_RUNTIME=qjs

Solution 2: Set the Node path in .env

MORPHQL_NODE_PATH=/usr/local/bin/node # Use 'which node' to find yours

Solution 3: Create a system symlink

sudo ln -s $(which node) /usr/local/bin/node

Prerequisites

• PHP 8.1+
• Node.js 18+ OR QuickJS (for the cli provider)
• Symfony 5.4+, 6.x, 7.x, or 8.x