Fractor Fluid Laravel Package

Product Decisions This Supports

• Developer Productivity & Code Quality: Enables automated Fluid template linting, formatting, and rule-based enforcement (e.g., enforcing consistent variable naming, avoiding deprecated syntax, or enforcing security best practices like output escaping). Reduces manual review cycles and developer friction in templating workflows.
• Build vs. Buy: Justifies building a custom Fluid rule engine (via this package) over buying third-party tools (e.g., PHP-CS-Fixer with Fluid support) if:
  • Your team needs domain-specific rules (e.g., enforcing a custom naming convention for Fluid variables tied to your business logic).
  • You require deep integration with existing Fractor workflows (e.g., running alongside other file processors in a monorepo).
  • You prioritize maintainability over out-of-the-box solutions (since this is a lightweight, MIT-licensed package).
• Roadmap Alignment:
  • Supports a shift-left strategy by catching template issues early in the CI/CD pipeline (e.g., fail builds on Fluid violations).
  • Enables scalable onboarding for new developers by standardizing template patterns (e.g., "all Fluid files must use {{ }} syntax, never {$}").
  • Useful for legacy system modernization where Fluid templates are scattered and inconsistent.
• Use Cases:
  • Tightly coupled with Fractor: If your team already uses Fractor for other file types (e.g., PHP, YAML), this extends that ecosystem seamlessly.
  • Custom Rule Development: Need to enforce rules like:
    • "All Fluid templates must include a {{ copyright }} section."
    • "Avoid hardcoded paths in templates; use {{ asset() }} instead."
  • Pre-commit Hooks: Integrate with tools like Husky to auto-fix or block commits with Fluid violations.
  • Documentation Generation: Extract and validate Fluid template usage patterns for internal design system docs.

When to Consider This Package

• Look Elsewhere If:

  • You need out-of-the-box Fluid linting/formatting without custom rules → Use PHP-CS-Fixer with its Fluid sniffer or TwigCS (if using Twig-like syntax).
  • Your team lacks PHP/Fluid expertise to write custom rules → Prioritize low-code tools like Symfony’s Fluid sandbox or Twig’s built-in checks.
  • You’re not using Fractor → The package’s value is tied to Fractor’s existing workflows (e.g., parallel processing, rule composition). Standalone Fluid tools may offer more features.
  • You need visual template validation (e.g., previewing changes) → Consider Twig Debugger or Fluid’s built-in debugging.
  • Your Fluid templates are minimal/consistent → The overhead of custom rules may not justify the effort.

• Adopt This Package If:

  • You’re already using Fractor and want to extend it to Fluid.
  • You need fine-grained control over Fluid syntax/rules (e.g., aligning with a design system).
  • Your team can invest in writing/maintaining custom rules (low stars/dependents suggest early-stage adoption).
  • You’re in a monorepo with mixed file types and want unified linting.

How to Pitch It (Stakeholders)

For Executives (Business Impact)

"This package lets us automate and enforce best practices for our Fluid templates—reducing bugs, improving consistency, and cutting manual review time. For example, we can block deprecated syntax or enforce security patterns (like output escaping) before code reaches production. It’s a lightweight, MIT-licensed tool that integrates with our existing Fractor workflow, so there’s no vendor lock-in. The upfront investment in custom rules pays off long-term by standardizing templates and making onboarding easier for new devs."

Ask: "Would you prioritize reducing template-related bugs over short-term tooling costs?"

For Engineering (Technical Fit)

*"Fractor-Fluid extends our existing Fractor setup to handle Fluid templates with custom rules. Key benefits:

• Seamless Integration: Works alongside our current file processors (e.g., PHP, YAML).
• Custom Rules: We can enforce our own standards (e.g., variable naming, security checks) without relying on third-party tools.
• CI/CD Ready: Fail builds on violations or auto-fix simple issues (e.g., formatting).
• Low Risk: MIT license, minimal dependencies, and ties into our existing toolchain.

Trade-offs:

• Requires writing custom rules (but we can start with a few high-impact ones).
• Not as feature-rich as standalone tools like PHP-CS-Fixer, but more aligned with our workflow.

Proposal:

1. Start with 2–3 critical rules (e.g., output escaping, deprecated syntax).
2. Integrate into pre-commit hooks and CI.
3. Expand rules as needed.

Ask: "Does this fit our tech stack, and should we allocate time to build initial rules?""*