Polyscope Laravel Package

Getting Started

Confirm what you're installing before you plan around it. The three source documents disagree: the package description says "Laravel SDK for the Polyscope API," the feature list describes composing multiple Livewire components on one page, and the two prior assessments evaluate it as a polymorphic query-scope helper. Only one can be true, and the Livewire reading is the one that matches Beyond Code's actual product. Spend ten minutes here:

composer require beyondcode/polyscope
cat vendor/beyondcode/polyscope/composer.json   # does it require livewire/livewire?
ls vendor/beyondcode/polyscope/src
cat vendor/beyondcode/polyscope/src/*ServiceProvider.php

If require contains livewire/livewire, you have the component-composition package and everything below applies. If it contains guzzlehttp/guzzle, it's an API client — stop. If it contains neither and only touches illuminate/database, it's the query-scope package and you should re-scope entirely.

Install and wire it once.

composer require beyondcode/polyscope
php artisan vendor:publish --provider="BeyondCode\Polyscope\PolyscopeServiceProvider"
php artisan vendor:publish --tag=livewire:assets   # if not already public
php artisan config:clear && php artisan view:clear

With 0 dependents, do not assume auto-discovery is configured, and check the vendor composer.json for extra.laravel.providers. Pin the exact version ("beyondcode/polyscope": "1.0.0", not ^1.0) — you are the only one who will notice a breaking patch.

First use case: a dashboard with three independent components. Pick a page where the components genuinely don't need to share state — a KPI tile row, an activity feed with its own pagination, and a filter form that only affects the feed. Compose them in one Blade view and confirm that clicking "next page" on the feed re-renders only the feed. That single test tells you whether the package is doing what it claims or whether it's just a thin wrapper over @livewire. If the KPI tiles flicker on every feed pagination, the isolation isn't working and the rest of the value proposition is void.

Implementation Patterns

One component, one concern, one round trip. The whole point of multiple roots is that each has an independent lifecycle. If your Feed component also renders the KPI numbers, you've rebuilt a monolith with extra steps. Keep components small enough that the payload on a single Livewire request stays a few kilobytes.

{{-- resources/views/dashboard.blade.php --}}
<x-app-layout>
    <div class="grid grid-cols-3 gap-6">
        @livewire('dashboard.kpis')
        @livewire('dashboard.filters')
        @livewire('dashboard.feed')
    </div>
</x-app-layout>

Prefer sibling composition over deep nesting. Siblings communicating via events is debuggable; a four-level nest of @livewire where the innermost emits to a grandparent is not. When two components must share state, either lift it into a parent component or use events:

// Filters.php
public function updatedStatus(): void
{
    $this->emit('feed:filter', $this->status);
}

// Feed.php
protected $listeners = ['feed:filter' => 'applyFilter'];

Note that emit broadcasts to every listening component on the page, not just the one you have in mind. With three components on a page, a sloppy event name will wake all of them.

Keep URL state namespaced per component. Two paginated components on one page both defaulting to ?page= is the most common multi-root bug. Use Livewire's $queryString deliberately and give each component distinct keys (feedPage, auditPage) or keep pagination out of the URL entirely.

Treat routed components as a different mode. If you're pointing a route at a Livewire class, remember that the route model binding, the mount() signature, and the layout are all coming from the framework, not the package. Keep route-bound components free of assumptions about sibling components that only exist on the composed page.

Pass stable keys when composing in a loop. Any @livewire inside a @foreach needs a key, or Livewire will reuse the wrong component instance after a collection shifts:

@foreach ($widgets as $widget)
    @livewire('dashboard.widget', ['type' => $widget->type], key('widget-'.$widget->id))
@endforeach

Test components individually, then test the page. Use Livewire::test() for each component's behaviour — it's fast and isolates the failure. Add one feature test that asserts the page renders all roots and that a request to one component doesn't 500 the others. Don't try to unit-test the composition itself; the browser is the only honest test for "does this page hold together."

Isolate the vendor surface. Wrap the page assembly in a layout component or a small Blade partial so that @livewire calls and any package-specific directives live in one or two files. When the package stalls against a Livewire major, the replacement is a mechanical edit rather than an archaeology project.

Gotchas and Tips

Verify the package's identity before you build a single pattern on top of it. This is the dominant risk and it is cheap to eliminate. Two prior evaluations of the same repo produced two completely different, mutually incompatible integration plans. Ten minutes in src/ costs nothing compared to a sprint spent integrating the wrong layer.

Check the Livewire major version compatibility first, not later. Polyscope targets Livewire's earlier lifecycle model. Livewire 3 rewrote component bootstrapping, $emit became $dispatch, $listeners became #[On], and the wire: script injection changed. A package with zero dependents will not have been quietly patched for it. Run composer show livewire/livewire and cross-reference the package's require constraint before assuming the directives in your app will work. If you're on Livewire 3, the honest answer may be "don't adopt this."

Component count is a real cost. Every root component is a separate hydration payload and a separate endpoint. Three is fine. Twenty is a page that ships a megabyte of JSON and takes four round trips to settle. If you find yourself generating roots in a loop over a data set, you want one component with a list inside it, not N components.

Duplicate JS is the silent failure mode. Each component's @push('scripts') and document.addEventListener('livewire:load', ...) runs per component. On a single-root page you'd never notice; with three roots you get triple-registered listeners and duplicated analytics events. Guard with @once in Blade and an initialised flag in your Alpine/JS.

Debug at the network layer, not the PHP layer. Open the network tab, click something in one component, and read the request payload. You want to see one request, one component name, and a small snapshot. If you see three component names in the payload, the isolation isn't working. If the payload contains the entire page state, you've effectively lost the benefit and should fall back to a single component.

Blade directives from the package may not be idempotent. If the README tells you to add something to your layout (a directive, a script tag, a @stack), adding it to a layout that is rendered once per page is fine — adding it to a component view that renders per root is not. Check where you placed it.

Errors surface per component, so your error pages won't. A ModelNotFoundException in one root gives you a broken fragment, not a 404 page. Add explicit try/catch around data loading in components that live alongside others, and surface a degraded state in the fragment rather than letting the whole page layout render around a dead component.

You are the maintainer now. Zero stars, zero dependents, single maintainer: pin the version, keep vendor imports to a handful of files, and record the last release date against your Laravel upgrade cadence. Write a five-line test that asserts each composed page renders all expected component roots — that test will tell you the day an upgrade breaks the composition, which is otherwise a silent visual regression nobody reports.