README

一些小组件，使yii2 api开发生活更轻松

安装

composer require ddruganov/yii2-api-essentials

描述

此包包含用于api开发的有用类（过滤器、行为、助手等）

• behaviors\TimestampBehavior：为具有'created_at'和'updated_at'字段的Active Record模型提供基本的时间戳（自动检测其存在性）
• collectors\AbstractDataCollector：方便收集API调用数据的便捷方式
• exceptions\ModelNotFoundException：当在数据库中搜索模型失败时
• exceptions\NotImplementedException：当你需要编写方法的实现但...以后 :D
• forms\Form：一个执行数据验证并按特定方式操作的容器；对于不直接使用ActiveRecord创建模型非常有用；还用作数据收集器的基础
• http\actions\ApiAction：所有API操作的基类，提供获取所有传入数据作为数组的途径；返回一个ExecutionResult和适当的执行结果状态码；
• http\actions\ClosureAction：当ApiModelAction过于冗余时
• http\actions\FormAction：提供一种将数据验证和保存数据分开的方法，以减少类膨胀；使用Form
• http\controllers\ApiController：返回所有内容为json，测量每个请求的时间并使所有API调用为事务性
• http\filters\TimerFilter：测量操作所花费的时间并将结果输出到调试日志
• http\filters\TransactionFilter：在操作之前启动事务，在操作之后结束事务；依赖于ExecutionResult的成功
• testing\UnitTest：基单元测试类；提供了一种方便的方式来断言ExecutionResult状态和可定制的假数据生成器
• traits\Activity：在ActiveQuery中使用，以仅获取活动模型
• traits\Pagination：在ActiveQuery中使用，以设置列表查询中的页码和获取页数
• traits\Sorting：在ActiveQuery中使用，以对模型进行排序；默认字段是created_at
• traits\SoftDelete：在ActiveRecord中使用，当模型被删除时，将deleted_at字段填充为date('Y-m-d H:i:s')
• DateHelper：日期操作的一些有用方法
• ExecutionResult：基本上是一个具有特定结构的静态类型数组版本，以确保所有处理数据的方法返回相同的结构，但不仅限于这一点

ApiController 示例

class TestController extends ApiController
{
    public function actions()
    {
        return [
            'test1' => [
                'class' => ClosureAction::class,
                'closure' => function () {
                    Yii::debug('this is a closure action');
                    return ExecutionResult::success();
                }
            ],
            'test2' => [
                'class' => FormAction::class,
                'formClass' => TestCollector::class
            ],
            'test3' => [
                'class' => FormAction::class,
                'formClass' => TestForm::class
            ]
        ];
    }
}

TestCollector和TestForm扩展了forms\Form

ActiveQuery 特性示例

class SomeModelQuery extends ActiveQuery {
    use Activity, Pagination, Sorting;
}

ActiveRecord相关组件示例

class SomeActiveRecord extends ActiveRecord {

    use SoftDelete;

    public function behaviors() {
        return [TimestampBehavior::class];
    }
}

Form 示例

class SomeModelCreationForm extends Form {
    public ?string $name = null;
    public ?array $someRelatedModelIds = null;

    public function rules() {
        return [
            [['name','someRelatedModelIds'],'required'],
            [['name'],'string'],
            [['someRelatedModelIds'],'each', 'rule' => ['integer']]
        ];
    }

    protected function _run(): ExecutionResult {
        $model = new SomeModel();
        $model->setAttributes(['name' => $this->name]);
        if (!$model->save()) {
            return ExecutionResult::exception('Error saving model');
        }

        $result = $this->saveRelatedModelIds($model);
        if (!$result->isSuccessful()){
            return $result;
        }

        return ExecutionResult::success([
            'id' => $model->getId()
        ]);
    }

    private function saveRelatedModelIds(SomeModel $model) {
        ... bind related model ids here
    }
}