Canvas Headless Publishing for Laravel

If you want a ready-to-use public blog, run the canvas:ui command. This publishes Blade views, a controller stub, and routes to your application, providing a starter reader frontend at the /canvas-ui path.

php artisan canvas:ui

Configure webhooks in Admin → Integrations → Webhooks. Canvas sends signed JSON POST requests to your HTTPS URL upon lifecycle events: publish, schedule, update, unpublish, and delete.

Payload Content: Includes metadata (slug, title, summary, featured image, SEO meta, topic/tags, author) but does not include the full HTML body.

Recommended Workflow:

1. Receive the event (e.g., post.published).
2. Fetch the full post in your application using Eloquent (e.g., Post::published()->where('slug', ...)).
3. Revalidate your cache, rebuild static pages, or purge your CDN.

To install Canvas, require the package via Composer and run the installation Artisan command. Canvas requires PHP >= 8.3 and Laravel >= 12. It uses your application's existing authentication (defaulting to the web guard).

composer require austintoddj/canvas
php artisan canvas:install

For minor and patch updates, update the package via Composer and then run the canvas:publish command to ensure assets are updated.

Note: Major versions may contain breaking changes; refer to the official upgrade guide for those instances.

composer update austintoddj/canvas
php artisan canvas:publish

To quickly set up a Blade-based reader frontend, run the canvas:ui artisan command. This publishes views, a controller stub, and routes, and automatically appends the necessary route requirement to your routes/web.php file.

Use the --force flag to overwrite existing files if you are re-installing or resetting the UI.

php artisan canvas:ui

The post.body field contains HTML generated by the TipTap editor, not Markdown. When rendering on a custom frontend, you should treat the body as unescaped HTML (e.g., using {!! $post->body !!} in Blade) because it is written by authenticated users.

Key Styling Requirements:

• Wrap the body HTML in a root element with the class canvas-post-body.
• Use CSS to handle specific block types like img.canvas-post-body-image, pre.canvas-post-body-code, and table.canvas-post-body-table.
• For embeds (YouTube, Vimeo, X/Twitter), ensure you apply responsive aspect ratios (e.g., 16:9 for videos).
• Important: X/Twitter cards require a JavaScript resize listener to handle height changes reported via postMessage. You can reuse the pattern found in resources/js/lib/posts/iframe-resize.ts or the logic in the Canvas UI partial ui/partials/embeds.blade.php.

The following keys in config/canvas.php affect how the admin and frontend interact:

To ensure Canvas assets are automatically published whenever you run composer update, add the canvas:publish command to the post-update-cmd section of your application's composer.json file.

{
    "scripts": {
        "post-update-cmd": ["@php artisan canvas:publish --ansi"]
    }
}

Media uploads use the disk and path defined in config('canvas.storage_disk') and storage_path. By default, these are the public disk and the canvas/ prefix.

Post bodies and featured images often store root-relative paths (e.g., /storage/canvas/...). Ensure your storage is linked via php artisan storage:link (which canvas:install does automatically) or that your custom CDN/disk is configured to serve these paths correctly. For absolute URLs (e.g., for Open Graph), use helpers like Canvas\Support\MediaUrl or PostSeo.

To generate SEO-friendly metadata (title, description, canonical URL, image URL, etc.) for a post, use the PostSeo::resolve method. This is recommended for custom frontends to ensure consistency with the Canvas UI.

use Canvas\Support\PostSeo;

$seo = PostSeo::resolve($post, url()->current());
// Returns object with: title, description, canonical_url, image_url, image_alt

Use the following patterns to retrieve posts associated with specific tags, topics, or authors via Eloquent.

use Canvas\Models\Tag;
use Canvas\Models\Topic;
use Canvas\Models\CanvasUser;
use Canvas\Models\Post;

// Get posts by Tag
$tag = Tag::firstWhere('slug', $slug);
$posts = $tag->posts()->published()->with(['user', 'topic'])->latest()->paginate();

// Get posts by Topic
$topic = Topic::firstWhere('slug', $slug);
$posts = $topic->posts()->published()->with(['user', 'tags'])->latest()->paginate();

// Get posts by Author (CanvasUser)
$canvasUser = CanvasUser::query()->where('username', $username)->firstOrFail();
$posts = Post::query()
    ->where('user_id', $canvasUser->user_id)
    ->published()
    ->latest()
    ->paginate();