README

This repository is a readonly MoonShine monorepo subsplit. Please, open pull requests and issues in the main repository.

Display escaping

Labels, hints, prefixes, suffixes and string content returned by beforeRender() / afterRender() are escaped by default. This also applies to field labels rendered in tables, cards and relation headings, and to component labels such as buttons, links and tabs.

Allow HTML for an individual part explicitly:

Text::make('<strong>Name</strong>', 'name')
    ->unescapeLabel()
    ->hint('<a href="/help">Help</a>')
    ->unescapeHint()
    ->prefix('<span>Prefix</span>')
    ->unescapePrefix()
    ->suffix('<span>Suffix</span>')
    ->unescapeSuffix()
    ->beforeRender(fn () => '<aside>Before</aside>')
    ->unescapeBeforeRender()
    ->afterRender(fn () => '<aside>After</aside>')
    ->unescapeAfterRender();

Each unescape…() method has an escape…(bool $escape = true) counterpart. An explicit field/component setting takes precedence over the global setting in either direction. Label methods are also available on components with labels, for example ActionButton::make('<b>Open</b>')->unescapeLabel(). Footer applies its label preference to menu labels, and Tabs applies it to tabs created from items.

Text derived from field values has its own preference, so allowing HTML in a field label never exposes record data:

Text::make('<b>Site</b>', 'site')
    ->unescapeLabel()                              // field label only
    ->link(fn ($value) => $value, name: fn ($value) => $value)
    ->unescapeLinkName();                          // link names, opt in separately

BelongsToMany::make('Categories', 'categories', resource: CategoryResource::class)
    ->tree('parent_id')
    ->unescapeOptionLabels();                      // checkbox table, tree, horizontal and inline labels

Heading labels, explicit Modal / OffCanvas titles, field link names and related item labels remain escaped even when global label escaping is disabled, because they commonly contain record data. Use their local unescapeLabel(), unescapeTitle(), unescapeLinkName() or unescapeOptionLabels() only for trusted HTML. A title derived from an action button label follows the button's label preference; relation headings and modal titles follow the relation field's label preference. Confirmation content and explicit confirmation titles keep escaping enabled by default.

Htmlable values, such as HtmlString, are treated as prepared HTML. Return one from beforeRender() / afterRender() to output trusted markup without disabling escaping for the field. getBeforeRender() / getAfterRender() keep their Renderable|string return type: such values, including generated xIf() wrappers, are returned as RenderableHtml.

In Laravel, configure the defaults in config/moonshine.php:

'escapes' => [
    'label' => true,
    'hint' => true,
    'prefix' => true,
    'suffix' => true,
    'before_render' => true,
    'after_render' => true,
],

The corresponding MoonShineConfigurator methods are escapeLabel(), escapeHint(), escapePrefix(), escapeSuffix(), escapeBeforeRender() and escapeAfterRender(). Pass false to disable a default. Values from env() such as '0', 'false' or 'off' are accepted; empty or unrecognized values keep escaping enabled.

The global label setting applies to developer-provided labels without a local preference, including buttons, fields, boxes, dividers, menus and card value labels. Disabling it allows HTML in those labels; escape any record data included in them explicitly. The record-text contexts listed above keep their own escaping defaults. Prefer local unescape…() methods when only specific labels contain HTML.

These settings control display text. getLabel() and getHint() still return the original text, and existing value methods escape(), unescape() and escapeOnApply() keep their separate purpose. Renderable views and generated component markup are rendered as HTML. When upgrading HTML supplied as a plain string, enable the appropriate unescape…() method explicitly.

Relation modalMode() buttons inherit the field's label preference; modifyButton can override it. link() name callbacks receive the field preview as before, for example the option label of a Select or the formatted Date. While link names are escaped, fields that escape their own preview (Text, Textarea, BelongsTo) pass it as plain text, and the callback result is escaped once; other fields pass their prepared preview. When that preview is markup generated by the field (Checkbox, Color, Json, File, Number stars, multiple Select badges and Enum lists), the parts of the result that repeat it unchanged keep their prepared form; custom fields declare this by overriding isPreviewMarkup(); Url::title() callbacks likewise receive the raw value. After unescapeLinkName() callbacks receive the prepared preview and their result is output as trusted HTML. Inline BelongsToMany badge callbacks receive the prepared label, because badges print their value as is. A Link returned by its inline link callback follows the option label preference unless it sets its own label preference. Async search results selected into the checkbox table are inserted as text unless the field calls unescapeOptionLabels(). Popover editing uses the field's value escape() / unescape() preference independently of global or local label settings.

To reuse a label in another component, use labelFrom(): it copies both the label and its escaping preference, for example Heading::make()->labelFrom($field).

Table column-selection toggles inherit each field's label preference. An explicit handler label preference applies only when its button has no explicit label preference of its own. modifyButton runs in prepareButton() afterward and has the last word: the button it returns is used as is. Handlers::getButtons() applies the handler preference only to buttons that a custom getButton() returns without calling prepareButton().

Prefix/suffix rendering uses the field's isEscapePrefix() / isEscapeSuffix() getters, including overrides in custom fields. The default getters use the explicit field preference, then an explicit extension preference, then the global default. Rendering prepares a clone of the extension, so shared extension instances keep their own preferences. Standalone extensions use the same defaults through DisplayTextType.

Display escaping is prepared in PHP. getLabelHtml() and getHintHtml() return prepared Htmlable values, and class-backed components pass them to their views as labelHtml, hintHtml, valueHtml or titleHtml next to the raw text. Blade outputs prepared values with {{ }} without escaping them again; they serialize to strings. Templates do not read escaping configuration or call PHP helpers: all preparation happens in the components' view data. Raw labels and value keys remain available for serialization and attributes.

Anonymous Blade components used directly follow the standard Laravel idiom: plain strings are escaped, while Htmlable values such as HtmlString and Blade slots are output as trusted HTML. The global escapes.* settings apply to values prepared by class-backed components, not to raw strings passed directly to anonymous views.

Class-backed Blade components accept a local preference through :escape-label, for example <x-moonshine::action-button :label="$label" :escape-label="false" />. The constructor receives this preference before view data is prepared. A direct Blade Link displays its label when its slot is empty; an explicit slot takes precedence. Link passes its prepared label as $slot, so published link-native / link-button views keep working. Card labels also respect values, escapeLabel, and escapeValueLabels supplied through customView(). A label or title supplied through customView() data gets its labelHtml / titleHtml rebuilt with the component's preference, unless the prepared value is supplied too.

The Laravel view composer prepares the slot of link-native / link-button before Blade renders it. Direct view rendering accepts plain strings, Htmlable values and Blade slots; an absent or empty slot falls back to the prepared label. Collapse titles and Footer menu labels replaced through customView() also follow the component's escaping preference, while explicit labelHtml / menuLabelsHtml values take precedence. Card values and Footer menus supplied as iterators through customView() remain available after serialization and repeated rendering. Custom fields can override getExtensionsAttributes() to add extension attributes during rendering.

Custom implementations

Existing contracts are unchanged, so custom implementations keep working after the upgrade. Escaping is described by separate contracts:

HasLabelEscapingContract: escapeLabel(), unescapeLabel(), isEscapeLabel(), hasLabelEscapingOverride() and getLabelHtml(): Htmlable, supplied by the WithLabel trait,
HasHintEscapingContract: escapeHint(), unescapeHint(), isEscapeHint() and getHintHtml(): Htmlable, supplied by WithHint,
HasLinkNameEscapingContract: escapeLinkName(), unescapeLinkName() and isEscapeLinkName(), supplied by WithLink,
HasTitleEscapingContract: escapeTitle(), unescapeTitle() and isEscapeTitle() for modals and off-canvas panels,
HasRenderEscapingContract: the beforeRender() / afterRender() escaping methods of fields,
DisplayEscapingConfiguratorContract: the global defaults of a configurator,
HasEscapedValueContract: the value escape(), unescape() and isUnescape() methods supplied by WithEscapedValue, used by popover editing.

Implementations without these contracts use the defaults described above: escaping stays enabled, and configurable types follow the configurator when it implements DisplayEscapingConfiguratorContract. hasLabelEscapingOverride() reports whether a local preference was set, independently of its resolved value, so defaults can be inherited without overwriting explicit choices. Keep getLabel(): string raw for attributes, serialization and data operations, and use getLabelHtml() for display.

moonshine / ui

Package info

Security

Statistics

README

Display escaping

Custom implementations