COLROW PHP SDK は、PHP 環境にて COLROW API を利用するための SDK です。
Composer を使います。まずはプロジェクトのルートディレクトリにて、以下の composer.json を作成し、php composer.phar install を実行してください。
{
"require": {
"rashiku/colrow-php-sdk" : "1.0.*"
}
}
以下のように記述することで COLROW PHP SDK が利用できるようになります。
require_once 'vendor/autoload.php';
何らかの事情で Composer が使えない場合は、ファイル一式をダウンロードし、Colrow フォルダをそのままお使いください。上記の autoload.php の代わりに以下のように記述し、必要なファイル群を読み込んでください。
require_once 'Colrow/ColrowClient.php';
require_once 'Colrow/ColrowObject.php';
require_once 'Colrow/ColrowQuery.php';
require_once 'Colrow/ColrowDrive.php';
require_once 'Colrow/ColrowException.php';
※PHP のバージョンは 5.4 以上である必要があります。
SDK から必要なファイルを読み込んだ後、ColrowClient を初期化する必要があります（ColrowDrive だけは例外）。
ColrowClient::initialize(
'your_account',
'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
'シート1'
);
3つの引数はそれぞれ「COLROW に登録した Google アカウント」「スプレッドシートの key」「ワークシート名」になります。
利用する機能に応じたクラスを use 文にて宣言します。大抵のケースでは、以下の3つのクラス（のうちいずれか）を宣言することになるでしょう。
use Colrow\ColrowClient;
use Colrow\ColrowQuery;
use Colrow\ColrowObject;
オブジェクトとして全件取得：
$query = new ColrowQuery();
$objects = $query->find();
最初の1件を取得：
$query = new ColrowQuery();
$object = $query->first();
クエリ（後述）を指定して取得：
$query = new ColrowQuery();
$query->equalTo('会社名', 'らしく');
$query->orderBy('日付');
$query->reverse(true);
$objects = $query->find();
件数をカウント：
$query = new ColrowQuery();
echo $query->count();
シートに新しい行を追加：
$row = new ColrowObject();
$row->set('会社名', 'らしく販売');
$row->set('担当者', '鈴木一郎');
$row->set('日付', '2016/1/1');
$row->save();
行の内容を更新：
$query = new ColrowQuery();
$objects = $query->find();
$row = $objects[10];
$row->set('担当者', '田中太郎');
$row->save();
行を削除：
$query = new ColrowQuery();
$objects = $query->find();
$row = end($objects);
$row->destroy();
ColrowQuery クラス経由で取得したオブジェクトは、get メソッドによって内容を参照できます。
foreach ($objects as $object) {
echo $object->get('会社名') . "\n";
}
その他にも、以下のメソッドが利用可能です。
- set(label, value) ... オブジェクトの label（列のラベル名）に value をセット
- save() ... オブジェクトを保存。シートの該当行の内容も更新（新規作成した場合は最終行に追加）
- destroy() ... オブジェクトを削除。シートの該当行も削除
- getId() ... オブジェクトの ID（＝該当行に割り当てられた固有の ID）を参照
- toJson() ... JSON 文字列に変換（デバッグ用）
シートの内容を抽出するため、ColrowQuery クラスのインスタンスに対して、SQL の where 句に相当する以下のメソッドが用意されています。
- equalTo(label, value) ... label の値が value に等しい
- notEqualTo(label, value) ... label の値が value に等しくない
- lessThan(label, value) ... label の値が value より小さい
- greaterThan(label, value) ... label の値が value より大きい
- lessThanOrEqualTo(label, value) ... label の値が value より小さいか等しい
- greaterThanOrEqualTo(label, value) ... label の値が value より大きいか等しい
- exists(label) ... label の値が空ではない
- doesNotExist(label) ... label の値が空である
上記の条件を複数列記することで AND として扱われます。
$query->equalTo('カテゴリ', 'A');
$query->notEqualTo('状態', '休業中');
$query->lessThanOrEqual('優先度', 5);
OR の場合は ColrowQuery のインスタンスを個別に作成し、orQuery メソッドを使います。
$query1 = new ColrowQuery();
$query1->equalTo('会社名', 'らしく');
$query2 = new ColrowQuery();
$query2->equalTo('会社名', 'らしく販売');
$query = new ColrowQuery();
$query->orQuery($query1, $query2);
$objects = $query->find();
その他にも以下のメソッドが利用可能です。
- orderBy(label) ... label の値でソート（デフォルトは昇順）
- reverse(boolean) ... true を指定することでソートを降順に変更
- offset(number) ... 指定した列数をスキップ
- limit(number) ... 取得する列数を指定
Google ドライブにファイルをアップロードするために用意された ColrowDrive クラスは、前述した他のクラスとはやや使用感が異なります。
use Colrow\ColrowDrive;
if (isset($_FILES['image'])) {
$file = $_FILES['image'];
$fp = fopen($file['tmp_name'], 'r');
$file_body = base64_encode(fread($fp, filesize($file['tmp_name'])));
fclose($fp);
$parent_id = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
$response = ColrowDrive::upload('your_account', $file['name'], $file['type'], $file_body, $parent_id);
echo json_encode($response);
} else {
echo '<form method="post" action="" enctype="multipart/form-data">';
echo '<input type="file" name="image">';
echo '<input type="submit" value="アップロード">';
echo '</form>';
}
$parent_id はファイルのアップロード先、つまり Google ドライブのフォルダの ID になります。そのフォルダのページの URL の https://drive.google.com/drive/u/0/folders/ 以降に書かれているのがそれです。また、ColrowDrive::upload() の第1引数には、COLROW に登録した Google アカウントを指定してください。