PHPackages                             oxhq/canio - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF & Document Generation](/categories/documents)
4. /
5. oxhq/canio

ActiveLibrary[PDF & Document Generation](/categories/documents)

oxhq/canio
==========

Browser-grade PDF and document rendering for Laravel powered by Stagehand

v1.0.6(1mo ago)0120↓36.1%MITPHPPHP ^8.2

Since Mar 30Pushed 1mo agoCompare

[ Source](https://github.com/oxhq/canio-laravel)[ Packagist](https://packagist.org/packages/oxhq/canio)[ Docs](https://oxhq.github.io/canio/)[ RSS](/packages/oxhq-canio/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (18)Versions (8)Used By (0)

Canio Laravel Package
=====================

[](#canio-laravel-package)

`oxhq/canio` is the Laravel-facing package for Canio.

It keeps the API Laravel-native and delegates execution to the Stagehand runtime. In the default `embedded` mode, that runtime is installed and started automatically when the package needs it.

Supported Versions
------------------

[](#supported-versions)

- PHP `^8.2`
- Laravel `^10.0 | ^11.0 | ^12.0 | ^13.0`

Install
-------

[](#install)

```
composer require oxhq/canio
php artisan canio:install
```

Public docs: [oxhq.github.io/canio](https://oxhq.github.io/canio/)

The second command is recommended for deployment and validation because it:

- publishes the default config
- downloads the matching Stagehand binary
- downloads the Chrome for Testing browser bundle for local CDP rendering
- verifies release checksums
- runs a local doctor check

The package can also auto-install and auto-start the runtime on first render in `embedded` mode, but explicit install is the cleaner production path.

If you need the config file:

```
php artisan vendor:publish --tag=canio-config
```

Quick Start
-----------

[](#quick-start)

```
use Oxhq\Canio\Facades\Canio;

return Canio::view('pdf.invoice', ['invoice' => $invoice])
    ->profile('invoice')
    ->title('Invoice #123')
    ->stream('invoice.pdf');
```

Supported entrypoints:

- `Canio::view(...)`
- `Canio::html(...)`
- `Canio::url(...)`

Common terminal operations:

- `->render()`
- `->save(...)`
- `->download(...)`
- `->stream(...)`
- `->dispatch()`

When To Choose Canio
--------------------

[](#when-to-choose-canio)

Choose Canio when you need:

- real browser layout
- JavaScript execution before capture
- explicit readiness with `window.__CANIO_READY__`
- render artifacts for debugging
- async render jobs and runtime operations

Do not choose Canio only because you want the smallest possible cold-render time on a static HTML invoice. That is not the category this package is trying to win.

Runtime Model
-------------

[](#runtime-model)

### Embedded mode

[](#embedded-mode)

`embedded` is the default and recommended package experience.

- Laravel talks to Stagehand through the package
- the runtime is installed automatically when missing
- the runtime is auto-started on demand
- the application does not need a manually managed daemon in the happy path

### Remote mode

[](#remote-mode)

Use `remote` when you want Laravel to talk to an already-running Stagehand daemon.

Useful config keys:

- `runtime.mode`
- `runtime.base_url`
- `runtime.auto_install`
- `runtime.auto_start`
- `runtime.binary`
- `runtime.install_path`
- `runtime.startup_timeout`

Production deployment guide: [embedded vs remote runtimes](https://github.com/oxhq/canio/blob/main/docs/deployment.md)

Troubleshooting
---------------

[](#troubleshooting)

If the first render fails, check these first:

1. Run `php artisan canio:doctor`
2. Confirm `php artisan canio:install` succeeded
3. Confirm `php artisan canio:browser:install` succeeded, or set `CANIO_CHROMIUM_PATH`
4. In locked-down Linux environments, you may also need `CANIO_CHROMIUM_NO_SANDBOX=true`

Stagehand uses the Rod-backed native renderer by default:

```
CANIO_RENDERER_DRIVER=rod-cdp
CANIO_BROWSER_PRODUCT=chrome
CANIO_BROWSER_CHANNEL=Stable
CANIO_BROWSER_INSTALL_PATH=/var/lib/canio/browsers
```

`chrome` is the default browser product because Canio optimizes for browser-real PDF fidelity. `chrome-headless-shell` is available for controlled environments that prefer the lighter old-headless shell tradeoff:

```
CANIO_BROWSER_PRODUCT=chrome-headless-shell
```

To fall back to the direct CDP renderer without changing Laravel integration code:

```
CANIO_RENDERER_DRIVER=local-cdp
CANIO_BROWSER_INSTALL_PATH=/var/lib/canio/browsers
```

Useful browser bundle commands:

```
php artisan canio:browser:install
php artisan canio:browser:install --product=chrome-headless-shell
php artisan canio:browser:install 123.0.6312.86 --platform=linux64
php artisan canio:browser:repair
```

If the app server should use an external Chrome/CDP service instead of launching local Chromium:

```
CANIO_RENDERER_DRIVER=remote-cdp
CANIO_REMOTE_CDP_ENDPOINT=ws://chrome-renderer.internal:9222/devtools/browser/
```

If you want a self-hosted runtime instead of embedded mode:

```
CANIO_RUNTIME_MODE=remote
CANIO_RUNTIME_BASE_URL=http://127.0.0.1:9514
```

Benchmarks And Proof
--------------------

[](#benchmarks-and-proof)

Canio is positioned as the browser-grade option, not the minimum-latency static option.

The checked-in harnesses currently establish:

- Canio is the most faithful engine on the reference invoice fixture
- Canio beats Browsershot and Snappy on useful performance in that lane
- Canio executes runtime JavaScript correctly in the probe harness
- Dompdf and mPDF still win on raw uncached latency for simpler static renders

Public benchmark summary: [oxhq/canio benchmark summary](https://github.com/oxhq/canio/blob/main/docs/benchmark-summary.md)
Full harnesses: [oxhq/canio benchmarks](https://github.com/oxhq/canio/blob/main/benchmarks/README.md)

Optional Cloud Layer
--------------------

[](#optional-cloud-layer)

This package works without any cloud dependency.

Cloud is an optional paid layer on top of Canio OSS. Keep it secondary in the package story: local or self-hosted rendering is fully supported without it.

Commands And Operations
-----------------------

[](#commands-and-operations)

The package also exposes runtime and job commands such as:

- `php artisan canio:install`
- `php artisan canio:doctor`
- `php artisan canio:serve`
- `php artisan canio:runtime:status`
- `php artisan canio:runtime:job {id}`
- `php artisan canio:runtime:artifact {id}`
- `php artisan canio:runtime:cleanup`

The facade also exposes job and artifact helpers, including:

- `Canio::job($jobId)`
- `Canio::jobs($limit = 20)`
- `Canio::artifact($artifactId)`
- `Canio::artifacts($limit = 20)`
- `Canio::retryJob($jobId)`
- `Canio::cancelJob($jobId)`
- `Canio::replay($artifactId)`

More Documentation
------------------

[](#more-documentation)

- Public docs: [oxhq.github.io/canio](https://oxhq.github.io/canio/)
- Monorepo overview: [oxhq/canio](https://github.com/oxhq/canio)
- Production deployment guide: [deployment guide](https://github.com/oxhq/canio/blob/main/docs/deployment.md)
- Contributor setup: [development guide](https://github.com/oxhq/canio/blob/main/docs/development.md)
- Architecture notes: [architecture](https://github.com/oxhq/canio/blob/main/docs/architecture.md)
- Render contract: [render contract](https://github.com/oxhq/canio/blob/main/docs/render-contract.md)

###  Health Score

43

—

FairBetter than 90% of packages

Maintenance91

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 61.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~8 days

Total

7

Last Release

42d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a1e66a354a710e1b8f3254cb843ed74159bb261809a3deaccfff898bfcbdee7a?d=identicon)[garaekz](/maintainers/garaekz)

---

Top Contributors

[![garaekz](https://avatars.githubusercontent.com/u/14919842?v=4)](https://github.com/garaekz "garaekz (11 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (7 commits)")

---

Tags

browser-renderingchromiumlaravelpdflaravelpdfchromiumdocumentsstagehandbrowser-renderinghigh-fidelity

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/oxhq-canio/health.svg)

```
[![Health](https://phpackages.com/badges/oxhq-canio/health.svg)](https://phpackages.com/packages/oxhq-canio)
```

###  Alternatives

[larastan/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

6.4k51.0M7.6k](/packages/larastan-larastan)[laravel/ai

The official AI SDK for Laravel.

1.0k2.1M162](/packages/laravel-ai)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77018.2M121](/packages/laravel-mcp)[illuminate/queue

The Illuminate Queue package.

20432.2M1.5k](/packages/illuminate-queue)[spatie/laravel-responsecache

Speed up a Laravel application by caching the entire response

2.8k8.7M64](/packages/spatie-laravel-responsecache)[spatie/laravel-health

Monitor the health of a Laravel application

87411.3M154](/packages/spatie-laravel-health)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)