README

laravel query 包为基于 Laravel 的项目提供 drewlabs/query 库的绑定。它使用 Laravel 的 Eloquent API 进行数据库查询。

使用方法

提供者

• Laravel 当使用 Laravel 框架时，服务提供者会自动注册。
• Lumen 对于 Lumen 应用，您必须在 bootstrap/app.php 中手动注册提供者。

// bootstrap/app.php
// ...
$app->register(\Drewlabs\Laravel\Query\ServiceProvider::class);
// ...

组件

查询语言

该组件提供了一种统一的语言，用于使用 SELECT、CREATE、UPDATE 和 DELETE 方法查询数据库。它大量使用了 PHP 字典（即数组）进行各种操作。

创建 DMLManager 实例

// ...
use function Drewlabs\Laravel\Query\Proxy\DMLManager;

// Example class
use App\Models\Example;

// Create a query manager for querying database using Example model
$ql = DMLManager(Example::class);

创建 API

该方法接收要插入数据库表的属性作为行。

// Insert single values to the database
$example = DMLManager(Example::class)->create([/* ... */]);

注意：在复杂形式中，create 方法接收要插入的属性和一系列参数。

$person = DMLManager(Example::class)->create([
        /* ... */
        'addresses' => [ [/* ... */] ],
        'profile' => [/* ... */]
    ],[
        // Here we tells the query provider to use `profile`, `addresses` keys of `inputs` as relation
        // methods of the model class
        'relations' => ['addresses', 'profile']
    ]);

create 方法还接收第三个参数 PHP 闭包，该闭包可以在创建操作之后执行。

示例

// Insert single values to the database
$example = DMLManager(Example::class)->create([/* ... */], function($value) {
    // Do something with the created value
});

更新 API

与 create 方法类似，update 方法也提供了与数据库交互的重载方法实现。

$person = DMLManager(Example::class)->update(1, ['firstname' => '...']);

// Update by ID String
$person = DMLManager(Example::class)->update("1", ['firstname' => '...']);

// Update using query without mass update
$count = DMLManager(Example::class)->update(['and' => ['name', '...']], ['firstname' => '...']);

删除 API

删除提供了一个基于 ID 或复杂查询删除条目的接口。

// DELETE AN ITEM BY ID
$result = DMLManager(Example::class)->delete(1);

// DELET AN ITEM USING QUERY FILTERS
$result = DMLManager(Example::class)->delete(['and' => ['...', '...']], true);

选择 API

DMLManager 的 select 方法提供了一个用于使用查询过滤器在数据库中查询行的单个方法。

$person = DMLManager(Person::class)->select("1", ['*'], function ($model) {
    return $model->toArray();
});

// Select by ID
$person = DMLManager(Person::class)->select(1);

$list = DMLManager(Person::class)->select([/* ... */],['firstname', 'addresses']);

// Select using query filters
$list = DMLManager(Person::class)->select([/* ... */], 15, ['addresses', 'profile'], 1);

查询过滤器

过滤器提供了一个统一的接口来执行数据库查询。

• CreateQueryFilters API

CreateQueryFilters 是一个工厂函数，当被调用时，为 Laravel 数据库库创建一个过滤器绑定。

use Drewlabs\Laravel\Query\Proxy\CreateQueryFilters;

/// Note: Each key is an eloquent model/Eloquent query builder method
/// Parameters are passed in the order and the same way they are passed to the model method, but are specified as array
$filter = CreateQueryFilters([
    // Creatigng a where query
    'where' => [
        ['label', '<LabelValue>'],
        ['slug', 'like', '<SlugValue>']
    ],
    'orWhere' => ['id' , '<>', '<IDValue>'],
    'whereHas' => ['relation_name', function($query){
        // ... Provide the subquery
    }],
    // Multiple subqueries at once
    'whereDoesntHave' => [
        ['relation1', function($query){
        // ... Provide the subquery
        }],
        ['relation1', function($query){
        // ... Provide the subquery
        }]
    ],
    // Query date field
    'whereDate' => [$date],

    // Query relation presence
    'has' => 'hasRelation',

    // Query presence of multiple relations
    'has' => ['relation1', 'relation2'],

    // Where in query
    'whereIn' => ['column', [...]],

    // Multiple WherNotIn query

    'whereNotIn' => [
        ['colum1', [...]],
        ['colum2', [...]]
    ],

    // Join query
    'join' => [
        Folder::class,
        ['model' => UploadedFile::class, 'column' => 'folder_id'],
        ['model' => Folder::class, 'column' => 'id']
    ],
    // Normal laravel join
    'join' => ['table1', 'table2.id', '=', 'table1.user_id']
]);

// Calling the query filter on laravel database builder instance
$result = $filter->call(TestModel::query())->get($columns = ['*']);

查询过滤器 API

查询过滤器 API 提供了一系列过滤器，可用于使用 PHP 键值对数组（即字典）通过框架数据库 API 发送查询。

示例

// imports
// ...

// Create the request
$request = new \Illuminate\Http\Request([
    '_query' => [
        'where' => ['label', '<>', 'Hello World!'],
        'orWhere' => [
            [
                'match' => [
                    'method' => 'whereIn',
                    'params' => ['url', [/* ... */]]
                ]
            ],
            [
                'id', 340
            ]
        ],
        'whereNull' => [
            'column' => 'basepath'
        ],
        'whereIn' => [
            [
                "column" => 'basepath',
                "match" => ['/home/usr/workspace', '/local/usr/Cellar/etc/workspace']
            ],
            [
                'fullpath',
                ['/home/usr/workspace', '/local/usr/Cellar/etc/workspace']
            ]
        ]
    ],
    'label' => 'Are you there ?',
    'id' => 320
]);

// Create query filters from framework request object
$result = \Drewlabs\Query\PreparesFiltersBag::new($request)->build(new TestModel);

• 以下是该包支持的查询方法列表

$methods = [
    'where',
    'whereHas',
    'whereDoesntHave',
    'whereDate',
    'has',
    'doesntHave',
    'whereIn',
    'whereNotIn',
    // Added where between query
    'whereBetween',
    'orWhere',
    'orderBy',
    'groupBy',
    'skip',
    'take',
    // Supporting joins queries
    'join',
    'rightJoin',
    'leftJoin',
    // Supporting whereNull and whereNotNull queries
    'whereNull',
    'orWhereNull',
    'whereNotNull',
    'orWhereNotNull'
]

警告 实体对象/查询模型必须实现 Drewlabs\Query\Contracts\Queryable 接口，以便与查询方法调用兼容。

命令 API

命令 API 提供了使用框架 API 向数据库发送查询的函数。

use function Drewlabs\Laravel\Query\Proxy\useActionQueryCommand;
use function Drewlabs\Laravel\Query\Proxy\DMLManager;
use function Drewlabs\Laravel\Query\Proxy\SelectQueryAction;
use function Drewlabs\Support\Proxy\Action;

$command = useActionQueryCommand(Test::class);

// Calling command with an action using `call` method
$result = $command->call(SelectQueryAction($id));

// Calling the command using a callable interface
$result = $command(Action('SELECT' , $id));

// Creating and calling the the command API
useActionQueryCommand(Test::class)(SelectQueryAction($id));

选择查询操作

SelectQueryAction 代理函数提供了一个无错函数来创建类型为 SELECT 的数据库查询操作。

• SelectQueryAction($id [, array $columns, \Closure $callback])

use function Drewlabs\Laravel\Query\Proxy\SelectQueryAction;

// ...

// Example
$action = SelectQueryAction($id) // Creates a select by id query

• SelectQueryAction(array $query [, array $columns, \Closure $callback])
• SelectQueryAction(array $query, int $per_page [?int $page = null, array $columns, \Closure $callback])

use function Drewlabs\Laravel\Query\Proxy\SelectQueryAction;

//...

// Example
$action = SelectQueryAction([ 'where' => ['id', 12] ]);

• SelectQueryAction(FiltersInterface $query [, array $columns, \Closure $callback])
• SelectQueryAction(FiltersInterface $query, int $per_page [?int $page = null, array $columns, \Closure $callback])

use function Drewlabs\Laravel\Query\Proxy\CreateQueryFilters;
use function Drewlabs\Laravel\Query\Proxy\SelectQueryAction;

// ...
// Example
$action = SelectQueryAction(CreateQueryFilters(...));

更新查询操作

UpdateQueryAction 代理函数提供了一个无错函数来创建类型为 UPDATE 的数据库查询操作。

• UpdateQueryAction($id, array|object $attributes [, \Closure $callback])

use function Drewlabs\Laravel\Query\Proxy\UpdateQueryAction;

// ...

// Example
$action = UpdateQueryAction($id, ['name' => 'John Doe'])

• UpdateQueryAction(array $query, array|object $attributes [, \Closure $callback])

use function Drewlabs\Laravel\Query\Proxy\UpdateQueryAction;

// ...

// Example
$action = UpdateQueryAction(CreateQueryFilters(...), ['name' => 'John Doe'])

• UpdateQueryAction(FiltersInterface $query, array|object $attributes [, \Closure $callback])

use function Drewlabs\Laravel\Query\Proxy\UpdateQueryAction;
use function Drewlabs\Laravel\Query\Proxy\CreateQueryFilters;

// ...

// Example
$action = UpdateQueryAction(['where' => ['id' => 3]], ['name' => 'John Doe'])

删除查询操作

创建一个使用函数用户提供的 DELETE 类型查询操作。

• 删除查询操作($id [, \Closure $callback])

use function Drewlabs\Laravel\Query\Proxy\DeleteQueryAction;

// ...

// Example
$action = DeleteQueryAction($id)

• 删除查询操作(array $query [, \Closure $callback])

use function Drewlabs\Laravel\Query\Proxy\DeleteQueryAction;

// ...

// Example
$action = DeleteQueryAction(['where' => ['id' => 3]])

• 删除查询操作(FiltersInterface $query [, \Closure $callback])

use function Drewlabs\Laravel\Query\Proxy\DeleteQueryAction;
use function Drewlabs\Laravel\Query\Proxy\CreateQueryFilters;

// ...

// Example
$action = DeleteQueryAction(CreateQueryFilters(...))

创建查询操作

使用函数user提供用户创建一个CREATE类型的查询操作

• 创建查询操作(CreateQueryAction) (array $attributes [, array $params, \Closure $callback])

use function Drewlabs\Laravel\Query\Proxy\CreateQueryAction;

// ...

// Example
$action = CreateQueryAction([...])

• 创建查询操作(CreateQueryAction) (object $attributes, [, array $params , \Closure $callback])

use function Drewlabs\Laravel\Query\Proxy\CreateQueryAction;

// ...

// Example
$object = new stdClass;
$object->name = 'John Doe';
$object->notes = 67;

$action = CreateQueryAction($object);

注意 为了使创建函数更可定制，该函数支持第二个参数，允许开发者提供他们自己的自定义操作处理器。

use function Drewlabs\Laravel\Query\Proxy\useActionQueryCommand;
use function Drewlabs\Laravel\Query\Proxy\DMLManager;
use use Drewlabs\Contracts\Support\Actions\Action;

$command = useActionQueryCommand(TestModel::class, function(Action $action, ?\Closure $callback = null) {
     // Provides custom action handlers
});