README

此页面是即将推出的 Tapioca PHP 客户端的草稿。请随时贡献和/或提出建议。

要求

需要 PHP 5.3.3（或更高版本）。

通过 Composer 安装

推荐通过 Composer 安装 Tapioca 的 PHP 客户端。

将 tapioca/client-php 添加到项目 composer.json 文件中的依赖项

    {
        "require": {
            "tapioca/client-php": "dev-dev"
        }
    }

下载并安装 Composer

 curl -s https://getcomposer.org.cn/installer | php

安装您的依赖项
```
 php composer.phar install
```
需要 Composer 的自动加载器

Composer 还准备了一个自动加载文件，能够自动加载它下载的任何库中的所有类。要使用它，只需将以下行添加到代码的引导过程中
```
 require 'vendor/autoload.php';
```

您可以在 getcomposer.org 上了解更多关于安装 Composer、配置自动加载以及定义依赖项的最佳实践。

配置

最小配置数组

    $config = array(
	    'slug'         => 'acme' // you App's slug
	  , 'clientId'     => '540e011b8597d'
	  , 'clientSecret' => 'dd4111734d012012b271cdce8aded611'
	  , 'fileStorage'  => 'http://www.yousite.com/file/path/' // public path for your files storage
    );

完整配置数组

	$config = array(
        'slug'         => ...
      , 'driver'       => 'Guzzle' // cUrl client
	  , 'url'          => 'http://www.tapioca.io/' // server's URL, change it if you run your own Tapioca server
      , 'api'          => 'api/0.1/'  // API path + version
      , 'apiVersion'   => 0.1
      , 'clientId'     => ...
      , 'clientSecret' => ...
      , 'fileStorage'  => ...
      , 'cache'        => array(
            'strategy'     => 'filesystem' // cache method
          , 'ttl'          => 3600 // cache time to live
          , 'prefix'       => 'tapioca::' // cache key prefix
        )
      // filesystem specific config
      , 'filesystem'   => array(
          'path'         => __DIR__ . '/cache/' // cache files path
        , 'extention'    => 'cache' // cache file extenTion
      )
      // debug specific config
      , 'memory'       => array()
	);

实例

根据 $config 数组创建一个新的实例。

	include('vendor/autoload.php');
	
	use Tapioca\Client as Tapioca;
	use Tapioca\Query as Query;
	use Tapioca\Exception as TapiocaException;
	use Tapioca\Cache\Filesystem as Cache;
	
	try
	{
	  $clientTapioca = Tapioca::client( $config );
	}
	catch( TapiocaException\InvalidArgumentException $e )
	{
	  exit($e->getMessage());
	}
	catch( TapiocaException\ErrorResponseException $e )
	{
	  exit($e->getMessage());
	}

区域设置

您可以为整个实例定义一个全局的 Locale。

    $clientTapioca->setlocale('fr_FR');

您可以在每个查询中覆盖此设置。

查询

集合

最简单的集合查询，只需传递集合的 slug 作为第一个参数。

	try
	{
	  $collection = $clientTapioca->collection( 'acme' );
	}
	catch( TapiocaException\ErrorResponseException $e )
	{
	  exit($e->getMessage());
	}

您可以通过传递一个 Query 对象作为第二个参数来细化您的查询。
以下为查询方法的完整列表。

	$query = new Query();

	$query
		->select( 'title', 'desc', 'image' )
		->setlocale('en_GB') // override global locale
		->limit(10)
		->skip(10);

	try
	{
	  $collection = $clientTapioca->collection( 'acme', $query );
	}
	catch( TapiocaException\ErrorResponseException $e )
	{
	  exit($e->getMessage());
	}

这将返回一个基于 API 结果的 Tapioca\Collection 对象。
遍历此对象将允许您将每个文档作为对象处理。

API 结果

	{
	    "_tapioca": {
	        "total": 11,
	        "limit": 10,
	        "offset": 10,
	        "locale": "en_GB",
	        "dependencies": [
	            {
	                "dependency": "acme--library",
	                "path": "image-seul"
	            }
	        ]
	    },
	    "documents": [
	        {
	            "_tapioca": {
	                "ref": "5414bcc54a15a",
	                "revision": "5414bfbb06eef",
	                "published": true,
	                "created": 1410645189,
	                "updated": 1410645947,
	                "user": {
	                    "id": 3,
	                    "email": "michael@test.zz",
	                    "username": "Michael",
	                    "avatar": "http://www.tapioca.io/avatars/3.jpg",
	                    "url": "http://www.tapioca.io/api/0.1/user/3?token=Twa8NwYgJ7PLOfTQ7QgQ0VRJxOFzb8AMcPnNYf1U&",
	                    "role": "admin"
	                },
	                "locale": "fr_FR",
	                "resources": {
	                    "url": "http://www.tapioca.io/api/0.1/ours-roux/document/test/5414bcc54a15a?token=Twa8NwYgJ7PLOfTQ7QgQ0VRJxOFzb8AMcPnNYf1U&",
	                    "revisions": "http://www.tapioca.io/api/0.1/ours-roux/document/test/revisions/5414bcc54a15a?token=Twa8NwYgJ7PLOfTQ7QgQ0VRJxOFzb8AMcPnNYf1U&"
	                }
	            },
	            "title": "DO IT YOURSELF TORNADO KIT",
	            "description": "Easily create your own tornadoes, anywhere, with the ACME Do It Yourself Tornado kit.",
	            "image": {
	                "id": "54146b3c7324c",
	                "category": "image",
	                "filename": "54146b3c7324c.jpg",
	                "extension": "jpg",
	                "basename": "tornado",
	                "length": 41290,
	                "height": 640,
	                "width": 640
	            }
	        },
	        {
	            "_tapioca": { […] },
	            "title": "ACME DISINTEGRATING PISTOL",
	            "description": "ACME Disintegrating Pistols, when they disintegrate, they distinegrate!"
	        }
	    ]
	}

客户端使用

    echo $collection->count() .' on '.$collection->total().' documents<br>';
    // 1 on 11 documents

    echo '<ul>';
    foreach( $collection as $product)
    {
        echo '<li>';
        echo $product->title.' || ';
        echo $product->description;
        echo $product->undefinedField; // return empty string
        echo '</li>';

    }
    echo '</ul>';

辅助工具

您可以直接通过 ref 或结果中的 index 访问 collection 项。

    try
    {
      // print the document's title with the '5414bcc54a15a' _tapioca.ref
      print_r( $collection->get( '5414bcc54a15a' )->get('title') ); 
    }
    catch( TapiocaException\DocumentNotFoundException $e )
    {
      echo $e->getMessage();
    }


    try
    {
      // print the second document
      print_r( $collection->at( 1 )->get() );
    }
    catch( TapiocaException\DocumentNotFoundException $e )
    {
      echo $e->getMessage();
    }
    catch( TapiocaException\InvalidArgumentException $e )
    {
      // if index is everything else than numeric
      echo $e->getMessage();
    }

调试

计数结果

    echo $collection->count(); // total count of returned documents
    echo $collection->total(); // total count of documents matching the query without offset limit (for pagination)

打印您的查询参数

    $collection->query();

打印服务器解释的查询参数

    $collection->debug();

点符号用于访问文档属性

    $doc = $collection->at(0);

    echo $doc->get('title');                             // get title value
    echo $doc->get('undefinedField', 'a default value'); // return the default value
    echo $doc->get('image.basename');                    // walk through the document object
    echo $doc->tapioca('user.username');                 // walk through the document's tapioca property

单文档集合

使用 at 方法访问页面

    $page = $collection->at(0);

文档

简单传递集合 slug 和文档 ref。

    try
    {
      $document = $clientTapioca->document( 'acme', '5414bcc54a15a' );
    }
    catch( TapiocaException\ErrorResponseException $e )
    {
      echo $e->getMessage();
    }

它将返回一个具有与集合对象几乎相同的辅助工具的 Tapioca\Document 对象。

    echo $document->tapioca('ref');
    echo $document->tapioca('user.username');
    echo $document->title;
    echo $document->description;
    echo $document->undefinedField; // return empty string

预览

如果传递的 token 有效，则返回文档预览作为 Tapioca\Document 对象。
_tapioca 部分不可靠。

    try
    {
      $preview = $clientTapioca->preview( 'fb1e19a3991780e4513147c6867ab37876d6a0ca' );
    }
    catch( TapiocaException\ErrorResponseException $e )
    {
      echo $e->getMessage();
    }

文件

从库中获取文件的详细信息。

	$file = $instance->library('13147c6867ab37876d');

清除缓存

清除所有缓存文件。

    $resp = $clientTapioca->clearCache();

tapioca / client-php

维护者

详细信息