Pug Filter Less Laravel Package

Getting Started

This release is narrow: 1.1.0 adds Pug-php 3 compatibility. Treat it as a dependency-alignment release, not a feature release. If your app already uses pug-php/pug 3.x, upgrade the Laravel integration to ^1.1 and verify template rendering. If you are still on Pug-php 2.x, check whether 1.1.0 still supports it before upgrading; the release note does not say whether 2.x support was dropped or widened.

Minimal setup:

1. Check composer.json for the integration package and pug-php/pug constraints.
2. Upgrade with dependencies:

   composer require <laravel-pug-integration>:^1.1 pug-php/pug:^3 --with-dependencies
   

   Use the actual package name from your composer.json; do not copy the placeholder.
3. Confirm the package’s service provider is auto-discovered, or register it manually if the package requires that.
4. Publish/inspect the package config if it provides one. Look for Pug options such as template extension, cache path, pretty, and expression/option settings.
5. Put a .pug file under resources/views and render it with Laravel’s normal view() helper.

Where to look first:

• The package README for service-provider registration and config publishing.
• composer.json for the Pug-php 3 constraint.
• The package service provider for view-extension registration and container bindings.
• The config file for cache/compiler options.
• Laravel’s view finder behavior if both .blade.php and .pug files exist for the same view name.

First use case: replace a Blade layout/page with Pug for markup-heavy screens.

resources/views/layouts/app.pug:

doctype html
html
  head
    title= $title
  body
    block content

resources/views/home.pug:

extends layouts/app

block content
  h1 Hello #{$userName}
  p Welcome to the dashboard.

Controller:

return view('home', [
    'title' => 'Home',
    'userName' => $user->name,
]);

Implementation Patterns

Use Pug where its indentation-based syntax and mixins reduce markup noise, but keep Laravel application logic in controllers, view composers, and small view models.

Common day-to-day patterns:

• Layouts with extends and block. Keep one or two base layouts and override blocks per page. This is the main replacement for Blade’s @extends/@section.
• Partials with include. Use includes for navigation, footer, pagination, and repeated static fragments.
• Mixins for components. Define reusable UI fragments with arguments instead of duplicating markup:

  mixin button(label, href)
    a.btn(href=href)= label
  

  Then use +button('Save', '/save').
• Pass prepared data into views. Prefer simple scalars, arrays, and view models over calling services inside templates. This keeps Pug templates portable and easier to test.
• Use view composers for shared globals. Navigation data, current user display name, and app-level flags are better shared through view()->share() or composers than repeated controller arrays.
• Migrate incrementally. Start with one leaf page, then convert the layout, then convert shared partials. Do not mix Blade directives into Pug files; use Pug conditionals/loops or pass computed values from PHP.
• Test rendered output. Feature-test routes that return Pug views with assertSee() or render the view directly. This catches indentation, missing variables, and cache issues before deploy.
• Warm and clear compiled views on deploy. Clear compiled templates after deploy and after config changes. If the package compiles to a cache directory, ensure it is writable in production.
• Upgrade path for 1.1.0. Run the dependency update, clear config/view caches, render a layout, a page with data, and a page using includes/mixins. Then test any custom Pug options or filters.

Gotchas and Tips

• This is a compatibility release, not a syntax feature. Do not expect new Laravel helpers or Pug syntax from 1.1.0. Its main value is allowing the integration to work with Pug-php 3.
• Confirm the dependency contract. The release note only says “Pug-php 3 compatibility.” Check whether 1.1.0 widens the constraint or replaces Pug-php 2 support. If it replaces 2.x, apps still on Pug-php 2 need a planned upgrade.
• Pin both packages together. Use compatible constraints for the Laravel integration and pug-php/pug; avoid floating versions in production.
• View-name resolution can surprise you. If home.blade.php and home.pug both exist, the view finder’s extension order decides which wins. Use distinct names during migration or confirm the package registers .pug in the order you expect.
• Clear caches aggressively when debugging. Run php artisan view:clear and, if config was changed, php artisan config:clear. Stale compiled Pug templates can make fixes appear not to work.
• Pug errors often point at indentation. A single wrong space can change nesting. Keep indentation consistent and enable development-friendly options such as pretty output or disabled cache locally if the package supports them.
• Escaping differs from Blade. Pug’s escaped interpolation and unescaped interpolation are separate. Never use unescaped output for user-controlled data.
• Do not assume Pug-php 2 options still behave the same in 3.x. Custom filters, keywords, expression handling, and compiler options are the most likely places to need changes after this upgrade.
• Custom extension points need smoke tests. If you registered custom Pug filters, keywords, or container bindings, verify them after upgrading. The integration may still expose the same config/options, but Pug-php 3 may change the underlying signatures.
• Production error pages need special attention. Pug compilation failures can surface as view exceptions. Test the upgrade against a real layout, a page with includes, and a page with mixins before deploying.