I am using fractal for my API responses, which is consumed by an Ember app and want to have a Serializer that converts to JSON API v1.0 (which will be the default in Ember's future).

I took a stab at the TODOs listed in #187:

What we need to do:

• [x] Add links
• [x] Add relationships
  • [x] to-one
  • [x] to-many
  • [x] nested relationships
  • [x] empty relationships
• [x] Always set data as resource key
• [x] Rename includes to included
• [x] Included resources should be moved outside the data object
• [x] All resources should return id, type and attributes

Additional things to do:

• [x] Write documentation for the new serializer

I will try to add the remaining TODOs over this weekend.

Please provide feedback and mention any other things we need to get done before we can implement JSON APIs with fractal.

Cheers

Since JSON-API has released their "stable" version 1.0 of the standard we should start implementing it. I know there has been some discussions about adding this but I thinks it would be good to have this in its own issue as well. What can we do to speed up this process?

What we need to do:

• [ ] Add links
• [ ] Add relationships
• [ ] Always set data as resource key
• [ ] Rename includes to included
• [ ] Included resources should be moved outside the data object
• [ ] All resources should return id, type and attributes

Please correct the todos if I've messed up. Thanks.

This is a start to implementing #15. Or at least starts to. Right now, it's just a reimplementation of the current format using an external serializer.

@philsturgeon Let me know if this is a good direction, or if you have comments, and I can implement a few other serializers...

This is a PR in relation to #24 and #18.

Seeing as @joshuajabbour doesn't have the time at the moment to continue working on the PR I've had a crack at an implementation and would love some feedback.

The Implementation

At its core is the SerializerInterface which has 5 method signatures declared. Each serializer implements these methods to return the data in a format of their desire. Included is a basic ArraySerializer, which returns the data in what I consider an untouched form. Resulting JSON from the ArraySerializer would be:

{
    "id": 1,
    "name": "Bob",
    "age": 32,
    "embeds": [
        "posts"
    ]
}

Benefit here is for systems returning pre-keyed data (above would have the user data keyed to user, for example).

The default used serializer would be the (current) DataArraySerializer which keys the top level data to data.

{
    "data": {
        "id": 1,
        "name": "Bob",
        "age": 32
    },
    "embeds": [
        "posts"
    ]
}

The serializer is set on the Manager via the setSerializer method.

$manager = new League\Fractal\Manager;

$manager->setSerializer(new League\Fractal\Serializer\ArraySerializer);

If no serializer is set the default DataArraySerializer is used.

Meta Data

This PR also includes meta data support for resources. Instead of defining a method on transformers I've opted for a (hopefully) better approach by setting the meta data on the resource.

$user = new User('Bob', '23');

$resource = new League\Fractal\Resource\Item($user, new UserTransformer);

$resource->setMeta(array('token' => 'kan1$isdd098hjasd89hsa#$9q'));

The ArraySerializer simply merges with the top level much like it does with the standard data and the DataArraySerializer would key it to meta and merge to the top level.

Tests

I've not done any tests yet merely patched the existing tests that failed due to the new meta data key. Will do tests once some more feedback is received on the approach and implementation.

Cheers.

I have been looking over your todo list, and was wondering what ideas you had on implementing that feature. In your todo list example you have: ?embed=foo:limit(5):order(something,asc)

I have messed around with parsing that string into the requestedScopes, into a format something like the following:

// This is obviously just a prototype
array(
   'foo' => array(
     'limit' => 5,
     'order' => 'asc'
   ),
   'bar' => array(
     'limit' => 10
   )
)

I guess I am just having a hard time figuring out how you would get something like, bar's limit into the paginator (if it exists) for that resource, or when/how you'd get the order direction and apply it to foo.

Hopefully this question makes sense, and hopefully I can actually contribute something to the repo instead of just using it (thanks by the way!)

It would be great if we could add meta data inline and not only inside meta path.

ie: { "data":{'a':1,'b':2}, "meta":{'extra':here'}, "iWantExtraHere":"ifThatIsPossible" }

I've got a resource with a custom transformer. It has some available includes for other resources with custom transformers. Sometimes, those other resources are null. If that child resource is included, I get an error that you can't transform a null value (due to type hinting as in the examples). I can fix that by providing a null default value to the transform() method, and my transform() method can return null, but I then get an exception thrown on an attempted array_merge() call where Fractal tries to merge the return value with another array. How can I avoid this? What's the correct way for me to indicate a child resource is not present (null)?

Is it possible to register my transformers once for a given model?

To work off of your examples in Build APIs you won't hate we are returning from each controller method as so:

return $this->responseWithItem($place, new PlaceTransformer);

It would be cool if Fractal would already know "hey this is instanceof Place, we have something registered for that", negating the need for me to write new {model}Transformer.

I'm having a problem with Fractal library. I'm using spatie\laravel-fractal library which is just wrapper for thephpleague/fractal. So...

I want to return an empty object instead of an empty array.

public function includeDocumentType(Question $question)
{
    return $question->documentType
        ? $this->item($question->documentType, new DocumentTypeTransformer)
        : $this->null();
}

$this->null() always returns [] after generation and I want to return {}. Tbh I want to have 2 functions like $this->nullItem() and $this->nullCollection().

Does anyone know what's the solution to this problem?

In one of my projects I have 2 models that are related. Because of where they are used in the API there is a need for them to be able to embed each other.

The issue is that a client could request ?embed=a.b.a.b.a.b.a.b (continuing), causing the server to do tons of processing. This could lead to some type of denial of service attack.

Just wanted to get some opinions on these changes before I document them and learn how to write unit tests and update the unit tests/add my own.

This is not a complete pull request, if this is not the proper way for me to do this please let me know. I haven't made many pull requests to projects yet!

Hi There,

I have a group of array below that I would like to transform

I want the grouping key included,

  "success": true,
  "code": "200",
  "message": "OK",
data: {
    "08 December": {
        [
            id: 1,
            name: 'John',
            status: 'Active'
        ],
        [
            id: 2,
            name: 'John',
            status: 'Active'
        ],
    },
    "09 December": {
        [
            id: 3,
            name: 'John',
            status: 'Active'
        ]
    }
}

currently, I can only get this without the parent of the array:

{
    "success": true,
    "code": "200",
    "message": "OK",
    "data": [
        [
            {
                "id": 6,
                "status": "Complete",
                "name": "Vega Punk"
            },
            {
                "id": 7,
                "status": "Complete",
                "name": "Vega Punk"
            }
        ],
        [
            {
                "id": 8,
                "status": "Complete",
                "name": "Vega Punk"
            }
        ]
    ]
}

here is my code

and is it possible to custom the child? currently I just passing the whole array

I just don't know the keyword how to implement this, I hope you understand

Thank you.

When we try to include foo:modifier.bar,foo:modifier.baz, only foo and foo.bar get included, while foo.baz is ignored.

I believe this change is backward compatible, as I made sure $this->includeParams stays the same for foo:modifier(1).bar,foo:modifier(2).baz

Hi all.

I have transformer with relation for including

public function includeChild(Parent $parent): Item
{
    // How can I set `includes` for child transformer here?
    // without request param /parent?include=child.*

    return $this->item($parent->child, new ChildTransformer());
}

Thank you for your help.

Could you please make a bugfix update of the version 0.19.2

In order to fix this warning in PHP 8.1

Return type of League\Fractal\Scope::jsonSerialize() should either be compatible with JsonSerializable::jsonSerialize(): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /vendor/league/fractal/src/Scope.php on line 298  

We need to add the mentioned attribute:

https://github.com/thephpleague/fractal/blob/0.19.2/src/Scope.php#L298

/**
 * @return array
 */
#[\ReturnTypeWillChange]
public function jsonSerialize()
{
    return $this->toArray();
}

There are some breaking changes in 0.20, so I can't just swap the version to the new one.

Hi,

This is an appeal for package maintainers to use semantic versioning on this package.

The release of v0.20.0 introduces breaking changes on a patch version, this causes a lot of issues for people that relies on semver.