README

ScopeApplicator 为您的 PHP 项目带来了优雅的数据排序和过滤方式。

• 概述
• 需求
• 安装
• 支持的框架
• 用法
• 配置选项
  • 别名
  • 类型
  • 默认值
  • 允许为空
  • 键（实验性）
• 致谢
• 贡献
• 许可证

概述

ScopeApplicator 是一种简单、逻辑性强且框架无关的实现方式

/posts – 返回所有帖子列表

/posts?recent – 返回仅最近帖子

/posts?author_id=5 – 返回属于 id=5 的作者的帖子

/posts?author_id=5&order_by_title=desc&status=active – 返回属于 id=5 的作者的仅活跃帖子，并按标题降序排序

需求

— php >= 5.4

支持的框架

• Laravel ~5.1 (文档)
• Laravel 5.0.x (文档)
• Laravel 4.x.x (文档)
• Laravel 3.x.x (文档)
• Yii 2.0.x (文档)

安装

如果您使用的是支持的框架之一，请遵循其页面上的特定框架安装说明。

否则，您可以通过以下方式安装 ScopeApplicator

composer require mobileka/scope-applicator 1.1.*

用法

如果您使用的是支持的框架之一，请遵循其页面上的特定框架用法说明。

否则，您必须为您自己的框架或 PHP 项目创建自定义绑定。

TODO: 添加有关绑定的详细说明

配置选项

ScopeApplicator 支持几个配置选项，这些将在本章中描述。

别名

有时我们不希望用户看到实际的范围名称。别名是一个键，将 URL 查询参数映射到范围名称。

示例

public $scopes = [
    'orderByTitle' => ['alias' => 'order_by_title']
];

/posts?order_by_title – 将应用 orderByTitle 范围

/posts?orderByTitle – 不应用任何范围

类型

此选项允许在将参数值传递给范围之前将其转换为类型。

当类型设置为 bool 或 boolean 时，只有 1 和 true 将转换为 true。其他所有内容都视为 false。

如果 type 设置为除 bool 或 boolean 之外的内容，将调用 settype php 函数。

示例

public $scopes = [
    'userId' => [
        'alias' => 'author_id',
        'type' => 'int'
    ],
    'new' => [
        'type' => 'bool'
    ]
];

/posts?author_id=123sometext555 – 将应用 userId 范围，参数为整数 123

/posts?new=true – 使用布尔值 true 作为参数应用 new 范围

/posts?new=yes – 使用布尔值 false 作为参数调用 new 范围

默认值

当此选项设置时，范围将应用于每个请求，即使 URL 中没有匹配范围名称或别名的查询参数。

示例

public $scopes = [
    'userId' => [
        'alias' => 'author_id',
        'default' => 5
    ]
];

/posts?author_id=1 - 使用 1 作为参数应用 userId 范围

/posts - 使用 5 作为参数应用 userId 范围

允许为空

allowEmpty 用于在将空字符串传递给范围作为参数时使用。此选项默认设置为 false，因此空字符串 不会 被传递到范围。

示例

public $scopes = [
    'userId' => [
        'alias' => 'author_id',
        'allowEmpty' => true
    ]
];

/posts?author_id – 使用空字符串 '' 作为参数应用 userId 范围。

请注意，当 allowEmpty 设置为 false（这是默认行为）时，您必须始终为范围参数提供默认值。否则，当访问 /posts?author_id 路由时，将抛出“缺少参数”异常。

另外请注意，当 allowEmpty 设置为 true 时，将忽略范围参数的默认值，并传递空字符串。

键（实验性）

当范围接受多个参数时使用键。

示例

public $scopes = [
    'createdAt' => [
        'alias' => 'created_at',
        'keys' => ['from', 'to']
    ]
];

/posts?created_at[from]=000-00-00&created_at[to]=2014-07-23 – 使用 '0000-00-00' 作为第一个参数和 '2014-07-23' 作为第二个参数应用 createdAt 范围

请注意，我目前不建议使用此功能，因为它是一个实验性功能。在将该功能标记为“稳定”之前，请创建两个单独的范围（createdAtFrom 和 createAtTo）。

致谢

范围应用器受到 has_scope Ruby 模块的启发。

贡献

如果您发现了错误或有所建议，您始终可以创建一个问题或拉取请求（使用 PSR-2）。我们将讨论问题或建议，并一起规划实现。

许可证

ScopeApplicator 是一个开源软件，并使用 MIT 许可证。