README

Dlin Symfony Array Conversion Bundle

正在使用 Symfony2 构建 RESTFul API？你可能已经尝试过 FriendsOfSymfony/FOSRestBundle Bundle。

如果你像我一样，你可能会认为 FriendsOfSymfony/FOSRestBundle 非常棒，但它很复杂，并且不支持你真正想要的灵活性。

让我们再次思考一下构建 RESTful API 真正需要什么

内容协商

你真的需要这个吗？我最近构建的所有 API 都只支持 JSON，没有协商。
资源 URL 路由 如果你不需要内容协商，好消息是 Symfony 本身就做得很好，你可以简单使用正常控制器来处理 API 端点。
序列化，即转换为数组然后是 JSON

这很重要。你真的需要这个，不仅是为了 Doctrine 实体，也是任何对象。

你有时想将额外的详细信息（例如元数据或错误详细信息）包装在响应中。

你有时想通过getter函数公开数据。

你有时想使用不同的名称作为键。

Symfony2 自带 JsonResponse 类，它可以自动将关联数组转换为 JSON 对象响应体。缺少的部分是将你的实体/对象转换为关联数组的部分。Dlin/Converter 可以帮助。
接受请求以更新资源

你希望能够处理用户提交的数据并轻松更新实体对象

你希望能够轻松使用从浏览器提交的数据“滋养”实体/对象。然而，你通常需要手动重复地将值分配给实体，在验证用户输入之后。

Symfony2 带有对实体验证的内置支持，缺少的是轻松“滋养”实体的简单方法。Dlin/Converter 可以帮助。
权限控制

某些资源的字段只能由特定角色的用户访问。例如，只有管理员用户可以更新公司的名称。

有时你想根据某些条件控制可读/可写内容。

与 FOSRestBundle 一样，Dlin/ArrayConverter 支持为字段分配 'groups'。在将实体转换为数组或从数组“滋养”实体时，你可以指定哪些字段是可读/可写的，通过规范包含/排除哪些组。你可以通过指定包含/排除哪些字段来获得更多控制。

版本

0.2

安装

使用 Composer 进行安装

将以下内容添加到您的 composer.json

{
    "require" :  {
        "dlin/array-conversion-bundle": "dev-master"
    }
}

在 AppKernel.php 中启用该 Bundle

public function registerBundles()
{
    $bundles = array(
    ...
    new Dlin\Bundle\ArrayConversionBuddle\DlinArrayConversionBundle(),
    ...
}

注解

只有两种注解选项：“groups” 和 “key”。

注解适用于所有属性和方法，公开或非公开。

如果方法被注解，则在转换为数组时将没有任何参数地调用该方法。返回值用作结果数组中的字段值，而默认情况下将使用方法名作为数组索引。在“滋养”实体/对象时，方法将带有一个参数调用。通常，你会在“读取”组中添加getter函数，在“写入”组中添加setter函数。然而，组的确切定义完全由开发者决定。

如果属性被注释，则在实体和数组之间转换时，它将被获取/设置。请注意，私有属性也会被更新。

可以使用 key 选项来指定属性或方法的不同的键名，并使用 group 选项将多个属性分组，以便稍后用于权限控制。

如果多个属性或方法具有相同的键。在调用 toArray 时，最后一个将覆盖其他属性。然而，在从数组 fromArray 中'复活'时，所有字段和方法都将被设置/调用。

示例

use \Dlin\Bundle\ArrayConversionBundle\Annotation\ArrayConversion;

class PersonEntity {

    /**
     * If 'key' not given, it use 'firstName' by default
     * @ArrayConversion( groups={"read", "write"})
     */
    private $firstName;

    /**
     * You can use a different array key by specifying a different key value
     * In this example, 'last' will be used as key instead of 'lastName' in the resulting array
     * @ArrayConversion( key="last", groups={"read", "write"})
     */
    private $lastName;

    /**
     * @ArrayConversion( key="age", groups={ "write"})
     */
    private $age;


    /**
     * You can also convert the result of a getter function into the resulting array,
     * If the 'key' is not specified, the function name will be used (i.e 'getFullName') as the key in the resulting array
     * @ArrayConversion(key="fullName", groups={"read"})
     */
    public function getFullName(){

        return trim($this->firstName.' '.$this->lastName);
    }

    /**
     * You can also do this for setter function.
     * This function is called when the 'fromArray' service method is called. This is useful when you want to assign values to object
     * using setter functions instead of setting values for the private properties directly.
     * @ArrayConversion( key="age", groups={ "write"})
     */
    public function setFullName($fullname){
        ...
    }



    ...
}

用法

在控制器中获取服务

$converter =  $this->get('dlin.array_converter');

在 ContainerAwareService 中获取服务

$converter = $this->container->get('dlin.array_converter');

### 使用 "toArray" 方法

"toArray" 方法将注释的实体对象转换为数组。它接受 3 个参数

对象
包含组名的数组。具有与结果数组中匹配的组名的属性将进入结果数组。您可以在组名前加 '-' 来排除具有该组的字段。例如，['user', '-adminuser'] 将包括标记为在 user 组中的属性，但不包括在 adminuser 组中的属性。如果属性同时标记为在两个组中，则它不会进入结果数组。
包含要包含/排除的属性键的数组。您可以通过传递此参数给 'toArray' 方法来覆盖组选择。例如，['username', '-password'] 将包含属性 'username' 并排除 'password'，无论组名如何匹配。
布尔值。跳过具有 null/false/空值的属性。默认为 true。

示例

$person = new PersonEntity();
$person->setFirstName('Hello');
$person->setLastName('Kitty');
$person->setAge(12);

#at least one group must given, otherwise empty array returns
$res = $converter->toArray($person, array('read'));

//$this->assertEquals($res['firstName'], $person->getFirstName());
//$this->assertEquals($res['last'], $person->getLastName());
//$this->assertEquals($res['fullName'], $person->getFullName());

### 使用 "fromArray" 方法

"fromArray" 方法使用给定数组的值'复活'对象。它接受 2 个参数

对象/实体
包含组名的数组。如果从给定的数组中找到值，则将具有匹配组名的属性'复活'。您可以在组名前加 '-' 来排除具有该组的字段。例如，['user', '-adminuser'] 将更新标记为在用户组中的属性，但不更新在 adminuser 组中的属性。如果属性同时标记为在两个组中，则它不会被更新

与 "toArray" 方法不同，它不接受第三个参数来覆盖组选择。

$person = new PersonEntity();
$person->setFirstName('Hello');
$person->setLastName('Kitty');
$person->setAge(12);

$array = array('firstName'=>'New Name', 'age'=>13);

$converter->fromArray($person, $array, array('write')); #must specify a or more group

//$this->assertEquals("New Name", $person->getFirstName());
//$this->assertEquals(13, $person->getAge());

注意

'fromArray' 将直接设置目标对象的属性，即使对于私有属性也是如此。要使用setter/getter函数，请将注解放置在getter/setter函数上。

许可证

MIT

免费软件，是的！

dlin / array-converter-bundle

维护者

详细信息

README

版本

安装

注解

用法

注意

许可证