Skip to content

Marble Facade API

Jump to bottom
Phillip Dornauer edited this page Apr 14, 2026 · 4 revisions

Marble Facade API

All methods are available via Marble:: in Blade templates and PHP code.

use Marble\Admin\Facades\Marble;

Routing

Marble::routes(callable $handler, string $prefix = '')

Registers the catch-all route. Place in routes/web.php after all custom routes.

Marble::routes(function ($item) {
    return view(Marble::viewFor($item), ['item' => $item]);
});

Marble::viewFor(Item $item): string

Returns the Blade view name for an item.

Item Retrieval

Marble::item(int $id): ?Item

Get a single item by ID (cached).

Marble::resolve(string $path): ?Item

Resolve a URL path to a published item.

Marble::resolveOrFail(string $path): Item

Resolve a URL path or throw a 404.

Marble::findItem(string $blueprint, string $field, string $value, $language = null): ?Item

Find an item by a field value.

$member = Marble::findItem('team_member', 'email', 'alice@example.com');

Marble::items(string $blueprint): ItemQuery

Fluent query builder for items of a blueprint.

Marble::items('blog_post')
    ->published()
    ->under(10)
    ->orderBy('created_at', 'desc')
    ->paginate(10);

Query methods:

Method Returns
->published() Only published items
->under(int $id) Only children of this item
->orderBy($col, $dir) Sort
->get() Collection
->paginate(int $n) LengthAwarePaginator
->first() Item|null
->count() int
->query() Eloquent Builder

Content Structure

Marble::children(Item $item, ?string $blueprint = null, string $status = 'published'): Collection

Marble::children($item)                      // all published children
Marble::children($item, 'blog_post')         // filtered by blueprint
Marble::children($item, null, 'draft')       // drafts only
Marble::children($item, null, 'all')         // all statuses

Marble::navigation(?int $rootItemId = null, int $depth = 99): Collection

Navigation tree. Only published items with show_in_nav = true are included. Children available via $item->navChildren.

Without an argument, starts at the current site's root_item_id (fallback: config('marble.entry_item_id')). Pass an explicit ID to build a navigation from any subtree — useful for footer links, sidebar menus, etc.

Marble::navigation()          // site root → main navigation
Marble::navigation(42)        // subtree rooted at item 42
Marble::navigation(42, 1)     // one level deep only
Marble::navigation(null, 2)   // site root, max 2 levels

Marble::breadcrumb(Item $item): Collection

Ancestor chain from root to item.

URL Generation

Marble::url(Item $item, $locale = null): string

Marble::url($item)           // current language
Marble::url($item, 'de')     // German
Marble::url($item, 2)        // by language ID

Site & Settings

Marble::currentSite(): ?Site

Active site for current request.

Marble::settings(): ?Item

Settings item for current site.

{{ Marble::settings()?->value('site_name') }}

Language

Method Description
Marble::setLocale(string $code) Set language by code
Marble::setLanguageById(int $id) Set language by ID
Marble::currentLanguageId() Get current language ID
Marble::primaryLanguageId() Get primary language ID

Portal Authentication

Method Returns
Marble::isPortalAuthenticated() bool
Marble::portalUser() PortalUser|null

Cache

Marble::invalidateItem(Item $item): void

Clear cache for item and all ancestors. Called automatically on save.

Custom Field Types

Marble::registerFieldType(FieldTypeInterface $ft): void

Register a custom field type. Call from a service provider's boot() method.

Marble::registerFieldType(new MyCustomFieldType());

Marble::fieldTypes(): array

Get all registered field types.

Marble::fieldType(string $identifier): ?FieldTypeInterface

Get a field type by identifier.

A/B Testing

Method Returns Description
Marble::recordAbConversion(Item $item) void Record a conversion for the bucket the current visitor is assigned to
Marble::activeVariantId() int|null ID of the active variant for the current request
Marble::activeVariantItemId() int|null ID of the item the active variant belongs to
Marble::setActiveVariantId(int $variantId, int $itemId) void Set by MarbleRouter during resolution — not for manual use

Marble::recordAbConversion(Item $item)

Call this after the desired goal action in your own controller. Marble reads the visitor's marble_ab_{item_id} cookie and increments the correct conversion counter. No cookie = no-op.

// After a form submit, purchase, signup, etc.:
Marble::recordAbConversion($item);

See A/B Testing for full details on conversion tracking and the sidebar widget.

A/B variant resolution happens automatically in MarbleRouter. Templates do not need to call these methods — $item->value() already returns the correct variant value.

Subscriptions

Item subscriptions are managed in the admin UI (Watch/Unwatch button). No facade methods are needed in templates.

For custom notification dispatching from your own code, fire events or call notifySubscribers() on the item directly via the ItemSubscription model:

use Marble\Admin\Models\ItemSubscription;

$subscriberIds = $item->subscriberIds(); // Collection of user IDs

Clone this wiki locally