包简介

Builder.io integration for Laravel.

README 文档

README

Laravel package for Builder.io integration for rendering content on your own, instead of using Builder.io API and CDN.

While it is completely possible to leverage just Visual Editor of the Builder.io and render content without relying on Builder.io API, the functionality is limited. When using Builder.io API, they take care of targeting, localization and utilization of other features such as symbols, content data etc. When rendering content on your own, you have to take care of targeting, symbol resolution and content preparation for rendering.

This package helps a with retrieving content from Builder.io and storing it in the database for later rendering directly by just reading the database and not querying Builder.io API on each page render.

Features

store Builder.io content in the database
automatically update database content as soon as something changes in Builder.io, utilizing Builder.io global webhooks
download image and video assets to Laravel Storage without need to use CDN
Symbol support when retrieving content

Installation

To install the package, just run:

composer require stacktrace/laravel-builder

After installing, configure following environment variables:

# The Builder.io Public API key, can be found in settings
BUILDER_PUBLIC_API_KEY=123
# The Builder.io Private API key, can be found in settings as well
BUILDER_PRIVATE_KEY=123
# Random string for protecting webhook calls
BUILDER_WEBHOOK_TOKEN=somerandomstring

Then on Builder.io side, you have to configure webhook. Open Space Settings and within Integrations section, click on "Edit" next to Global Webhooks. Register the following webhook:

URL: https://your-laravel-app.com/__builder_webhook__
Headers:
    Authorization: somerandomstring

Set the Authorization header value to the BUILDER_WEBHOOK_TOKEN env variable.

Usage

Rendering pages

To render a page, first you have to prepare a controller. The package supports simple path targeting, so you can use single path target on your pages.

First, create controller for resolving content from current request:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Inertia\Inertia;
use StackTrace\Builder\Facades\Builder;

class BuilderPageController extends Controller
{
    public function __invoke(Request $request)
    {
        $page = Builder::resolvePageFromRequest($request);

        abort_if(is_null($page), 404);

        return Inertia::render('BuilderPage', [
            'title' => $page->title,
            'content' => $page->getContent(),
        ]);
    }
}

Then in web.php register this controller as fallback controller, since we want to dynamically render page based on path targeting:

Route::fallback(BuilderPageController::class);

In the Builder.io, set targeting of your page to something like urlPath is /test. Provided that you do not have a route registered on the /test path, the fallback controller will engage, and Builder::resolvePageFromRequest will search for a page on /test path.

You can now render the content directly using Builder.io SDK like following:

<template>
  <Head :title="title"/>

  <Content :content="content" api-key="@" :can-track="false" />
</template>

<script setup lang="ts">
import { Content } from "@builder.io/sdk-vue";
import { Head } from "@inertiajs/vue3";

defineProps<{
  content: object
  title: string
}>()
</script>

Builder editor

To be able to edit pages, within Builder.io on your site, create separate controller for handling editor requests:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Inertia\Inertia;
use StackTrace\Builder\Facades\Builder;

class BuilderEditorController extends Controller
{
    public function __invoke(Request $request)
    {
        $editor = Builder::resolveEditorFromRequest($request);

        abort_if(is_null($editor), 404);

        App::setLocale($editor->locale);

        return Inertia::render('BuilderEditorPage', [
            'apiKey' => $editor->apiKey,
            'model' => $editor->model,
            'url' => $editor->url,
        ]);
    }
}

Register controller in web.php:

Route::get('__builder_editing__', BuilderEditorController::class);

Then render editor content using Builder.io SDK:

<template>
  <Content
      v-if="content"
      :content="content"
      :api-key="apiKey"
      :model="model"
      :can-track="false"
  />
</template>

<script setup lang="ts">
  import { Content, fetchOneEntry } from '@builder.io/sdk-vue'
  import { onMounted, shallowRef } from "vue";

  const props = defineProps<{
    apiKey: string
    model: string
    url: string
  }>()

  const content = shallowRef<any>(null)

  onMounted(async () => {
    content.value = await fetchOneEntry({
      model: props.model,
      apiKey: props.apiKey,
      userAttributes: {
        urlPath: props.url,
      }
    })
  })
</script>

Note that we now we are using fetchOneEntry to render content using Builder.io API. This is however necessary for editor to work.

Then in your model settings, use a dynamic editor URL. Enter the following URL:

return `https://your-laravel-app.com/__builder_editing__?path=${targeting.urlPath || ''}&locale=${content.data.locale || ''}&model=${content.modelId}`;

The editor will now use your app instead of Builder.io preview page.

Localization

While localization is a premium feature in Builder.io, you can use simple field to store locale of your content. Just define a field in your model settings named locale. When receiving webhooks, the package looks for fields and if it finds a field named locale, it will store it in local column. The Builder::resolveEditorFromRequest will respect locale settings with following rules:

first retrieve content where locale is matching App:getLocale()
if the locale is not matching App::getLocale(), the content where locale matches App::getFallbackLocale() is retrieved
if content fallback locale does not exist either, the content where locale is not set is retrieved

stacktrace/laravel-builder 适用场景与选型建议

stacktrace/laravel-builder 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 60 次下载、GitHub Stars 达 2，最近一次更新时间为 2024 年 03 月 27 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 stacktrace/laravel-builder 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 stacktrace/laravel-builder 我们能提供哪些服务？

定制开发 / 二次开发

基于 stacktrace/laravel-builder 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

stacktrace/laravel-builder

包简介