juphyter · PHPstats

juphyter runs PHP code in notebooks and in Quarto documents.

A notebook is a file of cells. Each cell holds a few lines of code, and its output appears directly beneath it: text, a table, or a chart. The program that runs the cells is called a kernel, and it keeps one PHP session open, so a variable set in one cell is available in the next. JupyterLab is the usual application for editing and running notebooks. Quarto renders a Markdown document with code cells into HTML, PDF, or Word, running each cell and placing its output in the document.

juphyter is that kernel for PHP. After juphyter install, JupyterLab lists PHP in its launcher, and Quarto runs the {php} cells of any .qmd that names the kernel in its front matter. It is meant for statistical and exploratory work with the phpstats packages: load data, try a pipeline, look at the table or the plot it produces, and change the code until the result is right.

What a cell shows

The value of a cell’s last expression is its output. A phibble data frame appears as an HTML table with its dimensions and column types, and a phiz plot appears as a chart. Other values appear as a compact dump.

$mpg = \Phibble\DataFrame::fromRows(\Phiz\Datasets::mpg());

$mpg |>
    group_by('class') |>
    summarize(models: n(), hwy: mean('hwy')) |>
    arrange(desc('hwy'));

A tibble: 7 × 3

	class <chr>	models <int>	hwy <dbl>
1	compact	47	28.297872340426
2	subcompact	35	28.142857142857
3	midsize	41	27.292682926829
4	2seater	5	24.8
5	minivan	11	22.363636363636
6	suv	62	18.129032258065
7	pickup	33	16.878787878788

$mpg = \Phibble\DataFrame::fromRows(\Phiz\Datasets::mpg());

phplyr($mpg)
    ->groupBy('class')
    ->summarize(models: n(), hwy: mean('hwy'))
    ->arrange(desc('hwy'))
    ->get();

A tibble: 7 × 3

	class <chr>	models <int>	hwy <dbl>
1	compact	47	28.297872340426
2	subcompact	35	28.142857142857
3	midsize	41	27.292682926829
4	2seater	5	24.8
5	minivan	11	22.363636363636
6	suv	62	18.129032258065
7	pickup	33	16.878787878788

\Phiz\Plot::of(\Phiz\Datasets::mpg())
    ->aes(x: 'displ', y: 'hwy', color: 'drv')
    ->point(opacity: 0.7)
    ->smooth(method: 'lm')
    ->labs(x: 'Displacement (L)', y: 'Highway mpg', color: 'Drive');

Highway mileage against engine displacement.

What the kernel provides

State across cells, including use imports and declared functions and classes.
Tracebacks that name the cell and the line, instead of eval()'d code.
HTML tables for phibble data frames and charts for phiz plots, plus toHtml() and toMimeBundle() hooks for any other class.
Juphyter\display(), which shows a value part way through a cell.
Completion of variables, functions, classes, and members.
Interrupting a running cell with the stop button, when PHP has the pcntl extension.
Loading the nearest vendor/autoload.php above the notebook, so a notebook inside a Composer project can use that project’s classes and packages.

juphyter requires none of the phpstats packages. It runs plain PHP, and it formats a phibble data frame or a phiz plot when those packages are installed.

How it works

The kernel has two processes. A small Python program built on ipykernel handles the Jupyter protocol, and a PHP process runs the cells. They talk over a Unix socket. This is why an install needs a Python with ipykernel as well as PHP, and why the kernel runs on macOS and Linux only.

Installation covers the requirements and the install commands, and Getting started walks through a first notebook.