supplement code notation

Author: kevinyan815

src/Connection.php

@@ -5,20 +5,53 @@
 class Connection
 {
  /**
+ * Elasticsearch client instance
+ *
  * @var EsClient
  */
  protected $client;
 
+ /**
+ * Query builder
+ *
+ * @var
+ */
  protected $queryBuilder;
 
+ /**
+ * The elasticsearch connection configuration options.
+ *
+ * @var array
+ */
  protected $config;
 
+ /**
+ * Index name for elasticsearch connection
+ *
+ * @var
+ */
  protected $index;
 
+ /**
+ * type name for elasticsearch connection
+ *
+ * @var
+ */
  protected $type;
 
+ /**
+ * time zone (usually using in range query)
+ *
+ * @var
+ */
  public $timeZone;
 
+ /**
+ * Connection constructor.
+ *
+ * @param EsClient $client
+ * @param $config
+ */
  public function __construct(EsClient $client, $config)
  {
  $this->client = $client;

src/ConnectionFactory.php

@@ -5,18 +5,40 @@
 
 class ConnectionFactory
 {
+ /**
+ * Elasticserach client builder
+ *
+ * @var ClientBuilder
+ */
  protected $clientBuilder;
 
+ /**
+ * ConnectionFactory constructor.
+ *
+ * @param ClientBuilder $clientBuilder
+ */
  public function __construct(ClientBuilder $clientBuilder)
  {
  $this->clientBuilder = $clientBuilder;
  }
 
+ /**
+ * Establish a elasticsearch connection based on the configuration
+ *
+ * @param array $config
+ * @return Connection
+ */
  public function make(array $config)
  {
  return $this->createConnection($config);
  }
 
+ /**
+ * Create elasticsearch connection
+ *
+ * @param array $config
+ * @return Connection
+ */
  protected function createConnection(array $config)
  {
  $host = array_only($config, 'host', 'port', 'scheme', 'user', 'pass');

src/QueryBuilder.php

@@ -4,36 +4,42 @@
 class QueryBuilder
 {
  /**
- * select 字段列表
+ * fields fetched in query
+ *
  * @var array
  */
  protected $selectedFields = [];
  /**
- * 区间范围条件
+ * range condition
+ *
  * @var array
  */
  protected $range;
 
  /**
- * term条件
+ * term condition
+ *
  * @var array
  */
  protected $terms;
 
  /**
- * 排序规则
+ * order rules
+ *
  * @var array
  */
  protected $orders;
 
  /**
- * 结果集起始文档距搜索结果首个文档的距离
+ * fetched item's offset apart from the first item in the whole result of a search
+ *
  * @var string
  */
  protected $from;
 
  /**
- * 返回搜素结果文档的数目
+ * result size
+ *
  * @var string
  */
  protected $size;
@@ -102,7 +108,8 @@ public function initQueryBody()
 
 
  /**
- * 为搜索设置时间范围条件
+ * set time range condition for query
+ *
  * @param $start
  * @param $end
  * @return $this
@@ -123,7 +130,7 @@ public function setTimeRange($start, $end)
  }
 
  /**
- * 为搜索添加term条件
+ * add term condition for query
  * @param $term
  * @param $value
  * @return $this
@@ -135,7 +142,8 @@ public function term($term, $value)
  }
 
  /**
- * 设置搜索结果的排序方式
+ * specify data will be sorted through field in asc or desc
+ *
  * @param $field
  * @param $value
  * @return $this
@@ -147,17 +155,20 @@ public function order($field, $value)
  }
 
  /**
- * 设置搜索按照时间降序返回文档
+ * order documents in descending time
+ *
  * @return $this
  */
- public function newest()
+ public function latest()
  {
  $this->order('@timestamp', 'desc');
  return $this;
  }
 
  /**
- * 设置搜索按照时间升序返回文档
+ * order documents in ascending time
+ *
+ * @return $this
  */
  public function oldest()
  {
@@ -166,7 +177,7 @@ public function oldest()
  }
 
  /**
- * 设置搜索结果_source里只包含给定的字段
+ * set fields include in _source in query result
  * @param array $fields
  * @return $this
  */
@@ -178,15 +189,16 @@ public function select(array $fields = [])
  }
 
  /**
- * 清除selectedFields里的值
+ * clear $selectedFields
  */
  protected function clearSelect()
  {
  $this->selectedFields = [];
  }
 
  /**
- * 设置返回的第一条文档距离结果集首个文档的距离(文档数)
+ * Set the distance of the first document returned from the first document in the whole query result set
+ *
  * @param $offset
  * @return $this
  */
@@ -197,7 +209,8 @@ public function from($offset)
  }
 
  /**
- * 设置要返回的文档数目
+ * set size of return result
+ *
  * @param $size
  * @return $this
  */
@@ -220,14 +233,14 @@ public function scrollSize($scrollSize)
  }
 
  /**
- * 组成搜索条件的Query
- * Query示例:
+ * compose query based on all options we set before
+ * Query Example:
  *
  * [
- * 'index' => 'logstash-bussiness_weixin_bridge_page*',
- * 'type' => 'bussiness_weixin_bridge_page',
- * 'scroll'=> '30s',//scroll镜像生存时间维持30秒, 在调用每次进行scroll搜索时会重新设置镜像的生存时间,
- * 'size' => '50',//result size for per shard scroll created
+ * 'index' => 'index name ',
+ * 'type' => 'type name',
+ * 'scroll'=> '30s',// how long between scroll requests. should be small!
+ * 'size' => '50', //results size for per shard scroll created
  * 'body' => [
  * 'query' => [
  * 'bool' => [
@@ -301,7 +314,8 @@ public function composeQuery()
 
 
  /**
- * 搜索并返回文档
+ * fetch then return documents
+ *
  * @return array
  */
  public function get()
@@ -314,7 +328,8 @@ public function get()
  }
 
  /**
- * 返回匹配搜索条件的文档数
+ * count matching documents
+ *
  * @return int
  */
  public function count()
@@ -332,9 +347,11 @@ public function count()
  }
 
  /**
- * 遍历搜索结果
- * 分页遍历搜索结果请不要循环用from和size来取数据, 应该用更高效的scroll api, 更多信息查看下面的文档
+ * iterate documents matching search options
+ * this is more efficient than specify from and size in query body, more about scroll you can checkout
  * @documentaion https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/_search_operations.html#_scrolling
+ *
+ * @return array
  */
  public function scroll()
  {

src/config/config.php

@@ -16,20 +16,19 @@
  | Default Elastic Connection Name
  |--------------------------------------------------------------------------
  |
- | Here you may specify which of the database connections below you wish
- | to use as your default connection for all database work. Of course
- | you may use many connections at once using the Database library.
+ | Here you may specify which of the connections below you wish
+ | to use as your default connection for all elasticsearch's work. Of course
+ | you may use many connections at once using the Elastic library.
  |
  */
 
  'default' => env('ELASTIC_CONNECTION', 'default'),
 
  /*
  |--------------------------------------------------------------------------
- | ElasticSearch 连接的配置信息
+ | ElasticSearch connection configuration
  |--------------------------------------------------------------------------
- | index和type是ElasticSearch执行时操作才需要的配置信息, 其它几项配置信息是连接
- | ElasticSearch时需要的配置信息
+ |
  */
 
  'connections' => [