Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 99 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# JpGraph demo gallery

A tiny, self-contained way to **spin up** this library and see it render real
charts. Each endpoint uses the Composer loader in `lib/JpGraph.php` and streams
a PNG generated on request.

## Requirements

- PHP with the **GD** extension (`php -m | grep gd`)
- No Composer install needed — the loader and library are vendored in `lib/`

Tested on PHP 8.4. JpGraph 4.4.3 already handles the PHP 8.1+/9 deprecations on
the standard rendering paths, and this branch closes the remaining gaps (see the
PHP 9 note below). `_bootstrap.php` still mutes `E_DEPRECATED` for these
endpoints as a defensive measure, so a stray notice can never leak into the PNG
byte stream.

## Run it

From the repository root:

```bash
php -S localhost:8000 -t examples
```

Then open <http://localhost:8000/> for the gallery, or hit an endpoint directly:

- <http://localhost:8000/bar.php> — bar chart
- <http://localhost:8000/line.php> — two-series line chart
- <http://localhost:8000/pie.php> — pie chart
- <http://localhost:8000/windrose.php> — wind rose

## Files

| File | What it does |
| ----------------- | ------------------------------------------------------- |
| `index.php` | HTML gallery that embeds the chart endpoints |
| `_bootstrap.php` | Shared loader + deprecation muting (`jpgraph_boot()`) |
| `bar.php` | Bar chart endpoint |
| `line.php` | Line chart endpoint (two series, legend, markers) |
| `pie.php` | Pie chart endpoint (percent labels, legend) |
| `windrose.php` | Wind rose endpoint (compass directions, speed ranges) |

## Using the library in your own code

```php
require 'lib/JpGraph.php';

JpGraph\JpGraph::load(); // core
JpGraph\JpGraph::module('bar'); // any module in lib/jpgraph/src/jpgraph_<name>.php

$graph = new Graph(400, 300);
$graph->SetScale('textlin');
$graph->Add(new BarPlot([1, 2, 3, 4]));
$graph->Stroke(); // streams image/png, or pass a path to save
```

## PHP 9 compatibility

The bundled **JpGraph 4.4.3** already resolves the main PHP 8.1+/9 changes on the
standard rendering paths: `strftime()` has been replaced, `imagefilledpolygon()`
is version-guarded via `CheckPHPVersion()`, and computed `float`→`int`
coordinates and dynamic properties are handled. Rendering ~20 chart types under
`error_reporting(E_ALL)` on PHP 8.4 produces **zero** deprecation notices.

This branch closes the remaining removed-function gap, in `LanguageConv`
(`jpgraph_ttf.inc.php`) — the character-encoding paths that still call functions
PHP has removed:

| Removed function | Replacement | Path |
| --- | --- | --- |
| `utf8_encode()` (removed in PHP 9.0) | guarded `mb_convert_encoding` / `iconv`, with a manual Latin-1 fallback | Hebrew text |
| `convert_cyr_string()` (removed in PHP 8.0) | guarded `mb_convert_encoding` / `iconv` | Cyrillic text |

These reuse the guarded-`mb_convert_encoding` idiom the class already applies to
its EUC-JP handling, so behaviour is unchanged where the extensions are present.

**Caveat:** full PHP 9 cleanliness of *every* code branch can't be proven
without a PHP 9 runtime, but all standard plot types — Windrose included — are
verified clean on PHP 8.4.

## Windrose

`WindroseGraph` `require_once`'d `jpgraph_glayout_vh.inc.php`, which was missing
from this fork, so *any* windrose script fatally errored at include time. That
file has been restored (`lib/jpgraph/src/jpgraph_glayout_vh.inc.php`): a
composite layout tree (`LayoutRect` base, with `LayoutHor`/`LayoutVert`) that
arranges several windrose plots in one graph, matching the interface
`jpgraph_windrose.php` expects (`WindroseGraph::Add()` accepts these alongside a
`WindrosePlot`, and each exposes `LayoutSize()`/`SetPos()`/`Stroke()`). Single
plots and the multi-plot `LayoutVert([LayoutHor(...), LayoutHor(...)])` form
both render correctly.

Fonts: upstream windrose hardcoded the MS TrueType fonts (Verdana/Arial), which
aren't present on most systems, so it failed with a "font not readable" error
out of the box. Its font defaults now use the bundled DejaVu font
(`FF_DV_SANSSERIF`, which ships under `lib/jpgraph/src/fonts/`), so windrose
renders with no font setup at all. Call `SetFont()` (on the plot, its `scale`,
and the legend) to use a different font if you have one installed.
36 changes: 36 additions & 0 deletions examples/_bootstrap.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
<?php
/**
* Shared bootstrap for the demo chart endpoints.
*
* JpGraph streams raw PNG bytes straight to the output buffer, so *any* text
* emitted before or during rendering (a stray warning, a notice) corrupts the
* image. The vendored library has been patched for the PHP 8.1+/9 deprecations
* it used to emit (see jpgraph_compat.inc.php and the PHP 9 section of
* README.md), so standard rendering is now notice-free. We still mute
* E_DEPRECATED (and turn off inline error display) as a defensive measure, so
* that a stray notice from any un-exercised code path can never leak into the
* image stream.
*
* This file itself does NOT modify the vendored library — it only configures
* error reporting for these example endpoints.
*/

// Keep real errors, drop the strftime()/other deprecation noise from the
// 2021-era library so it never leaks into the PNG byte stream.
error_reporting(E_ALL & ~E_DEPRECATED);
ini_set('display_errors', '0');

require __DIR__ . '/../lib/JpGraph.php';

/**
* Load the JpGraph core plus any modules a demo needs.
*
* @param string ...$modules e.g. 'bar', 'line', 'pie'
*/
function jpgraph_boot(string ...$modules): void
{
\JpGraph\JpGraph::load();
foreach ($modules as $module) {
\JpGraph\JpGraph::module($module);
}
}
26 changes: 26 additions & 0 deletions examples/bar.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<?php
/**
* Demo endpoint: bar chart. Streams an image/png response.
* Serve the gallery and open /bar.php to view it.
*/
require __DIR__ . '/_bootstrap.php';
jpgraph_boot('bar');

$data = [12, 19, 8, 24, 15, 30, 21];

$graph = new Graph(500, 320);
$graph->SetScale('textlin');
$graph->SetMargin(45, 25, 45, 40);
$graph->title->Set('Weekly signups');
$graph->subtitle->Set('JpGraph ' . trim(str_replace('Version:', '', @file_get_contents(__DIR__ . '/../lib/jpgraph/VERSION'))));
$graph->xaxis->SetTickLabels(['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']);
$graph->yaxis->title->Set('# signups');

$bar = new BarPlot($data);
$bar->SetFillColor('steelblue');
$bar->SetColor('steelblue');
$bar->SetWidth(0.6);
$bar->value->Show();
$graph->Add($bar);

$graph->Stroke();
55 changes: 55 additions & 0 deletions examples/index.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
<?php
/**
* Demo gallery landing page. Each <img> points at a chart endpoint that
* streams a freshly-rendered PNG from JpGraph.
*/
$version = trim(str_replace('Version:', '', @file_get_contents(__DIR__ . '/../lib/jpgraph/VERSION')));
$charts = [
'bar.php' => 'Bar chart',
'line.php' => 'Line chart (two series)',
'pie.php' => 'Pie chart',
'windrose.php' => 'Wind rose',
];
?>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>JpGraph demo gallery</title>
<style>
:root { color-scheme: light dark; }
body { font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
margin: 0; padding: 2rem; line-height: 1.5; }
header { max-width: 900px; margin: 0 auto 1.5rem; }
h1 { margin: 0 0 .25rem; font-size: 1.6rem; }
.sub { opacity: .7; font-size: .95rem; }
.grid { max-width: 900px; margin: 0 auto; display: grid;
grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 1.25rem; }
figure { margin: 0; border: 1px solid rgba(128,128,128,.3);
border-radius: 10px; overflow: hidden; }
figure img { display: block; width: 100%; height: auto; background: #fff; }
figcaption { padding: .6rem .8rem; font-size: .9rem;
border-top: 1px solid rgba(128,128,128,.25); }
figcaption a { text-decoration: none; opacity: .6; float: right; }
code { background: rgba(128,128,128,.15); padding: .1rem .35rem; border-radius: 4px; }
</style>
</head>
<body>
<header>
<h1>JpGraph demo gallery</h1>
<p class="sub">Live charts rendered by JpGraph <?= htmlspecialchars($version) ?: 'library' ?>
on PHP <?= PHP_VERSION ?>. Each image is generated on request.</p>
</header>
<div class="grid">
<?php foreach ($charts as $file => $title): ?>
<figure>
<img src="<?= htmlspecialchars($file) ?>" alt="<?= htmlspecialchars($title) ?>" loading="lazy">
<figcaption><?= htmlspecialchars($title) ?>
<a href="<?= htmlspecialchars($file) ?>" title="Open raw PNG">PNG&nbsp;&rarr;</a>
</figcaption>
</figure>
<?php endforeach; ?>
</div>
</body>
</html>
36 changes: 36 additions & 0 deletions examples/line.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
<?php
/**
* Demo endpoint: line chart with two series. Streams an image/png response.
*/
require __DIR__ . '/_bootstrap.php';
jpgraph_boot('line');

$thisYear = [3, 5, 8, 6, 9, 13, 18, 16, 20, 24, 22, 27];
$lastYear = [2, 4, 5, 7, 6, 9, 12, 14, 13, 17, 19, 21];
$months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];

$graph = new Graph(560, 320);
$graph->SetScale('textlin');
$graph->SetMargin(50, 30, 45, 45);
$graph->title->Set('Monthly active users');
$graph->xaxis->SetTickLabels($months);
$graph->yaxis->title->Set('thousands');
$graph->legend->SetPos(0.03, 0.06, 'right', 'top');

$l1 = new LinePlot($thisYear);
$l1->SetColor('firebrick');
$l1->SetWeight(2);
$l1->mark->SetType(MARK_FILLEDCIRCLE);
$l1->mark->SetFillColor('firebrick');
$l1->mark->SetSize(3);
$l1->SetLegend('This year');
$graph->Add($l1);

$l2 = new LinePlot($lastYear);
$l2->SetColor('gray');
$l2->SetWeight(1);
$l2->SetStyle('dashed');
$l2->SetLegend('Last year');
$graph->Add($l2);

$graph->Stroke();
26 changes: 26 additions & 0 deletions examples/pie.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<?php
/**
* Demo endpoint: pie chart. Streams an image/png response.
*/
require __DIR__ . '/_bootstrap.php';
jpgraph_boot('pie');

$data = [35, 25, 20, 12, 8];
$labels = ['Chrome', 'Safari', 'Firefox', 'Edge', 'Other'];

$graph = new PieGraph(460, 340);
$graph->title->Set('Browser share');
// Legend along the bottom so it never overlaps the pie.
$graph->legend->SetPos(0.5, 0.97, 'center', 'bottom');
$graph->legend->SetColumns(5);

$pie = new PiePlot($data);
$pie->SetLegends($labels);
$pie->SetCenter(0.5, 0.5);
$pie->SetSize(0.32);
$pie->SetLabelType(PIE_VALUE_PER);
$pie->value->Show();
$pie->value->SetFormat('%d%%');
$graph->Add($pie);

$graph->Stroke();
37 changes: 37 additions & 0 deletions examples/windrose.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
<?php
/**
* Demo endpoint: wind rose. Streams an image/png response.
*
* Data is wind-frequency (%) per compass direction. In each direction the
* first value is the "calm" share (drawn as the centre circle) and the rest
* are the speed-range buckets; the values must sum to <= 100% over the whole
* plot. Direction keys are compass labels.
*/
require __DIR__ . '/_bootstrap.php';
jpgraph_boot('windrose');

// calm 0-5 5-10 10-15
$data = [
'n' => [1.5, 1.0, 0.8, 0.4],
'ne' => [1.0, 0.8, 0.5, 0.3],
'e' => [1.2, 1.5, 0.9, 0.4],
'se' => [1.0, 1.2, 0.8, 0.3],
's' => [2.0, 2.5, 1.5, 0.5],
'sw' => [3.0, 4.0, 3.5, 2.0],
'w' => [4.0, 4.5, 3.5, 2.0],
'nw' => [2.5, 3.0, 2.0, 1.0],
];

$graph = new WindroseGraph(500, 400);
$graph->title->Set('Wind rose — frequency by direction');
$graph->title->SetFont(FF_DV_SANSSERIF, FS_BOLD, 12);

$wp = new WindrosePlot($data);
$wp->SetType(WINDROSE_TYPE8);
$wp->SetFontColor('darkgray');
// Speed ranges (knots) -> legend labels + colours (3 ranges after the calm centre).
$wp->SetRanges([0, 5, 10, 15]);
$wp->SetRangeColors(['#4575b4', '#91bfdb', '#fdae61']);
$graph->Add($wp);

$graph->Stroke();
Loading
Loading