Dindent Laravel Package

Technical Evaluation

Architecture Fit

• Updated Use Case Alignment (v3.1.0 — no change to fit):
  • Expanded HTML Support: Handles <style> tags and optimizes inline elements — suitable for projects with embedded CSS or complex inline HTML (e.g., email templates, legacy Blade views with inline styles).
  • One-Line Mode: Ideal for compact HTML outputs (e.g., API responses, notifications) where minimal indentation is preferred.
  • Non-Fit Scenarios (Unchanged):
    • Still not recommended for production-critical rendering pipelines (performance overhead is negligible but unnecessary).
    • Dynamic JS-generated HTML (e.g., Livewire/Alpine.js) remains irrelevant.
• New Considerations (v3.1.0):
  • The patch fixes temporary replacement state leaking between calls. This does not change what the package is good for, but it changes where it is safe to run: previously, repeated in-process invocations with mixed content (<pre>, <textarea>, <style>) could produce corrupted output on later calls. That makes the package materially more viable in long-running PHP processes (Horizon/queue workers, Octane/Swoole, looping Artisan commands) rather than only single-shot CLI/request contexts.
  • Email Templates: Still the strongest fit — mailables/notifications rendered in bulk by queue workers are exactly the repeated-call scenario this patch addresses.
  • Legacy Codebases: Still useful for normalizing inconsistent indentation in older Blade templates or static HTML, especially when batch-processing many files in one Artisan run.

Integration Feasibility

• PHP/Laravel Compatibility (Unchanged):
  • Breaking Constraint: Requires PHP 8.2+ (Laravel 10+). Projects on PHP 8.1 or older must migrate or use a fork. This remains the single largest integration blocker and was not relaxed in v3.1.0.
  • Key Integration Points:
    • One-Line Mode: Config flag or Artisan option:

      Dindent::indent($html, ['one_line' => true]);
      

    • Style Tag Support: Useful for inline CSS in Blade templates (<style>body { ... }</style>).
    • Pre/Textarea Extraction: Preserves formatting in <pre>/<textarea> — and is the code path most affected by the v3.1.0 state-leak fix.
• Version Constraint Guidance:
  • Pin ^3.1 (not ^3.0) if the package is used anywhere other than a single CLI invocation per process. ^3.0 will resolve to 3.1.0 on a clean install but may leave already-installed environments on 3.0.0 — verify with composer show schleuse/dindent.
• Example Integration Snippet (Unchanged):

  use Schleuse\Dindent\Dindent;
  
  // One-line mode for API responses
  $compactHtml = Dindent::indent($html, ['one_line' => true]);
  
  // Style tag optimization
  $styledHtml = Dindent::indent($htmlWithStyles);
  

Technical Risk

• Updated Risks:
  • Breaking Change (High Impact, Unchanged): PHP 8.2 requirement forces migration for older stacks. Mitigate by auditing composer.json PHP constraints and, if migration is blocked, proposing a parallel fork (schleuse/dindent:v2).
  • State-Leak Defect Class (Reduced — was unrated in prior assessment):
    • v3.0.0 could carry temporary replacement placeholders across calls within the same process, silently corrupting later output. This is a silent failure (wrong HTML, no exception) — the highest-cost category for us.
    • v3.1.0 fixes it. Residual risk: the fix is a single commit with no accompanying test-coverage signal in the release notes, and it is the only change in seven months. Treat as "likely fixed, verify ourselves."
  • New Features (Low Risk): <style> and one-line mode add flexibility but may introduce edge cases (e.g., conflicting CSS rules in <style> tags).
  • Maintenance Velocity (New): v3.0.0 (2026-03-11) → v3.1.0 (2026-10-03) is a ~7-month window with one bug fix and no feature work. Signals a low-activity, likely single-maintainer project. Plan for the possibility that the next breaking change arrives without warning or support.
• Open Questions (Updated):
  • Does the fix hold across mixed content sequences (e.g., a <pre>-heavy template followed by a plain template in the same worker)?
  • How will one-line mode interact with nested elements (<div><span>...</span></div>)?
  • Are there performance trade-offs for <style> tag parsing in large HTML strings?

Key Questions for Stakeholders

1. Migration Impact: Can the team reach PHP 8.2/Laravel 10+ by the next release cycle? If not, fork or abandon.
2. Runtime Context: Will this run inside queue workers / Octane (repeated in-process calls) or only one-shot CLI/request contexts? This determines whether v3.1.0 is a required upgrade or merely nice-to-have.
3. Use Case Clarification: Do we want one-line mode for API responses or keep it test-only? Do we need <style> support for email templates or inline Blade CSS?
4. Maintenance: Given the low release cadence, who owns monitoring upstream, and do we need to vendor/fork to guarantee continuity?
5. Alternatives: For PHP 8.1 projects, would a custom DOMDocument-based solution suffice, or does the new functionality justify the upgrade?

Integration Approach

Stack Fit

• Laravel-Specific Levers (Unchanged):
  • Artisan Command Enhancements:

    php artisan html:indent --one-line --optimize-styles resources/views/email.blade.php
    

  • Blade Directive:

    Blade::directive('indent', function ($expression) {
        return "<?php echo \\Schleuse\\Dindent\\Dindent::indent($expression, ".json_encode(['one_line' => true])."); ?>";
    });
    

  • Email/Notification Integration:

    public function build()
    {
        $html = $this->view('emails.welcome');
        $indented = Dindent::indent($html, ['one_line' => false]);
        return $this->markdown('emails.welcome')->with(['html' => $indented]);
    }
    

• Queue/Worker Fit (Improved in v3.1.0): The mailable-in-queue-worker pattern above is now the recommended fit rather than a caveat. Wrap all calls in a single service class so one code path owns pinning, options, and any future workaround.

Migration Path

1. Phase 0: Pre-Migration (Critical, Unchanged)
   • Audit PHP 8.2/Laravel 10 compatibility across the stack.
   • Fallback plan: fork the package or identify a DOMDocument-based alternative.
2. Phase 1: Proof of Concept (Updated)
   • Require schleuse/dindent:^3.1 (pin the minor, not ^3.0).
   • Test repeated-call sequences in a single process, not just single invocations:
     • Call 1: template containing <pre>, <textarea>, and <style>.
     • Call 2: plain template — assert output is byte-identical to a fresh-process render.
   • Test one-line mode in API responses and style-tag handling in email templates.
3. Phase 2: Tooling Integration
   • Update the Artisan command with new flags; configure mailables/notifications.
4. Phase 3: Enforcement
   • Add to pre-commit hooks with conditional flags (e.g., --one-line for specific paths).

Compatibility

• Regression Scope for v3.1.0 (New): The fix is internal to placeholder handling, so no API changes and no config changes. Regression surface is limited to output equality across consecutive calls — cheap to test, and the test doubles as protection against future upstream regressions.
• HTML Parsing:
  • Style Tags: Test with complex CSS (@media, nested rules) to avoid false formatting.
  • One-Line Mode: Validate edge cases:

    <div><span>Test</span><br></div>  <!-- Should remain compact -->
    

• Configuration: Check whether global defaults (config/dindent.php) are supported; otherwise standardize via wrapper.
• Laravel Ecosystem: Verify HTML integrity through Horizon, Mailgun, SendGrid, and confirm one-line mode doesn't disturb Livewire/Alpine dynamic content.

Sequencing

Operational Impact

Maintenance

• Pros (Updated):
  • One-Line Mode: Reduces noise in API responses/notifications.
  • Style Tag Support: Centralizes CSS formatting logic.
  • Deterministic Across Calls: v3.1.0 removes the need for process-restart workarounds in workers — less operational folklore to maintain.
• Cons (Updated):
  • PHP 8.2 Dependency: Increases maintenance burden for teams on older stacks.
  • Low Upstream Velocity: One bug fix in ~7 months. Assume no SLA and plan for self-support; consider vendoring the one class we depend on if the package becomes load-bearing.
  • False Positives: One-line mode may obscure debugging in complex HTML.
  • Configuration Drift: Team-wide agreement still needed on where one-line mode applies.
• Mitigations:
  • Wrapper Class: Single internal entry point that pins version, sets defaults, and can absorb a fork or replacement later.
  • Deprecation Plan: Document a timeline for PHP 8.1 support (if any) in the fork.

Support

• Debugging (Updated):
  • Output Diffing: Because the v3.1.0 defect was silent, support procedures should include a "render twice, compare" check when output corruption is suspected.
  • One-Line Mode: Add a --debug flag to the Artisan command to show original vs. indented HTML.
  • Style Tag Issues: Log warnings for malformed CSS (e.g., unclosed braces) during indentation.
• Community:
  • Monitor GitHub issues for PHP 8.2-specific bugs and any follow-up to e130cb1.
  • Contribute a test case for repeated-call isolation and Laravel mailable examples upstream — cheap investment in a single-maintainer package we depend on.

Scaling

• Performance (Unchanged):
  • One-Line Mode: Benchmark against original mode for large HTML (e.g., 50KB emails).
  • Style Tag Parsing: Test with deeply nested CSS to avoid timeouts.
• Parallelization: Process email templates via Laravel Queues. Note: with v3.1.0, per-call state is reset, so a long-lived worker handling thousands of jobs no longer accumulates or leaks replacement state — memory profile across a worker's lifetime should be re-checked once (peak RSS over 1k jobs) to confirm no other static growth.

Failure Modes