Twig Pathfinder 🚀

Twig Pathfinder is a powerful VS Code extension that provides seamless navigation between Twig templates, Symfony routes, and PHP controllers. It supercharges your Symfony development workflow by allowing you to instantly jump to referenced files with a single click.

✨ Features

🎯 Core Navigation

Twig → Template Navigation

Jump directly to included, extended, or embedded Twig templates:

{# Click on the template path to navigate #}
{% include 'partials/header.twig' %}
{% extends 'base.html.twig' %}
{% embed 'forms/contact.twig' %}
{% import 'macros.twig' as macros %}

✨ Works with:

• Relative paths: 'partials/header.twig'
• Absolute paths: '@templates/base.html.twig'
• Template directories: 'templates/', 'views/'
• Any file extension: .twig, .html.twig

Twig → Route Navigation

Navigate to Symfony route definitions from Twig:

{# Click on route name to navigate #}
<a href="{{ path('app_home') }}">Home</a>
<a href="{{ url('app_contact') }}">Contact</a>

✨ Supports:

• PHP Route Attributes (Symfony 5.4+): #[Route('/path', name: 'route_name')]
• PHP Annotations (Symfony 5.3 and earlier): @Route("/path", name="route_name")
• YAML Route Files: config/routes/*.yaml

PHP → Twig Navigation ⭐ NEW!

Navigate from PHP controllers to Twig templates:

// Click on template name to navigate
$this->render('index.html.twig');
$this->renderView('partials/header.twig');
return $this->render('forms/contact.twig');

✨ Works with:

• $this->render('...')
• $this->renderView('...')
• return $this->render('...')
• $twig->render('...')

📦 Installation

From VS Code Marketplace (Recommended)

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X or Cmd+Shift+X)
3. Search for "Twig Pathfinder"
4. Click Install
5. Reload VS Code if prompted

From Source (Development)

1. Clone the repository:

   git clone https://github.com/c4n4r/twig-pathfinder.git
   cd twig-pathfinder
   

2. Install dependencies:

   npm install
   

3. Compile TypeScript:

   npm run compile
   

4. Launch Extension Development Host:

   • Press F5 in VS Code
   • A new VS Code window will open with the extension loaded

5. Open your Symfony project in this new window

🚀 Usage

Quick Start

1. Open a Twig file in your Symfony project
2. Position your cursor on a template path or route name
3. Press F12 (or Cmd+Click / Ctrl+Click) to navigate

That's it! The extension automatically:

• Indexes your workspace on startup
• Resolves template paths and route names
• Opens the target file in a new tab

Keyboard Shortcuts

⚙️ Configuration

Customize the extension behavior via VS Code settings:

Opening Settings

1. GUI: Ctrl+, (or Cmd+, on Mac) → Search for "Twig Pathfinder"
2. JSON: Open settings.json (Ctrl+, → Open Settings (JSON))

Available Settings

📁 Indexing

🎨 Twig

🏗️ Symfony

💾 Cache

👀 File Watching

⚡ Performance

Example Configuration

{
  "twigOpenInclude.indexing.enabled": true,
  "twigOpenInclude.indexing.eagerIndexTwig": true,
  "twigOpenInclude.twig.templateDirectories": ["templates", "views"],
  "twigOpenInclude.twig.fileExtensions": [".twig", ".html.twig"],
  "twigOpenInclude.symfony.controllerPatterns": [
    "**/src/Controller/**/*.php",
    "**/Controller/**/*.php"
  ],
  "twigOpenInclude.cache.enabled": true,
  "twigOpenInclude.watch.excludePatterns": [
    "**/{node_modules,vendor,var,public}/**",
    "**/.git/**"
  ]
}

🏗️ Project Structure Support

The extension works best with standard Symfony project structures:

your-project/
├── templates/
│   ├── base.html.twig
│   ├── index.html.twig
│   └── partials/
│       └── header.html.twig
├── src/
│   └── Controller/
│       ├── DefaultController.php
│       └── Api/
│           └── RestController.php
└── config/
    └── routes/
        ├── annotations.yaml
        └── api/
            └── api.yaml

Custom Structures

If your project uses a different structure, update the settings:

{
  "twigOpenInclude.twig.templateDirectories": ["app/Resources/views", "resources/views"],
  "twigOpenInclude.symfony.controllerPatterns": ["**/app/Http/Controllers/**/*.php"],
  "twigOpenInclude.symfony.routeFilePatterns": ["**/routes/*.php"]
}

🔍 How It Works

Architecture

The extension uses a modular architecture with the following components:

┌─────────────────────────────────────────────────────────────┐
│                      VS Code Extension                         │
├─────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
│  │  Providers   │    │  Resolvers   │    │   Indexer    │   │
│  │              │    │              │    │              │   │
│  │ • DocumentLink│    │ • Twig       │    │ • Twig       │   │
│  │ • Definition  │    │ • Symfony    │    │ • Routes     │   │
│  │   (Twig)     │    │ • PHP        │    │ • Controllers│   │
│  └──────────────┘    └──────────────┘    └──────────────┘   │
│           │                   │                   │          │
│           └───────────────────┼───────────────────┘          │
│                               ▼                              │
│                    ┌──────────────────┐                       │
│                    │ Resolver Dispatch │                       │
│                    │    (with cache)   │                       │
│                    └──────────────────┘                       │
│                               ▼                              │
│                    ┌──────────────────┐                       │
│                    │   File System    │                       │
│                    │   (with cache)    │                       │
│                    └──────────────────┘                       │
│                                                                  │
└─────────────────────────────────────────────────────────────┘

Workflow

1. Activation: Extension loads and indexes your workspace
2. Navigation Request: You click on a template path or route name
3. Resolution:
   • Check cache first (if enabled)
   • Check workspace index
   • Fall back to file search
4. Navigation: Open the target file in VS Code

Performance Optimizations

• Eager Indexing: All templates, routes, and controllers are indexed on startup
• LRU Caching: File operations and resolutions are cached with configurable TTL
• Parallel Resolution: PHP and YAML routes are resolved in parallel
• Debounced Watching: File changes are processed with debouncing to avoid performance issues
• Smart Search: Intelligent fallback when files aren't in the index

🐛 Troubleshooting

Common Issues

❌ Navigation doesn't work

Possible causes:

• File is not a .twig or .php file
• Template path is not in quotes
• Template doesn't exist
• Indexing is disabled

Solutions:

1. Check the file extension is recognized
2. Ensure the path is between quotes: 'template.twig' or "template.twig"
3. Verify the template exists in your project
4. Enable indexing in settings: twigOpenInclude.indexing.enabled = true

❌ Wrong file opened

Possible causes:

• Multiple templates with the same name
• Custom template directories not configured
• Cache returning stale results

Solutions:

1. Use more specific template paths
2. Update templateDirectories in settings
3. Clear cache by restarting VS Code or disabling/enabling caching

❌ Slow performance

Possible causes:

• Large project with many files
• Eager indexing enabled on a large project
• Too many parallel operations

Solutions:

1. Disable eager indexing: twigOpenInclude.indexing.eagerIndexTwig = false
2. Reduce search limit: twigOpenInclude.twig.searchLimit = 1000
3. Reduce parallel operations: twigOpenInclude.performance.maxParallelOperations = 2
4. Exclude large directories from watching

❌ Extension not activating

Possible causes:

• Extension not installed correctly
• VS Code not reloaded after installation
• Activation events not triggered

Solutions:

1. Check extension is installed: Ctrl+Shift+P → "Extensions: Show Installed Extensions"
2. Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"
3. Check activation events in package.json

📊 Performance

Benchmarks

Tips for Large Projects

1. Disable eager indexing if startup is too slow:

   {
     "twigOpenInclude.indexing.eagerIndexTwig": false
   }
   

2. Limit search scope to relevant directories:

   {
     "twigOpenInclude.twig.templateDirectories": ["templates"],
     "twigOpenInclude.symfony.controllerPatterns": ["**/src/Controller/**/*.php"]
   }
   

3. Exclude large directories from watching:

   {
     "twigOpenInclude.watch.excludePatterns": [
       "**/{node_modules,vendor,var,public,storage}/**",
       "**/.git/**",
       "**/tests/**"
     ]
   }
   

4. Reduce cache size if memory usage is high:

   {
     "twigOpenInclude.cache.maxSize": 500
   }
   

🤝 Contributing

We welcome contributions! Here's how you can help:

Reporting Issues

1. Check the Output panel for error messages
2. Verify the issue with a minimal test case
3. Open an issue on GitHub
4. Include:
   • VS Code version
   • Extension version
   • Symfony version
   • Project structure
   • Error messages
   • Steps to reproduce

Development

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm run test
5. Compile: npm run compile
6. Test in VS Code: Press F5
7. Submit a pull request

Code Style

• Follow TypeScript best practices
• Use meaningful variable and function names
• Add comments for complex logic
• Keep functions small and focused
• Write tests for new features

📜 Changelog

See CHANGELOG.md for release history.

📄 License

This extension is licensed under the MIT License.

🙏 Acknowledgments

• Inspired by the need for better Twig navigation in VS Code
• Built with ❤️ for the Symfony community
• Made by Shifumi, with a bit of Mistral AI Help

Happy Coding! 🎉

Twig Pathfinder - Navigate your Symfony templates with ease.