README

使用此库，您可以使用 On Page ® API 令牌轻松查询数据。

安装

要安装此库到现有的 composer 项目，或更新到最新版本，您可以启动

composer require onpage-dev/onpage-php:^v1.2

当然，请记住包括 composer 自动加载

<?php
require 'vendor/autoload.php';

使用方法

设置

首先，您需要使用以下函数连接到 On Page 架构（项目）

$schema = \OnPage\Schema::fromToken('MY-API-TOKEN');

查询数据

// Retrieve all records of a resource (returns a laravel collection of \OnPage\Thing)
$products = $schema->query('products')->all();
foreach ($products as $prod) {
    // ...
}

// Get only the first item
$prod = $api->query('products')->first();

筛选和删除

// Retrieve all records of a resource (returns a laravel collection of \OnPage\Thing)
// NOTE: system fields must be prefixed with the _ symbol
$api->query('products')
    ->where('_id', 42) // = is the default operator
    ->where('_created_at', '<', '2024-01-01 00:00:00')
    ->where('_updated_at', '>=', '2024-01-01 00:00:00')
    ->first();

// Other filters
$api->query('products')
    ->where('name', 'like', 'shoes') // you can specify a different operator
    ->where('category.name', 'Nike') // you can query relations
    ->where('dimension', '>', 10) // you get it
    ->whereIn('size', [42, 43, 44])
    ->all(); // returns a collection with all your records

// Join filters with the OR clause: get all products for the adidas or nike brands
$api->query('products')
    ->whereOneOf(function(\OnPage\QueryBuilder $q) {
        ->where('price', 'Nike')
        ->where('brand', 'Adidas')
    })
    ->all();

// Advanced filtering by relation
$api->query('products')

    // only retrieve products that have at least one associated category
    ->whereHas('category')

    // only retrieve products that have zero associated categories
    ->whereHas('category', null, '=', 0)

    // only retrieve products that have at least one variant with at least one color
    ->whereHas('variant.color')

    // Only get products that have at least one category that satisfies these 2 conditions:
    ->whereHas('category', function(\OnPage\QueryBuilder $q) {
      $q->where('is_online', true);
      $q->where('name', 'like', 'shoes');
    })

    ->all();

// You can just simply move data to trash the same way:
$api->query('products')
    ->where(...)
    ->delete();

// Or delete elements bypassing the trash:
$api->query('products')
    ->where(...)
    ->delete(forever: true);

// Filter by element status trash, any
$api->query('products')
    ->where(...)
    ->delete(forever: true);

获取事物值

使用 val() 函数获取字段中的第一个值。使用 values() 函数获取字段中的所有值作为集合。

$cat = $api->query('categories')->first();
echo $cat->id; // item ID
echo $cat->created_at; // creation date e.g. 2022-01-01 23:33:00
echo $cat->updated_at; // date of last update to any of the fields e.g. 2022-01-01 23:33:00
echo $cat->order; // global order number (float)
echo $cat->val('name');
echo $cat->val('dimension');
echo $cat->val('description', 'zh'); // you can specify a language

// Or set the default language
$schema->lang = 'zh';
echo $cat->val('name'); // 再见

// You can also set a fallback language
$schema->lang = 'zh';
$schema->fallback_lang = 'en';
echo $cat->val('description'); // English description if chinese description is missing

// The values function is useful for multivalue fields, it will return a laravel collection of values.
echo $cat->values('bullet_points')->implode('; ');

文件

对于 image 和 file 字段，返回值将是 \OnPage\File::class 的实例。要获取文件或图片 URL，请使用 ->link() 函数。链接将指向原始文件。

# original size
$product->file('specsheet')->name // icecream-spec.pdf
$product->file('specsheet')->token // R417C0YAM90RF
$product->file('specsheet')->link() // https://acme-inc.onpage.it/api/storage/R417C0YAM90RF?name=icecream-spec.pdf

// Force download (by default the browser will try to preview the file, e.g. pdf/images)
$product->file('specsheet')->link([ 'download' => true ])

// Customize file name
$product->file('specsheet')->link([ 'name' => 'my custom name.pdf' ])

要将图像转换为缩略图，请添加如下所示的选项数组

# maintain proportions width 200px
$product->file('cover_image')->link(['x' => 200])

# maintain proportions height 100px
$product->file('cover_image')->link(['y' => 100])

# crop image to width 200px and height 100px
$product->file('cover_image')->link(['x' => 200, 'y' => 100])

# maintain proportions and contain in a rectangle of width 200px and height 100px
$product->file('cover_image')->link(['x' => 200, 'y' => 100, 'contain' => true])

# convert the image to png (default thumbnail extension is png)
$product->file('cover_image')->link(['x' => 200, 'ext' => 'png'])

其他实用工具

// Speed things up by only loading some fields
$api->query('products')->loadFields(['title'])->all();

// You can also limit the fields on a related item
$api->query('products')
->with([ 'colors' ])
->loadRelationFields('colors', ['name', 'image']) // only load 2 fields for the "color" relation
->all();


// Get a mapping between two fields or a field and the thing ID
$api->query('products')->map('code');
// [ 'MYSKU100' => 1827, 'MYSKU101' => 1828, ... ]

$api->query('products')->map('code', 'title');
// [ 'MYSKU100' => 'Apples', 'MYSKU101' => 'Bananas', ... ]

获取事物关系

// You need to specify the relations using the "with" method
$cat = $api->query('categories')
    ->with('subcategories')
    ->first();
$subcategories = $cat->rel('subcategories');
foreach ($subcategories as $subcategory) {
    echo $subcategory->val('name');
}

// You can also preload nested subcategories
$cat = $api->query('categories')
    ->with('subcategories.articles.colors')
    ->first();

// Or you can pass the relations as an array
$products_with_colors = $api->query('products')
    ->with([ 'colors', 'categories' ])
    ->all();
foreach ($products_with_colors as $prod) {
    echo $prod->val('name');
    foreach ($prod->colors as $color) {
        echo $color->val('name');
    }
}

// If you need to filter the related items you want to download, you can do this:
$cat = $api->query('categories')
    ->with('subcategories.articles.colors')
    ->filterRelation('subcategories.articles', function(\OnPage\QueryBuilder $q) {
        $q->where('is_online', true);
    })
    ->first();

创建和更新事物

要创建或更新记录，您需要创建一个事物编辑器。有两种获取事物编辑器的方法

1. 使用 资源编写器
2. 在 Op\Thing 上调用 ->editor()

使用资源编写器（第一种方法）

此类允许您一次编辑多个记录。您可以通过调用以下内容轻松获得编辑器

$writer = $api->resource('categories')->writer();

现在您有了 资源编写器，您可以使用它来创建事物

$editor = $writer->createThing();
$editor->set('name', 'Element 1');
$editor->setRel('category', [ 12345 ]); // array with category IDs

...并更新现有的事物

$editor = $writer->updateThing(736251); // The id of the element you want to update
$editor->set('description', 'Element 1 description');

最后，您需要将请求发送到 On Page 服务器

// this will create and update all the things as requested above
$writer->save();

更新单个项目（第二种方法）

$product = $api->query('products')->where('name', 'Plastic Duck')->first();

$editor = $product->editor();
$editor->set('description', 'This yellow plastic duck will be your best friend');
$editor->set('description', '这只黄色塑料鸭将是你最好的朋友', 'zh'); // you can specify language

// Save all the edits at once using the save method
$editor->save();

限制修改的语言

默认情况下，即使您只更新一种语言，编写器也会删除其他语言上的数据。如果您只想编辑某些语言并保留其他语言当前的值，您可以指定您正在工作的语言如下

// Update the chinese description without deleting the english description:
$editor = $product->editor();
$editor->setLangs([ 'zh' ]);
$editor->set('description', '这只');
$editor->save();

更新翻译

只需将语言代码作为 set 函数的第三个参数即可

// Update the value in the default language
$editor->set('description', 'This yellow plastic duck will be your best friend');

// Specify another the language
$editor->set('description', '这只黄色塑料鸭将是你最好的朋友', 'zh');

更新文件

您可以使用 FileUpload 类将文件上传到 On Page

$editor->set('image', new \OnPage\FileUpload('/path/to/bird.jpg')); // upload file

或者您也可以使用公共 URL 上传文件

$editor->set('image', 'https://mysite.com/bird_cover.jpg'); // specify file by url

更新多值字段

对于多值字段，您只需将 ->set 替换为 ->setValues，并将值数组作为第二个参数传递

$editor->setValues('bullet_points', [
    'Durable plastic',
    'Bright yellow color',
    'Compostable'
]);

更新关系

要更新关系，您可以使用 ->setRel(relation_name, related_ids)

$editor->setRel('features', [
    425790,
    547023,
    240289,
]);

获取结构信息

// Retrieve info about the schema:
echo $schema->label;

// Retrieve a resource given its name or ID
$res = $schema->resource('products');
foreach ($res->fields() as $field) {
    echo "$field->getLabel()\n"; // Main image
    echo "$field->getLabel('zh')\n"; // "Main Image" but in Chinese
    echo "$field->name\n"; // "main_image"
    echo "$field->type\n"; // string|file|image|real|int|text|...
    echo "$field->unit\n"; // null|kg|...
    echo "$field->is_multiple\n"; // true|false
    echo "$field->is_translatable\n"; // true|false
}