TextBuilder

TextBuilder とは

TextBuilder は、Bluesky の AT Protocol が定義する facets（リッチテキスト注釈）をメソッドチェーンで組み立てるためのクラスです。 Bluesky の投稿本文はプレーンテキストですが、メンション・リンク・ハッシュタグを表示するためにはテキスト中の位置（バイトオフセット）と種別を示す facets 配列を一緒に送る必要があります。TextBuilder はこのオフセット計算と配列構築を自動的に行います。

基本的なテキスト作成

TextBuilder::make()

TextBuilder::make() で初期テキストを指定してインスタンスを生成します。初期テキストは省略可能です。

use Revolution\Bluesky\RichText\TextBuilder;

$builder = TextBuilder::make(text: 'Hello Bluesky');

text()

text() でテキストを末尾に追加します。

$builder = TextBuilder::make()
    ->text('Hello ')
    ->text('Bluesky');

// $builder->text === 'Hello Bluesky'

newLine()

改行を追加します。count で行数を指定できます（デフォルト: 1）。

$builder = TextBuilder::make('1行目')
    ->newLine()
    ->text('2行目')
    ->newLine(count: 2)
    ->text('4行目');

toPost()

TextBuilder インスタンスを Post レコードに変換します。Bluesky::post() に直接渡せます。

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\RichText\TextBuilder;

$post = TextBuilder::make('シンプルな投稿')->toPost();

$response = Bluesky::withToken()->post($post);

Post::build()

Post::build() にクロージャを渡す方法でも使えます。戻り値が Post になります。

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Record\Post;
use Revolution\Bluesky\RichText\TextBuilder;

$post = Post::build(function (TextBuilder $builder) {
    $builder->text('Hello Bluesky');
});

$response = Bluesky::withToken()->post($post);

メンション（`@mention`）の追加

mention() でメンション facet を追加します。

$builder->mention(text: '@alice.bsky.social');

DID の自動解決

did を省略すると、ハンドルから DID を自動解決します（Bluesky::resolveHandle() が呼ばれます）。

// DID を自動解決（API 呼び出しが発生します）
$builder->mention('@alice.bsky.social');

DID を明示指定

DID が既にわかっている場合は明示的に渡すことで API 呼び出しを回避できます。

// DID を直接指定（推奨: API 呼び出しなし）
$builder->mention(text: '@alice.bsky.social', did: 'did:plc:xxxxxxxxxxxxxxxxxxxx');

本番環境でメンションを多用する場合は、DID をキャッシュしておくと API 呼び出しを削減できます。

リンク（URL）の埋め込み

link() でリンク facet を追加します。

// URL そのものを表示テキストにする
$builder->link('https://laravel.com');

// 表示テキストと URL を別々に指定
$builder->link(text: 'Laravel 公式サイト', uri: 'https://laravel.com');

uri を省略すると text がそのまま URI として使われます。

ハッシュタグの追加

tag() でハッシュタグ facet を追加します。

// # から始まるテキストを渡すとタグを自動抽出
$builder->tag('#Laravel');

// タグ文字列を明示指定（# なしの文字列）
$builder->tag(text: '#Laravel', tag: 'Laravel');

複合テキストの構築

複数の facet を組み合わせてリッチな投稿テキストを作れます。

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\RichText\TextBuilder;

$post = TextBuilder::make('新しい記事を公開しました！')
    ->newLine(count: 2)
    ->mention('@alice.bsky.social', did: 'did:plc:xxxx')
    ->text(' さんにもぜひ読んでほしいです。')
    ->newLine()
    ->link(text: '記事を読む', uri: 'https://example.com/article/1')
    ->newLine()
    ->tag('#Laravel')
    ->text(' ')
    ->tag('#PHP')
    ->toPost();

$response = Bluesky::withToken()->post($post);

Post::build() を使った記述

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Record\Post;
use Revolution\Bluesky\RichText\TextBuilder;

$post = Post::build(function (TextBuilder $builder) {
    $builder->text('新しい記事を公開しました！')
            ->newLine(count: 2)
            ->mention('@alice.bsky.social', did: 'did:plc:xxxx')
            ->text(' さんにもぜひ読んでほしいです。')
            ->newLine()
            ->link(text: '記事を読む', uri: 'https://example.com/article/1')
            ->newLine()
            ->tag('#Laravel')
            ->text(' ')
            ->tag('#PHP');
});

$response = Bluesky::withToken()->post($post);

投稿との統合

Bluesky::post() との組み合わせ

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\RichText\TextBuilder;

$post = TextBuilder::make('test')
    ->newLine()
    ->link('https://bsky.app/')
    ->toPost();

$response = Bluesky::withToken()->post($post);

Notification チャンネルとの組み合わせ

BlueskyChannel の toBluesky() メソッドで Post::build() を使えます。

use Illuminate\Notifications\Notification;
use Revolution\Bluesky\Notifications\BlueskyChannel;
use Revolution\Bluesky\Record\Post;
use Revolution\Bluesky\RichText\TextBuilder;

class DeployedNotification extends Notification
{
    public function __construct(
        private string $url,
    ) {}

    public function via(object $notifiable): array
    {
        return [BlueskyChannel::class];
    }

    public function toBluesky(object $notifiable): Post
    {
        return Post::build(function (TextBuilder $builder) {
            $builder->text('デプロイが完了しました')
                    ->newLine()
                    ->link(text: '確認する', uri: $this->url)
                    ->newLine()
                    ->tag('#Laravel');
        });
    }
}

テキスト中の @mention・URL・#hashtag を自動で検出して facets を設定することもできます。

use Revolution\Bluesky\RichText\TextBuilder;

$builder = TextBuilder::make('@alice.bsky.social test https://example.com #alice')
    ->detectFacets();

// detectFacets() 後にさらに facets を追加することも可能
$builder->newLine()->tag('#bob');

$post = $builder->toPost();

detectFacets() は正規表現ベースの検出です。確実にリンクしたい場合は link()・mention()・tag() を明示的に使う方が確実です。

facet() メソッドで任意の facet 配列を直接追加できます。

use Revolution\Bluesky\RichText\TextBuilder;

$builder = TextBuilder::make();

$builder->facet([
    'index' => [
        'byteStart' => 0,
        'byteEnd' => 5,
    ],
    'features' => [
        [
            '$type' => 'app.bsky.richtext.facet#link',
            'uri' => 'https://example.com',
        ],
    ],
]);

文字数制限と注意事項

バイトオフセットと grapheme

AT Protocol の facet インデックスは UTF-8 バイトオフセットで指定します。TextBuilder は内部で strlen() を使ってバイト数を計算しています。日本語・絵文字などのマルチバイト文字は 1 文字でも複数バイトを消費するため、文字数ではなくバイト数でオフセットが決まります。

// 'Hello' は UTF-8 で 5 バイト（1 文字 = 1 バイト）
// '日本語' は UTF-8 で 9 バイト（1 文字 = 3 バイト）
$builder = TextBuilder::make('日本語');
// strlen($builder->text) === 9

投稿の文字数制限

Bluesky の投稿は grapheme（表示上の文字数）で最大 300 文字です。バイト数ではなく grapheme で制限されるため、日本語でも 300 文字書けます。

use Illuminate\Support\Str;

$text = 'これが投稿テキストです。';

// grapheme での文字数確認
$length = Str::length($text); // mb_strlen() と同等

TextBuilder 自体は文字数チェックを行いません。300 grapheme を超える投稿を送ると AT Protocol API がエラーを返します。

メソッド一覧

メソッド	説明
`TextBuilder::make(string $text = '')`	インスタンスを生成
`text(string $text)`	テキストを末尾に追加
`newLine(int $count = 1)`	改行を追加
`mention(string $text, ?string $did = null)`	メンション facet を追加
`link(string $text, ?string $uri = null)`	リンク facet を追加
`tag(string $text, ?string $tag = null)`	ハッシュタグ facet を追加
`detectFacets()`	テキストから facets を自動検出
`facet(array $facet)`	カスタム facet を追加
`resetFacets()`	全 facets をリセット
`toPost()`	`Post` レコードへ変換
`toArray()`	`['text' => ..., 'facets' => ...]` 配列へ変換

Source: src/RichText/TextBuilder.php

GitHub Copilot

SDK

AI SDK

VOICEVOX

スターターキット

フィード・RSS

ミドルウェア

TextBuilder とは

基本的なテキスト作成

TextBuilder::make()

text()

newLine()

toPost()

Post::build()

メンション（`@mention`）の追加

DID の自動解決

DID を明示指定

リンク（URL）の埋め込み

ハッシュタグの追加

複合テキストの構築

Post::build() を使った記述

投稿との統合

Bluesky::post() との組み合わせ

Notification チャンネルとの組み合わせ

facets の自動検出

カスタム facet の追加

文字数制限と注意事項

バイトオフセットと grapheme

投稿の文字数制限

メソッド一覧

​TextBuilder とは

​基本的なテキスト作成

​TextBuilder::make()

​text()

​newLine()

​toPost()

​Post::build()

​メンション（@mention）の追加

​DID の自動解決

​DID を明示指定

​リンク（URL）の埋め込み

​ハッシュタグの追加

​複合テキストの構築

​Post::build() を使った記述

​投稿との統合

​Bluesky::post() との組み合わせ

​Notification チャンネルとの組み合わせ

​facets の自動検出

​カスタム facet の追加

​文字数制限と注意事項

​バイトオフセットと grapheme

​投稿の文字数制限

​メソッド一覧

TextBuilder とは

基本的なテキスト作成

TextBuilder::make()

text()

newLine()

toPost()

Post::build()

メンション（`@mention`）の追加

DID の自動解決

DID を明示指定

リンク（URL）の埋め込み

ハッシュタグの追加

複合テキストの構築

Post::build() を使った記述

投稿との統合

Bluesky::post() との組み合わせ

Notification チャンネルとの組み合わせ

facets の自動検出

カスタム facet の追加

文字数制限と注意事項

バイトオフセットと grapheme

投稿の文字数制限

メソッド一覧