Util Laravel Package

Getting Started

phug/util is the low-level support library that sits underneath the Phug/Pug PHP templating stack. If you installed phug/phug or pug-php/pug, it is already in your vendor/ directory. Install it directly only when you are writing a Phug module, an extension, or a small library that wants the same building blocks.

composer require phug/util

Where to look first:

1. src/Partial/ — the trait library. This is the highest-value part of the package: small, single-responsibility traits (NameTrait, ValueTrait, PathTrait, LineTrait, OffsetTrait, SourceTrait, OptionTrait, ParentTrait, ChildrenTrait, AttributesTrait, …) that you can compose into your own classes instead of copy-pasting accessors.
2. src/OptionInterface.php / src/Partial/OptionTrait.php — the canonical "options bag" pattern used everywhere in Phug. Implement this and your class behaves like every other configurable Phug object.
3. src/ModuleInterface.php + src/AbstractModule.php — the plugin contract for extending Phug.
4. src/Collection.php and src/OrderedList.php — array wrappers used throughout the ecosystem.
5. src/SourceLocation.php — line/column/offset bookkeeping for anything that reports template errors.

First use case: give a class a clean option bag so callers can pass ['foo' => 'bar'] and read it via $obj->getOption('foo', $default) without writing boilerplate. That single trait is the most reused piece of the package.

Implementation Patterns

Option bag on your own classes. This is the pattern you will reach for daily. Implement OptionInterface and pull in OptionTrait, then merge caller options over defaults:

use Phug\Util\OptionInterface;
use Phug\Util\Partial\OptionTrait;

class Renderer implements OptionInterface
{
    use OptionTrait;

    public function __construct(array $options = [])
    {
        $this->setOptions(array_replace([
            'pretty'   => false,
            'encoding' => 'UTF-8',
        ], $options));
    }
}

$r = new Renderer(['pretty' => true]);
$r->getOption('pretty'); // true

Ordered collections instead of raw arrays. OrderedList gives you add, insert, remove, indexOf, and predictable iteration order, which is exactly what you need for ordered things like middleware, filters, or event listeners. Reach for Collection when you want keyed access with get/set/has/remove semantics without sprinkling array_key_exists through your code.

Source location for diagnostics. Any component that can fail on user input (a parser, a compiler, a formatter) should attach a SourceLocation rather than just a string message. Consumers can then render path:line:column consistently with Phug's own error output, and IDE/editor integrations can jump to the right spot.

Module pattern for extensibility. If you are extending Phug, subclass AbstractModule and declare what events or options you care about. The module is then registered on the Phug engine and receives the shared container/option bag, so your code sees the same configuration as the host. Do not reach into the engine's internals; use the accessors the module interface exposes.

Profiler for hot paths. Profiler wraps start/end style timing around named sections and pairs well with a debug flag in your options. Wire it behind getOption('debug') and you get cheap, opt-in instrumentation for template compilation without pulling in a heavier profiler.

Compose traits, do not inherit deeply. The Partial traits are designed to be mixed into classes of different shapes. A small value object with NameTrait + ValueTrait + SourceTrait is idiomatic here; a three-level class hierarchy is not.

Sandbox for user-supplied callables. SandBox is the escape hatch for invoking closures in a controlled scope with access to a defined set of variables — useful when you are evaluating user-provided expressions and want to avoid leaking $this or local state.

Gotchas and Tips

• It is a support package, not a product. There is no standalone documentation site. The authoritative spec is the source plus the way phug/phug and pug-php/pug consume it. Read src/ first; do not expect a README walkthrough.
• API stability is tied to the parent ecosystem. Minor versions may shift method signatures as the templating engine evolves. If you depend on phug/util directly, pin a range in composer.json and run your test suite on upgrade rather than floating on ^.
• Trait collisions are your problem. OptionTrait, SourceTrait, and friends can define overlapping properties/methods if you stack too many. Resolve with insteadof / as, or implement the specific accessor yourself. Do not blindly use a dozen traits.
• Options merge shallowly by default. setOptions / mergeOptions will overwrite top-level keys, not deep-merge nested arrays. If you need deep merging you must do it explicitly before passing options in — a common source of "my default was ignored" bugs.
• Collection is not an array. Functions like array_map, array_filter, and count() behave differently than on a plain array, and strict comparisons (===) will fail between a Collection and its array equivalent. Call toArray() (or iterate) before handing data to third-party code.
• Source locations must be plumbed through. The object only describes a location; nothing computes it for you. Feed path, line, offset, and the original source string at the point where you know them, or downstream error messages will be unknown:0.
• Debugging is easiest via the exception types. Phug\Util\Exception\* carries location context; catching the base runtime exception and dumping getMessage() loses that context. Inspect the location object, and enable Xdebug's develop mode if you want readable stack traces through the trait-heavy call chains.
• Extension points, ranked by risk: implementing OptionInterface (safe), composing Partial traits (mostly safe), subclassing AbstractModule (couples you to Phug's event naming), extending Collection/OrderedList (watch for method additions that shadow yours). Prefer the lowest-risk option that solves the problem.
• Zero dependents does not mean unmaintained. The package is pulled in transitively by the Phug stack rather than being depended on directly, so its release cadence tracks the engine, not its own star count.