Qiq Templates Support Plugin

Qiq Templates Support is an IntelliJ-based plugin that brings syntax highlighting, navigation, PHP injection, and other IDE niceties to Qiq templates. It targets JetBrains IDEs that can host the PhpStorm platform (PhpStorm, IntelliJ Ultimate with PHP plugin, etc.).

Features

• Syntax highlighting for Qiq control structures, escape modifiers ({{= }}, {{h }}, etc.), and HTML blocks.
• PHP language injection inside Qiq tokens and inline <?php ?> islands so that autocompletion, inspections, and formatting work as expected.
• Type-aware escape directives: {{h }}, {{a }}, {{j }}, {{u }}, {{c }} are routed through typed runtime stubs so PhpStorm flags wrong argument types ({{h $array }}, {{h $objectWithoutToString }}, etc.).
• Composer-aware stub selection: the strict (Qiq 1.x) or relaxed (Qiq 2.x / 3.x) escape signature is chosen automatically from composer.lock.
• Cross-template rename refactoring: renaming a PHP property, method, or local variable propagates into every Qiq template that references it. Triggering Shift+F6 from inside a Qiq template ({{h $article->title }}) also works.
• Cross-template navigation: Cmd/Ctrl+click (Go to Declaration) on setLayout(), render(), include(), or custom helpers to open the referenced template file.
• Enter/typing handlers that auto-complete Qiq block closers and keep indentation consistent.
• Template discovery: resolves relative paths by walking up from the current file, project roots, and PHP server document roots.

Settings

Open Settings (Preferences) → Languages & Frameworks → Qiq Templates for project-level options:

• Inject declare(strict_types=1) into Qiq templates (off by default) — when enabled, scalar literal misuses such as {{h true }}, {{h 123 }}, or {{h null }} surface as PhpStorm type warnings. Useful when your project renders templates under PHP strict types; off by default to match Qiq's runtime, which performs implicit scalar→string casts.

Installation

The project uses Gradle with the JetBrains IntelliJ Platform Plugin tooling.

Build a distributable ZIP

./gradlew buildPlugin

The packaged plugin will be at build/distributions/QiqTemplateSupport-<version>.zip.

Run in a sandbox IDE

./gradlew runIde

This downloads the specified PhpStorm platform, installs the plugin into a sandbox, and launches the IDE for manual testing.

Development

Prerequisites

• JDK 21+
• Gradle (wrapper included)
• A JetBrains IDE for Kotlin/Java development (recommended)

Project structure

src/main/kotlin/
  io/github/jingu/idea_qiq_plugin/
    lexer/          # JFlex definition and generated lexer adapter
    highlight/      # Syntax highlighters, colors, annotators
    inject/         # PHP language injection
    navigation/     # Reference contributors and resolution utilities
    editor/         # Typed/Enter handlers
    util/           # Path resolution helpers
    ...             # Other plugin components
src/main/resources/
  META-INF/plugin.xml   # Plugin descriptor
  messages/             # Resource bundle for UI strings
  ...
src/test/kotlin/        # Unit tests
README.md

Generated lexer sources are placed under src/gen/ (ignored by Git). To regenerate them after editing Qiq.flex run:

./gradlew generateQiqLexer

Running tests

./gradlew test

Tests run against the PhpStorm platform specified in build.gradle.kts.

Coding guidelines

• Kotlin sources follow JetBrains' official style.
• Keep packages under io.github.jingu.idea_qiq_plugin aligned with directory layout.
• Use ASCII characters unless non-ASCII is necessary.
• Before committing, consider running ./gradlew test and ensure the sandbox IDE behaves as expected for major UI changes.

Contributing

Pull requests and issue reports are welcome. Please include:

• A clear description of the change or bug.
• Steps to reproduce bugs when applicable.
• Added or updated tests covering new functionality.

License

This project is released under the MIT License. See LICENSE for details.