SimpleGraph Document


はじめに~クラスの概要~

グラフライブラリSimpleGraphは、PHPプログラムから数種のグラフイメージを作成するツールです。SimpleGraphを使用すると、PHPプログラムの配列をライブラリにパラメータとして渡すことで、簡単にグラフを作成することができます。
作成できるグラフは、①棒グラフ、②円グラフ、③折れ線グラフとなります。
グラフイメージはとてもシンプルなものとなります。複雑なデータをグラフに表すことは出来ませんが、WEBシステム・アプリケーションでの集計処理で簡易な集計グラフを必要とする場合や、集計データを表として詳細に表示し、その概要としてグラフを必要とする場合に、簡易な処理でグラフ描画を可能とするSimpleGraphはとても良いツールとなります。

SimpleGraphはWEBシステム・アプリケーションでのグラフ作成に関して、ミニマムな機能を提供いたします。
PHPで記述されたグラフライブラリとしてはJpGraph(http://www.asial.co.jp/jpgraph/)があり、高機能・高品質なライブラリとなります。非営利目的で使用する場合には、無料のJpGraphコミュニティ版を利用できますので、高機能・高品質なグラフを必要とする場合には、JpGraphの利用を検討することをお勧め致します。

SimpleGraphの動作環境ですが、PHP5.x.xでの使用を前提としております。
また、グラフ生成にGD拡張モジュールを使用しますので、php.iniの設定でGD拡張モジュールを有効にしてください。
PHP4.x.xでの動作ですが、PHP5.x.xのみの対応となっております。クラスファイルの記述がPHP5.x.xで採用された構文に沿って記述されているためです。PHP4.x.xでの動作検証は行っておりませんので、ご了承ください。

PHPバージョン ver 5.x.x
拡張モジュール GD/GD2

ライセンスに関して

配布に際しては皆様がWEBシステムにSimpleGraphを組み込んだ場合でも、ソースコードの開示を必要としないように、またSimpleGraphのソースコードを改変・改良して再配布することが出来るようにBSDライセンスに従って配布致します。
ただし、BSDライセンスによる配布ですので、再配布・使用の際には下記の条件に従う必要があります。

基本的に、クラスファイルの最初に記述されている著作権等の記載部分をそのままにして使用・配布していただければ上記条件を満たすといえます。
また、改変後の再配布に際して、ユーザの再配布の自由を強制されることもありません。

日本語対応に関して

SimpleGraphでは、日本語対応としてIPA(独立行政法人 情報処理推進機構)の提供するIPAフォント(http://ossipedia.ipa.go.jp/ipafont/index.html)を使用しています。
IPAフォントは「IPA Font License Agreement v1.0」ライセンスにて配布されております。
SimpleGraphの使用に際しては、SimpleGraphの準拠する「BSD License」と共に、IPAフォントの準拠するライセンスも遵守していただく必要がございます。
SimpleGraphのダウンロードの際に、両ライセンスに同意するかの確認をさせて頂きますが、下記リンクページを一読していただき、両ライセンスの遵守をお願い致します。

SimpleGraph Sandbox

SimpleGraphをスムーズに体験して頂くために、Sandboxを用意しております。
ダウンロードしたzipファイルを解凍すると「SimpleGraph_Sandbox」がありますので、Windows環境の方はローカルにWA(M)P環境を、Linux環境の方はローカルにLA(M)P環境を構築して頂き、Apacheのドキュメントルートに、解凍した「SimpleGraph_Sandbox」を配置してください。
※MySQLなどのデータベースは必要ありません。ローカルでApache、PHPが動作する環境を構築してください。
そして、WEBブラウザを起動して、「http://localhost/SimpleGraph_Sandbox/」をロケーションバーに入力して閲覧してください。
SimpleGraphで生成したグラフイメージが2つ見えるはずです。一方は「imgタグのsrc属性指定でのグラフ生成例」で、他方は「ajaxでのグラフ生成例」です。
以下にSandboxのコードの説明をしながら、SimpleGraphの使用法をご説明していきます。

Sandboxの構成

まず、Sandboxの構成を見てみましょう。

【ディレクトリ】
/┳css
 ┣graph ※SimpleGraphライブラリ本体
   ┣font
   ┣BarGraph.class.php
   ┣CircleGraph.class.php
   ┣Graph.class.php
   ┣GraphBuilder.class.php
   ┣LineGraph.class.php
 ┣index.html ※Sandbox内での表示ファイル
 ┣make_graph_image.php ※「imgタグのsrc属性指定でのグラフ生成例」でグラフイメージを生成するファイル
 ┣send_graph_image.php ※「ajaxでのグラフ生成例」でグラフイメージを生成するファイル

Sandbox内の「graph」フォルダが、SimpleGraphライブラリ本体となります。
実際にSimpleGraphを使用する際は、この「graph」フォルダをWEBシステム・アプリケーション内の任意のディレクトリに配置して、 グラフ生成クラスを利用します。

SimpleGraph本体となる「graph」フォルダ内の構成は以下になります。
①GraphBuilder.class.php ※グラフオブジェクト生成のfactoryメソッドを提供するクラス
②Graph.class.php ※SimpleGraphライブラリ基底クラス
③BarGraph.class.php ※棒グラフ生成クラス
④CircleGraph.class.php ※円グラフ生成クラス
⑤LineGraph.class.php ※折れ線グラフ生成クラス
⑥font ※SimpleGraphで使用するフォント格納ディレクトリ

以上がSimpleGraphのクラス構成となります。

クイックスタート(imgタグのsrc属性指定でのグラフ生成例)

では、「imgタグのsrc属性指定でグラフ生成する例」をご説明してきます。

まず、「index.html」のソースコードは以下のようになっています。

【index.html】
<h3>imgタグのsrc属性指定でのグラフ生成例</h3>
<img src="make_graph_image.php?とても良かったです=25&良かったです=59&普通=158
&悪かった=25&とても悪かった=12">

imgタグのsrc属性に、グラフイメージを生成するファイルである「make_graph_image.php」を、クエリパラメータにグラフデータを付けて指定しています。

次に、実際にグラフイメージを生成して、クライアント(ブラウザ)に返却する「make_graph_image.php」のソースコードを見てみましょう。

【make_graph_image.php】
<?php
// グラフライブラリ ビルダークラスのインクルード
require_once './graph/GraphBuilder.class.php';

// グラフデータの取得
$data = array();
foreach ($_GET as $key => $value) {
	$data[$key] = $value;
}

// グラフオブジェクトの生成
$graph = GraphBuilder::factory('BarGraph', $data, 'jpeg');
//$graph = GraphBuilder::factory('CircleGraph', $data, 'jpeg');
//$graph = GraphBuilder::factory('LineGraph', $data, 'jpeg');

// グラフイメージの出力
$graph->flush();
?>

まず、①SimpleGraph本体の「graph」フォルダ内にある「GraphBuilder.class.php」をインクルードします。
「GraphBuilder.class.php」はグラフ生成のためのグラフオブジェクトを生成するためのfactoryメソッドを提供します。
次に、②「index.html」から送られてきたクエリパラメータ(GETパラメータ)を取得して、配列として整形します。
ソースコード内の「$data」は、実際にグラフに表示するデータとなり、以下の対応となります。

$key : [データ項目]
$value : [データの値]

そして、③グラフ生成オブジェクトをfactoryメソッドを使用して生成します。
その際、引数として以下のパラメータを渡します。

第1引数 : グラフタイプ
第2引数 : グラフデータ(連想配列)
第3引数 : グラフ生成のMIMEタイプ

<グラフタイプ>
SimpleGraphでは、現在以下のグラフタイプに対応しています。
(1)棒グラフ : 'BarGraph'
(2)円グラフ : 'CircleGraph'
(3)折れ線グラフ : 'LineGraph'

<グラフデータ>
実際に表示するグラフデータは、上記で示したように、①データ項目、②データの値をペアとした連想配列として渡す必要があります。

<グラフ生成のMIMEタイプ>
SimpleGraphでは、現在以下のMIMEタイプに対応しています。
(1)png
(2)jpeg
(3)gif
なお、MIMEタイプを省略した場合は、デフォルトのMIMEタイプとしてpngが出力されます。

最後に、④flushメソッドをコールして、グラフイメージを出力します。
SimpleGraphで提供されているflushメソッドは、png・jpeg・gifイメージを出力するメソッドです。
生成したグラフイメージをクライアントに返却するには、このflushメソッドをグラフ生成処理を記述したPHPファイルの最後にコールします。

エンコーディング(文字コード)に関して

SimpleGraphは、ソースコードの記述エンコーディングとしてUTF-8を採用しています。
また、通常の運用としてPHPの内部エンコーディング(mb_internal_encoding)はUTF-8を想定しております。
表示するページ(例ではindex.html)の文字コードを、例えばShift_JISで記述した場合は、グラフ内の文字が文字化けする可能性があります。
その場合は、グラフ生成処理をするPHPファイル内で、GETパラメータを受け取った後に、文字コードをUTF-8に変換した上で、グラフオブジェクトを生成してください。

クイックスタート(ajaxでのグラフ生成例)

次に、「ajaxでのグラフ生成例」について説明をしていきます。

「index.html」のソースコードは、以下のようになっています。

【scriptタグ】
<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript">google.load("jquery", "1.4");</script>
<script>
var url = './send_graph_image.php';
// 棒グラフ・円グラフ用
var dataObj = {
		'とても良かったです' : 25,
		'良かったです' : 59,
		'普通' : 158,
		'悪かった' : 25,
		'とても悪かった' : 12
};

// 折れ線グラフ用
/*
var dataObj = {
		'1965' : 3,
 		'1970' : 5,
 		'1975' : 36,
 		'1980' : 25,
 		'1985' : 10,
 		'1990' : 25,
 		'1995' : 59,
 		'2000' : 158,
 		'2005' : 25,
 		'2010' : 12
};
*/

// ajax通信でグラフイメージ(base64エンコード)を取得する
$.ajax({
	url: url,
	dataType: 'text',
	data: dataObj,
	success: function(data){
		setGraphImage(data);
	}
});

function setGraphImage(data)
{
	var imgTag = '<img src="data:image/jpeg;base64,' + data + '">';
	$('#graph').html(imgTag);
}
</script>
【HTML】
<h3>ajaxでのグラフ生成例</h3>
<div id="graph"></div>

まず、scriptタグでは、jQueryを読み込んでいます。これは、ajax通信の実装を簡略化するためです。
ajax通信で送信するグラフデータを、dataObjとして用意します。
このグラフデータの生成部分を変更することで、様々なUIを実装できます。
ajax通信のdataプロパティーにdataObjをセットすることで、オブジェクトがクエリー文字列に変換されてGETリクエストとして付加されます。
ajax通信のレスポンス(data)を、setGraphImage関数にて、imgタグのsrc属性にセットして、div#graph要素のコンテンツとして書き込みます。
※この段階で、生成したグラフイメージが表示されます。
※jQueryのajax通信に関する詳細な解説は、他のサイトを参照してください。
※プレーンなJavaScriptで、XMLHttpRequestオブジェクトを使用した実装をする場合も、上記説明にならって実装をしてください。

次に、ajax通信のサーバサイドプログラムとなる「send_graph_image.php」の説明を致します。

<?php
// グラフライブラリクラスのビルダーのインクルード
require_once './graph/GraphBuilder.class.php';

// グラフデータの取得
$data = array();
foreach ($_GET as $key => $value) {
	$data[$key] = $value; 
}

//$graph = GraphBuilder::factory('BarGraph', $data, 'jpeg');
$graph = GraphBuilder::factory('CircleGraph', $data, 'jpeg');
//$graph = GraphBuilder::factory('LineGraph', $data, 'jpeg');

// グラフイメージを取得・base64エンコードして出力
$graphImage = $graph->fetch();
echo base64_encode($graphImage);
?>

まず、①SimpleGraph本体の「graph」フォルダ内にある「GraphBuilder.class.php」をインクルードします。
次に、②「index.html」から送られてきたクエリパラメータ(GETパラメータ)を取得して、配列として整形します。
ソースコード内の「$data」は、実際にグラフに表示するデータとなります。
そして、③fetchメソッドでグラフイメージを取得して、④flushメソッドをコールし、グラフイメージをブラウザに出力します。
※出力をbase64エンコードするのは、imgタグにイメージコードを直接記述するために必要となるからです。

ライブラリ提供メソッド

factoryメソッド

グラフオブジェクトを生成するスタティックなメソッドです。GraphBuilderのメンバとして提供されています。

public static function factory($className, $dataArray, $imageType)
第1引数 $className 生成するグラフオブジェクトのクラス名
※BarGraph/CircleGraph/LineGraph
第2引数 $dataArray グラフに表示するデータ配列(連想配列)
※空の配列を渡した場合は、白い最小サイズの画像が表示されます。
第3引数 $imageType グラフイメージのMIMEタイプ(png/jpeg/gif)
※指定のない場合はpngとなります。
戻り値 object 生成した具象クラスのインスタンス

fetchメソッド

fetchメソッドは、グラフデータをセットしたグラフオブジェクトからグラフイメージを取得するメソッドです。
ajax通信でグラフイメージを表示するためにサーバサイドでbase64エンコードをする際に使用します。

public function fetch()
引数 void
戻り値 binary グラフイメージのバイナリコード

flushメソッド

flushメソッドは、グラフイメージを出力するメソッドです。
通常は、グラフイメージを出力する(クライアントに返却する)PHPプログラムの最後にコールします。

public function flush()
引数 void
戻り値 void