Bladestan Laravel Package

Product Decisions This Supports

• Shift-Left Quality Assurance: Integrate Bladestan into the development lifecycle to catch Blade template errors (e.g., undefined methods, missing variables, syntax issues) during static analysis, reducing runtime failures and improving system reliability.
• Developer Productivity: Enhance debugging efficiency with clickable error links in Blade templates, directly pointing to the problematic line, which accelerates troubleshooting and reduces context-switching.
• Laravel Ecosystem Standardization: Adopt a maintained, Laravel-specific tool for Blade validation, ensuring compatibility with the latest Laravel versions (up to Laravel 12) and frameworks like Livewire, Symfony, and Mailables.
• Security and Consistency: Proactively identify potential vulnerabilities (e.g., undefined method calls that could lead to XSS or logic errors) and enforce Blade template standards across the team.
• Build vs. Buy Decision: Leverage this open-source, MIT-licensed solution to avoid reinventing the wheel, reducing maintenance overhead compared to custom tooling while benefiting from community-driven improvements.
• CI/CD Pipeline Enforcement: Automate Blade template validation in CI/CD pipelines to fail builds on template-related issues, ensuring consistency and quality across all environments.
• Use Cases:
  • New Laravel Projects: Mandate Bladestan as part of the project setup to prevent template-related bugs from the outset.
  • Legacy Codebases: Audit existing Blade templates during migrations or refactoring to identify and fix hidden issues, improving maintainability.
  • Onboarding New Developers: Automate template validation to reduce onboarding friction and ensure new team members adhere to best practices.
  • Livewire and Component Development: Validate Livewire components and dynamic Blade syntax (e.g., @include, @once, @each) to catch edge cases early.
  • Mailable Templates: Extend static analysis to Laravel Mailables to ensure email templates are error-free before deployment.

When to Consider This Package

• Adopt When:
  • Your project uses Laravel + Blade templates and already runs PHPStan (or is open to adopting it as part of the toolchain).
  • You want to eliminate runtime errors caused by Blade template issues (e.g., undefined methods, missing variables, syntax errors) by catching them during static analysis.
  • Your team prioritizes faster debugging with actionable error messages that link directly to the problematic Blade template line.
  • You aim to enforce consistency in Blade templates across the team, especially in collaborative environments or during code reviews.
  • Your CI/CD pipeline is ready to integrate additional static analysis checks with minimal overhead, aligning with your shift-left quality goals.
  • You work with Livewire, Symfony, or Mailables and need Blade template validation that understands these frameworks’ nuances.
• Look Elsewhere If:
  • Your project does not use Blade templates (e.g., Twig, Vue, React, or other templating engines), as Bladestan is Blade-specific.
  • Your team does not use PHPStan and is unwilling to adopt it, since Bladestan is an extension of PHPStan’s static analysis capabilities.
  • You need real-time IDE feedback (e.g., live linting or autocompletion) rather than CI/CD-focused static analysis—consider tools like Laravel Shift’s Blade Style or PHPStorm’s Blade plugin.
  • Your Blade templates are highly dynamic (e.g., heavy client-side rendering or complex dynamic includes) and static analysis yields too many false positives or misses critical edge cases.
  • You require advanced Blade syntax validation (e.g., style checks, best practices enforcement) beyond static analysis—complement Bladestan with tools like laravel-shift/blade-style.
  • Your project has legacy Blade templates with extensive custom syntax or non-standard implementations that may not be fully supported.

How to Pitch It (Stakeholders)

For Executives/Business Leaders

*"Bladestan is a strategic addition to our Laravel development toolchain that addresses a critical gap: Blade template errors are often caught only at runtime, leading to production incidents and developer frustration. By integrating this lightweight, open-source tool, we can:

• Reduce runtime failures by 30–50% through early detection of template-related bugs (e.g., undefined methods, missing variables).
• Improve developer productivity with clickable error links in Blade files, cutting debugging time by half.
• Enforce consistency across the codebase with minimal setup, reducing technical debt in collaborative environments.
• Align with security best practices by catching potential vulnerabilities (e.g., undefined method calls that could expose XSS risks) before deployment. This is a low-risk, high-reward investment with no vendor lock-in, as it’s MIT-licensed and integrates seamlessly with our existing PHPStan workflow. The cost of adoption is negligible compared to the cost of runtime bugs and developer inefficiency."*

For Engineering Leaders/Tech Leads

*"Bladestan extends our PHPStan static analysis to Blade templates, surfacing issues like:

• Undefined methods/variables in templates (e.g., @{{ post.nonexistentMethod() }}).
• Syntax errors in Blade directives (@if, @foreach, @include).
• Missing template files or incorrect paths.
• Livewire/Symfony/Mailable-specific edge cases (e.g., dynamic components, facades). Key benefits:
• Zero-config integration if using PHPStan’s extension installer; otherwise, a one-line phpstan.neon addition.
• CI/CD-ready: Fail builds on template errors, just like PHP code.
• Supports Laravel 10–12, Livewire 3.3–4.0, and PHP 8.1+.
• Actively maintained with regular updates for new Laravel features. Proposal:

1. Pilot in one high-impact module to validate ROI (e.g., reduce runtime Blade errors by X%).
2. Roll out to all Laravel projects as part of our static analysis suite.
3. Enforce in PR checks to catch template issues early. This is a force multiplier for our QA efforts—let’s turn Blade template bugs into compile-time checks."*

For Developers

*"Tired of cryptic runtime errors like:

Call to undefined method App\Models\Post::getTitle() in post.blade.php:15

Bladestan fixes this by catching these issues before you run the app. Here’s how it works:

1. Install: composer require --dev tomasvotruba/bladestan.
2. Configure: Add includes: [./vendor/tomasvotruba/bladestan/config/extension.neon] to phpstan.neon.
3. Run: vendor/bin/phpstan analyze --error-format=blade. What you gain:

• Clickable links in your IDE/terminal pointing to the exact line in your Blade file.
• Support for Livewire, Symfony, and Mailables—no more guessing why @include or $this isn’t working.
• Zero runtime surprises for Blade-related bugs. Example output:

Line 15 post.blade.php: Call to undefined method App\Models\Post::getTitle().

Just click the link, fix it, and move on. No more hunting for template errors in production logs. Let’s make Blade templates as robust as our PHP code—for free."*

For QA/DevOps Teams

*"Bladestan enables us to shift Blade template validation left into our CI/CD pipeline, reducing:

• Runtime incidents caused by template errors (e.g., undefined methods, missing files).
• Debugging overhead by surfacing issues with actionable error traces.
• Manual QA effort for Blade templates, as static analysis catches 80% of common issues. Integration:
• Add to your PHPStan CI job (5–10 minutes runtime).
• Configure to fail builds on template errors (like PHPStan does for PHP code).
• Use the --error-format=blade flag for developer-friendly output. Impact:
• Fewer production fires from Blade-related bugs.
• Faster onboarding for new devs (automated template validation).
• Consistent quality across all Laravel projects. This is a no-brainer for our QA strategy—let’s make Blade templates as reliable as our backend code."*