README

JsonQ 是一个简单、优雅的 PHP 包，用于查询任何类型的 JSON 数据。它通过提供类似 ORM 的查询方式，使您更容易处理 JSON 数据。

支持本项目

Hey due，请帮助我每天改进这个项目

注意

从 JsonQ 6.0 版本开始，所有功能都重写自 QAarray。经过长期运行，我们发现 JsonQ 的查询引擎应该是独立的。因为人们希望查询各种类型的数据，如 CSV、YAML、XML。因此，如果我们保持查询引擎与该项目紧密耦合，那就没有意义了。这就是为什么我们将查询引擎部分移出，并开发了一个新的包 QAarray。Qarray 是为查询原生 PHP 数组而设计的，任何人都可以实现自己的引擎，就像 JsonQ 一样。

请勿直接从以下版本更新到 >= 6.0 版本

安装

composer require nahid/jsonq

使用方法

您可以通过从文件导入您的 JSON 数据立即开始使用此包

use Nahid/JsonQ/Jsonq;
$jsonq = new Jsonq('data.json');

或从 JSON 字符串

$json->json('{"id": 1, "name": "Nahid"}');

或从 PHP 数组

$json->collect(['id'=>1, 'name'=>'Nahid']);

您可以使用各种查询方法（如 find、where、orWhere、whereIn、whereStartsWith、whereEndsWith、whereContains 等）开始查询数据。此外，您还可以在查询后使用 sum、count、groupBy、max、min 等方法对数据进行聚合。

让我们看看一个快速示例

//data.json
{
   "name": "products",
   "description": "Features product list",
   "vendor":{
      "name": "Computer Source BD",
      "email": "info@example.com",
      "website":"www.example.com"
   },
   "users":[
      {"id":1, "name":"Johura Akter Sumi", "location": "Barisal"},
      {"id":2, "name":"Mehedi Hasan Nahid", "location": "Barisal"},
      {"id":3, "name":"Ariful Islam", "location": "Barisal"},
      {"id":4, "name":"Suhel Ahmed", "location": "Sylhet"},
      {"id":5, "name":"Firoz Serniabat", "location": "Gournodi"},
      {"id":6, "name":"Musa Jewel", "location": "Barisal", "visits": [
         {"name": "Sylhet", "year": 2011},
         {"name": "Cox's Bazar", "year": 2012},
         {"name": "Bandarbar", "year": 2014}
      ]}
   ],
   "products": [
      {"id":1, "user_id": 2, "city": "bsl", "name":"iPhone", "cat":1, "price": 80000},
      {"id":2, "user_id": 2, "city": null, "name":"macbook pro", "cat": 2, "price": 150000},
      {"id":3, "user_id": 2, "city": "dhk", "name":"Redmi 3S Prime", "cat": 1, "price": 12000},
      {"id":4, "user_id": 1, "city": null, "name":"Redmi 4X", "cat":1, "price": 15000},
      {"id":5, "user_id": 1, "city": "bsl", "name":"macbook air", "cat": 2, "price": 110000},
      {"id":6, "user_id": 2, "city": null, "name":"macbook air 1", "cat": 2, "price": 81000}
   ]
}

use Nahid\JsonQ\Jsonq;

$q = new Jsonq('data.json');
$res = $q->from('products')
    ->where('cat', '=', 2)
    ->get();
dump($res);

//This will print
/*
array:3 [▼
  1 => {#7 ▼
    +"id": 2
    +"user_id": 2
    +"city": null
    +"name": "macbook pro"
    +"cat": 2
    +"price": 150000
  }
  4 => {#8 ▼
    +"id": 5
    +"user_id": 1
    +"city": "bsl"
    +"name": "macbook air"
    +"cat": 2
    +"price": 110000
  }
  5 => {#9 ▼
    +"id": 6
    +"user_id": 2
    +"city": null
    +"name": "macbook air 1"
    +"cat": 2
    +"price": 81000
  }
]
*/

假设我们想要获取查询结果中 price 的总和。我们可以通过调用 sum() 方法而不是 get() 方法轻松实现。

$result = $json->from('products')
        ->where('cat', '=', 2)
        ->sum('price');
dump($result);

//It will print:
/*
365000
*/

非常简洁，不是吗？

让我们探索完整的 API，看看这个库还能为您做什么。好吗？

API

以下 API 示例基于以下示例 JSON 数据给出这里。要更好地了解示例，请先查看 JSON 数据。有关每个 API 的详细示例，请参阅这里。

API 列表

at
avg
chunk
collect
column
copy
count
each
except
exists
fetch
filter
find
first
from
groupBy
implode
import
json
keys
last
macro
max
min
nth
orWhere
pipe
reset
select
size
sort
sortBy
sum
then
toJson
transform
values
where
whereContains
whereEndsWith
whereIn
whereMatch
whereNotIn
whereNull
whereNotNull
whereStartsWith

`fetch()`

此方法将执行查询并返回结果数据。您需要在使用一些查询方法后最终调用它。详细信息可以在其他 API 示例中找到。

`find(path)`

path -- 您要查找的数据的路径层次结构。

在此之后，您不需要调用 fetch() 方法。因为这个方法会自行获取并返回数据。

注意：您不能在它之后链式调用更多的查询方法。如果您需要这样做，应该使用 at() 或 from() 方法。

示例

假设您想获取您Json数据中 'cities' 属性的值。您可以这样做

$q = new Jsonq('data.json');
echo $q->find('vendor.name');

如果您想遍历到层次结构更深的层级，可以这样做

$q = new Jsonq('data.json');
echo $q->find('vendor.name');

请在此处查看详细示例这里。

`from(path)`

path (可选) -- 您想要开始查询的数据的路径层次结构。

默认情况下，查询将从您提供的JSON数据的根开始。如果您想首先移动到您想要开始查询的嵌套路径层次结构，您将使用此方法。省略 path 参数或使用 '.' 作为参数也将从根数据开始查询。

此方法与 find() 方法的区别在于，find() 方法将返回给定路径层次结构的数据。另一方面，此方法将返回对象实例，因此您可以在其后进一步链式调用查询方法。

示例

假设您想开始查询您的Json数据中 'vendor.name' 属性的值。您可以这样做

$q = new Jsonq('data.json');
echo $q->from('vendor.name')->get();

如果您想遍历到层次结构更深的层级，可以这样做

$q = new Jsonq('data.json');
echo $q->from('users.5.visits')->get();

请在此处查看详细示例这里。

`at(path)`

这是 from() 方法的别名，其行为与此完全相同。请在此处查看示例这里。

`where(key, condition, val)`

key -- 数据的属性名。或者，您也可以在这里传递一个函数来在它内部包含多个查询。请参阅示例了解详细信息。
val -- 要匹配的值。它可以是一个 int、string、bool 或甚至是 Function - 依赖于 op。
op -- 用于匹配的运算符。以下运算符可供使用
- = : 用于弱等价匹配
- eq : 与 = 相同
- != : 用于弱不等价匹配
- neq : 与 != 相同
- == : 用于严格等价匹配
- seq : 与 == 相同
- !== : 用于严格不等价匹配
- sneq : 与 !== 相同
- > : 检查数据中给定 key 的值是否大于 val
- gt : 与 > 相同
- < : 检查数据中给定 key 的值是否小于 val
- lt : 与 < 相同
- >= : 检查数据中给定 key 的值是否大于或等于 val
- gte : 与 >= 相同
- <= : 检查数据中给定 key 的值是否小于或等于 val
- lte : 与 <= 相同
- null : 检查数据中给定 key 的值是否为 null （在 where() 中，此 op 可省略 val 参数）
- notnull : 检查数据中给定 key 的值是否不为 null （在 where() 中，此 op 可省略 val 参数）
- in : 检查数据中给定 key 的值是否存在于给定的 val 中。 val 应该是一个普通的 Array。
- notin : 检查数据中给定 key 的值是否不存在于给定的 val 中。 val 应该是一个普通的 Array。
- startswith : 检查数据中给定 key 的值是否以（具有前缀）给定 val 开头。这仅适用于 String 类型的数据。
- endswith : 检查数据中给定 key 的值是否以（具有后缀）给定 val 结尾。这仅适用于 String 类型的数据。
- contains : 检查数据中给定 key 的值是否包含给定 val 的子字符串。这仅适用于 String 类型的数据。
- match : 检查数据中给定 key 的值是否与给定 val 的正则表达式匹配。对于此 op，val 参数应是一个 RegExp。
- macro : 将尝试执行给定的 val 来匹配数据中给定 key 的值。对于此 op，val 参数应是一个 Function。此函数内部应包含匹配逻辑，并根据该逻辑返回 true 或 false。

示例

例如，如果您想找到具有 id 为 1 的 'users'，可以这样做

$q = new Jsonq('data.json');
$res = $q->from('users')->where('id', '=', 1)->get();

您可以为 where 条件添加多个条件。它将通过 AND 操作连接这些多个 where 条件来给出结果。

$q = new Jsonq('data.json');
$res = $q->from('users')
->where('id', '=', 1)
->where('location', '=', 'barisal')
->get();

请在此处查看详细信息示例这里。

`orWhere(key, op, val)`

where() 的参数与 orWhere() 相同。唯一的区别是：orWhere() 方法给出的条件将与其他条件进行 OR 操作。

例如，如果您想找到具有 id 为 1 或 2 的用户，可以这样做

$q = new Jsonq('data.json');
$res = $q->from('users')
->where('id', '=', 1)
->orWhere('id', '=', 2)
->get();

请在此处查看详细信息示例这里。

`whereIn(key, val)`

key -- 数据的属性名
val -- 它应该是一个 Array

此方法的行为类似于 where(key, 'in', val) 方法调用。

`whereNotIn(key, val)`

key -- 数据的属性名
val -- 它应该是一个 Array

此方法的行为类似于 where(key, 'notin', val) 方法调用。

`whereNull(key)`

key -- 数据的属性名

此方法的行为类似于 where(key, 'null') 或 where(key, '=', null) 方法调用。

`whereNotNull(key)`

key -- 数据的属性名

此方法的行为类似于 where(key, 'notnull') 或 where(key, '!=', null) 方法调用。

`whereStartsWith(key, val)`

key -- 数据的属性名
val -- 它应该是一个 String

此方法的行为类似于 where(key, 'startswith', val) 方法调用。

`whereEndsWith(key, val)`

key -- 数据的属性名
val -- 它应该是一个 String

此方法的行为类似于 where(key, 'endswith', val) 方法调用。

`whereContains(key, val)`

key -- 数据的属性名
val -- 它应该是一个 String

此方法的行为类似于 where(key, 'contains', val) 方法调用。

`sum(column)`

column -- 数据的属性名

示例

例如，如果您想找到 'products' 中 'price' 的总和，可以这样做

$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->sum('price');

如果您正在聚合的数据是纯数组，您不需要传递 'column' 参数。请在此处查看详细信息示例这里

`count()`

它将返回集合中的元素数量。

示例

例如，如果您想找到 'products' 属性中的元素数量，可以这样操作

$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->count();

请在此处查看详细信息示例这里。

`size()`

这是 count() 的别名方法。

`max(column)`

column -- 数据的属性名

示例

例如，如果您想找到 'products' 中 'price' 的最大值，可以这样做

$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->max('price);

如果您正在查询的数据是纯数组，您不需要传递 'column' 参数。请在此处查看详细信息示例这里

`min(column)`

column -- 数据的属性名

示例

例如，如果您想找到 'products' 中 'price' 的最小值，可以这样做

$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->min('price');

如果您查询的数据是纯数组，则无需传递'property'参数。请查看详细示例此处

`avg(column)`

column -- 数据的属性名

示例

假设您想找到'products'的'price'的平均值。您可以这样操作

$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->avg('price');

如果您查询的数据是纯数组，则无需传递'column'参数。请查看详细示例此处

`first()`

它将返回集合的第一个元素。

示例

$q = new jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->first();

请查看详细示例此处。

`last()`

它将返回集合的最后一个元素。

示例

$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->last();

请查看详细示例此处。

`nth(index)`

index -- 要返回的元素的索引。

它将返回集合的第n个元素。如果给定的索引是正数，则从开始处返回第n个元素。如果给定的索引是负数，则从末尾返回第n个元素。

示例

$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->nth(2);

请查看详细示例此处。

`exists()`

如果元素不是空或不是null或不是一个空数组或不是一个空对象，它将返回true。

示例

例如，如果您想找到 'products' 属性中的元素数量，可以这样操作

$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->exists();

请查看详细示例此处。

`groupBy(column)`

column -- 您想要按此属性分组集合。

示例

假设您想根据'location'属性对'users'数据分组。您可以这样做

$q = new Jsonq('data.json');
$res = $q->from('users')
->groupBy('location')
->get();

请查看详细示例此处。

`sort(order)`

order -- 如果您省略了'order'属性，则默认按升序排序。您需要将'desc'作为'order'参数传递，以便按降序排序数据。您还可以在'order'参数中传递一个比较函数，以定义自己的数据排序逻辑。

注意：此方法应用于纯数组。如果您想对对象数组进行排序，应使用稍后描述的sortBy()方法。

示例

假设您想对'arr'数据进行排序。您可以这样做

$q = new Jsonq();
$res = $q->collect([7, 5, 9, 1, 3])
->sort();

请查看详细示例此处。

`sortBy(column, order)`

column -- 您需要传递排序将进行的列名。
order -- 如果您省略了'order'属性，则默认按升序排序。您需要将'desc'作为'order'参数传递，以便按降序排序数据。您还可以在'order'参数中传递一个比较函数，以定义自己的数据排序逻辑。

注意：此方法应用于对象数组。如果您想对纯数组进行排序，应使用前面描述的sort()方法。

示例

假设您想对'products'的'price'数据进行排序。您可以这样做

$q = new Jsonq('data.json');
$res = $q->from('products')
->where('cat', '=', 1)
->sortBy('price', 'desc');

请查看详细示例此处。

`reset(data)`

data -- 可以是JSON文件路径，或JSON字符串或JSON对象。如果没有在data参数中传递数据，则jsonQ对象实例将重置为先前初始化的数据。

在任何时候，您可能希望将对象实例重置为完全不同的数据集，然后查询它。在这种情况下，您可以使用此方法。

请查看详细示例此处。

`copy()`

它将返回对象实例的完整克隆。

请查看详细示例此处。

错误和问题

如果您遇到任何错误或问题，请随时在 GitHub 上提交问题。

此外，您也可以通过 mailto:nahid.dns@gmail.com 发送电子邮件给我，以报告拥抱或错误。

其他平台

该包还支持不同的语言。

JavaScript JsonQ 由 Ahmed shamim 开发
Python JsonQ 由 Shaon Shaonty 开发
Go JsonQ 由 Saddam H 开发 - 即将推出

在 Beerpay 上支持

嘿，兄弟！请帮我喝杯 🍻！

nahid / jsonq

维护者

详细信息

README

支持本项目

注意

请勿直接从以下版本更新到 >= 6.0 版本

安装

使用方法

API

fetch()

find(path)

from(path)

at(path)

where(key, condition, val)

orWhere(key, op, val)

whereIn(key, val)

whereNotIn(key, val)

whereNull(key)

whereNotNull(key)

whereStartsWith(key, val)

whereEndsWith(key, val)

whereContains(key, val)

sum(column)

count()

size()

max(column)

min(column)

avg(column)

first()

last()

nth(index)

exists()

groupBy(column)

sort(order)

sortBy(column, order)

reset(data)

copy()

错误和问题

其他平台

在 Beerpay 上支持

`fetch()`

`find(path)`

`from(path)`

`at(path)`

`where(key, condition, val)`

`orWhere(key, op, val)`

`whereIn(key, val)`

`whereNotIn(key, val)`

`whereNull(key)`

`whereNotNull(key)`

`whereStartsWith(key, val)`

`whereEndsWith(key, val)`

`whereContains(key, val)`

`sum(column)`

`count()`

`size()`

`max(column)`

`min(column)`

`avg(column)`

`first()`

`last()`

`nth(index)`

`exists()`

`groupBy(column)`

`sort(order)`

`sortBy(column, order)`

`reset(data)`

`copy()`