tobyzerner / json-api-php Goto Github PK

my bad. I fixed it.

Everything is ready to go for this and we just need to add it.

According to the JSON-API specification, a resource's identifier named id must be unique in the given resource domain. http://jsonapi.org/format/#document-resource-object-identification

In most of our applications, our classes which represent these resources have this property as a private to avoid the rest of the application to change this one and corrupt the database for example.

What about to change the following lines to use a getter instead of trying to directly access to the id property and have to extends this method in our custom serializer every time ?

# Tobscure\JsonApi\AbstractSerializer.php

/**
     * {@inheritdoc}
     */
    public function getId($model)
    {
        return $model->getId();
    }

I just face the problem, My Article Model's primaryKey is ID, not id, then json return the id attribute is null, the problem is : https://github.com/tobscure/json-api/blob/master/src/SerializerAbstract.php#L84, directly using the $data->id, but my resource is ID, not id, My fix:

class ArticleSerializer extends SerializerAbstract {

protected $type = 'articles';
protected $id = 'ID';//add it

protected function attributes($article)
{

    return [
        'title'  => $article->post_title,
        'body' => $article->post_content,
        'excerpt' => $article->post_excerpt,
        'createdAt' => $article->post_date,
        'author' => $article->post_author,
        'commentCount' => $article->comment_count,
    ];

}

}

in https://github.com/tobscure/json-api/blob/master/src/SerializerAbstract.php#L84, change to

  if($primaryKey = $this->id){
               return new Resource($this->type, $data->$primaryKey, $this->attributes($data), $links, $included);
       }else{
                return new Resource($this->type, $data->id, $this->attributes($data), $links, $included);
       }

Anyway, many databases' s tructure is not set id as the primaryKey, so i think need consider this problem..

We need to type hint and DocBlock everything.

I think it would make a lot more sense to use a getter - that way we can maintain encapsulation.

Something to automate pagination?

From the spec:

Note: A server may choose to expose a deeply nested relationship such as comments.author as a direct relationship with an alias such as comment-authors. This would allow a client to request /articles/1?include=comment-authors instead of /articles/1?include=comments.author. By abstracting the nested relationship with an alias, the server can still provide full linkage in compound documents without including potentially unwanted intermediate resources.

Even if user code converts an alias into a full path, it's impossible to include a deeply nested relationship without including all intermediate resources. So this functionality needs to be a part of the library.

Hi,

Let me illustrate a behavior, which I consider to be counter-intuitive when using the Collection::fields() method.

Given a $users variables, which is an array of User objects.

$collection = (new Collection($users, new UsersSerializer()))
    ->with(['picture'])
    ->fields([
        'users' => ['name'],
        'picture' => ['large'],
    ]);

$document = new Document($collection);

print json_encode($document->toArray(), JSON_PRETTY_PRINT);

it will return:

{
    "data": [
        {
            "type": "users",
            "id": "2e758e05-ec02-49c2-a27b-4948aefb9115",
            "attributes": {
                "name": "Pierre"
            }
        },
        {
            "type": "users",
            "id": "2e758e05-ec02-49c2-a27b-4948aefb9115",
            "attributes": {
                "name": "Paul"
            }
        }
    ]
}

In this case, the resulting JSON object is missing pictures relationships even if I explicitly specified the need of this relation in the Collection::with() method.

I discovered that if I provide a picture field for the users index, it will display the picture relationship in the resulting JSON object.

$collection = (new Collection($users, new UsersSerializer()))
    ->with(['picture'])
    ->fields([
        'users' => ['name', 'picture'],
        'picture' => ['large'],
    ]);

$document = new Document($collection);

print json_encode($document->toArray(), JSON_PRETTY_PRINT);

Is it a desired behavior ? I which case it is useful since the Collection::with() already express the need to attach any given relationships to a resource?

The piece of code responsible for this behavior can be found here: https://github.com/tobscure/json-api/blob/master/src/Resource.php#L212

Anyway, thanks a lot for this well crafted library ;)

Chaining a "new Collection" call is a bit awkward because it has to be surrounded in parentheses. I wonder if this syntax ...

$collection = (new Collection($posts, new PostSerializer))
    ->with(['author', 'comments']);

... could be improved with something like:

$collection = Collection::make($posts, new PostSerializer)
    ->with(['author', 'comments']);

make is pretty standard, another idea is Collection::of() (but Resource::of() doesn't work quite as well). Any other ideas/thoughts?

We need to add support for hyperlinks such as self, related, etc.

Currently (0.1.1) the package throws an error if the relation the client is trying to include a relation doesn't exist. What is expected behaviour? Should it throw an error?

return new Relation($resource); // throws and error if $resource is null

Maybe this should just return empty instead?

I could help out you with this. @tobscure is it something you would consider? Maybe we could also create a label for version 1.0?

In preparation for a 1.0 release.

Wouldn't it be nice if we could typehint what model we're throwing to the serializers?

public function getAttributes(User $user) {
    //
}

Would this be possible to implement and would it take long time to do?

I was wondering if there could be more page related methods in Parameters or at least making getPage() a public method. Here's something I'm looking for:

$page = $params->getPage('number');
$size = $params->getPage('size', $defaultSize);

would sound wrong to use different methods just for that, when everything else are methods on Parameters as well.

I was implementing the package at yet another project, until I noticed that the Parameters own getLimit returns a string. Yes, it does state in the docblock that it should return a string but I find this quite confusing. Mostly because within the LinksTrait addPaginationLinks the limit is used as an integer...

My main point is should the getLimit method within Parameters not return integer, and 0 by default instead of ''.

Would it make sense to offer methods getLinks and getMeta that would act in a similar way to getAttributes?

Hi all,

Shoud this library allow omitting the id property on a resource? This should be done when posting a new resource to the api.

This is what JSON-API spec v1.0 says about omitting the id property:

The id member is not required when the resource object originates at the client and represents a new resource to be created on the server.

Also see this pull request and @byCedric's response.

Reference http://jsonapi.org/format/#fetching-sparse-fieldsets

How do I include a relationship by default from a serializer class? Is it possible?

Hi Toby, thank you for the nice tool.

When I add a relationship, "id" and "type" is present. This works fine. I just didn't figure out how to add the resources as "included" data (see the example at http://jsonapi.org/, people, comments are included).

Is there a way to do that?

Hi there,

I'm taking a look at this part of the spec on relationships.

Resource linkage MUST be represented as one of the following:

• null for empty to-one relationships.
• an empty array ([]) for empty to-many relationships.
• a single resource identifier object for non-empty to-one relationships.
• an array of resource identifier objects for non-empty to-many relationships.

I'm not sure if my understanding is incorrect or not. My URL looks like this: GET /v1/devices?include=group

I have done this to get the "relationships" key to show up for all items:

    public function group($device)
    {
        return new Relationship(
            $device['group_id'] ? new Resource([
                'id' => $device['group_id'],
                'name' => $device['group_name'],
            ], new GroupSerializer) : null
        );
    }

Originally I tried to return null instead of a Relationship, but that removes the "relationships" block entirely. The only problem with the above solution is that it seems to only support "X-to-many" relationships. In other words, the response from the API looks like this:

"relationships": {
    "group": []
}

I believe that in reality, I want it to look like this:

"relationships": {
    "group": null
}

Is there any way to get this result? Thank you so much for this library! It's very flexible and useful.

Hi @tobscure
First of all, thanks for your efforts making this library. I was looking at the php libraries implementing jsonapi in order to pick one for one of my projects. There are a few of them worth trying, including yours. Unfortunately, it looks like that all of them suffer from the same issue.

Issue

They all have the similar idea of serializers - the logic which converts a business entity (model) into a json data object. And these serializers look pretty much similarly: they have a number of methods like getId($model), getAttributes($model) which take the entity as a parameter. These methods know about their $models internal structure and they use this knowledge to extract the id, attributes or whatever is needed to build the json. Consider the example from readme:

use Tobscure\JsonApi\AbstractSerializer;

class PostSerializer extends AbstractSerializer
{
    protected $type = 'posts';

    public function getAttributes($post, array $fields = null)
    {
        return [
            'title' => $post->title,
            'body'  => $post->body,
            'date'  => $post->date
        ];
    }
}

PostSerializer can only deal with $post models. The getAttributes() call will fail on everything else except a properly structured post object. But SerializerInterface does not restrict the model to anything particular. What SerializerInterface says is basically: you give me anything (@param mixed $model) and I tell you its attributes. Therefore, PostSerializer breaks the contract given by SerializerInterface. It means violation of Liskov Substitution Principle.

Solution (well, a kind of)

Instead of these pseudo-universal serializers, we should have something like ResourceInterface:

interface ResourceInterface
{
    public function getType(): string;
    public function getId(): string;
    public function getAttributes(array $fields = null): array;
    public function getLinks(): array;
    public function getMeta(): array;
    public function getRelationship($name):  ?\Tobscure\JsonApi\Relationship;
}

And a use-case would be like

class PostResource implements ResourceInterface
{
    protected $type = 'posts';
    public function __construct($post)
    {
       // validate $post
    }

    public function getAttributes(array $fields = null)
    {
        return [
            'title' => $this->post->title,
            'body'  => $this->post->body,
            'date'  => $this->post->date
        ];
    }
}
$document->setData(new PostResource($post));

Since your library version is still 0.*, it is not too late to make backward-incompatible changes to fix this issue. Please let me know what you think.

Eloquent adapter to make relationships easier when using Laravel.

Let me know if you need help setting up the configuration!

filter:
    paths:
        - 'app/*'
        - 'src/*'
    excluded_paths:
        - 'bootstrap/*'
        - 'config/*'
        - 'public/*'
        - 'resources/*'
        - 'vendor/*'
        - 'views/*'
tools:
    php_analyzer: true
    php_mess_detector: true
    php_changetracking: true
    php_code_sniffer:
        config:
            standard: PSR2
    php_loc:
        excluded_dirs:
            - vendor
    php_pdepend:
        excluded_dirs:
            - vendor
            - tests
    external_code_coverage:
        timeout: '3600'
        runs: 3

checks:
    php:
        code_rating: true
        duplication: true
        variable_existence: true
        useless_calls: true
        use_statement_alias_conflict: true
        unused_variables: true
        unused_properties: true
        unused_parameters: true
        unused_methods: true
        unreachable_code: true
        sql_injection_vulnerabilities: true
        security_vulnerabilities: true
        precedence_mistakes: true
        precedence_in_conditions: true
        parameter_non_unique: true
        no_property_on_interface: true
        no_non_implemented_abstract_methods: true
        deprecated_code_usage: true
        closure_use_not_conflicting: true
        closure_use_modifiable: true
        avoid_useless_overridden_methods: true
        avoid_conflicting_incrementers: true
        assignment_of_null_return: true
        verify_property_names: true
        verify_argument_usable_as_reference: true
        verify_access_scope_valid: true
        use_self_instead_of_fqcn: true
        too_many_arguments: true
        symfony_request_injection: true
        switch_fallthrough_commented: true
        spacing_of_function_arguments: true
        spacing_around_non_conditional_operators: true
        spacing_around_conditional_operators: true
        space_after_cast: true
        single_namespace_per_use: true
        simplify_boolean_return: true
        scope_indentation:
            spaces_per_level: '4'
        return_doc_comments: true
        require_scope_for_properties: true
        require_scope_for_methods: true
        require_php_tag_first: true
        require_braces_around_control_structures: true
        remove_trailing_whitespace: true
        remove_php_closing_tag: true
        remove_extra_empty_lines: true
        psr2_switch_declaration: true
        psr2_control_structure_declaration: true
        psr2_class_declaration: true
        property_assignments: true
        properties_in_camelcaps: true
        prefer_while_loop_over_for_loop: true
        phpunit_assertions: true
        php5_style_constructor: true
        parameters_in_camelcaps: true
        parameter_doc_comments: true
        return_doc_comment_if_not_inferrable: true
        param_doc_comment_if_not_inferrable: true
        overriding_private_members: true
        optional_parameters_at_the_end: true
        one_class_per_file: true
        non_commented_empty_catch_block: true
        no_unnecessary_if: true
        no_unnecessary_function_call_in_for_loop: true
        no_unnecessary_final_modifier: true
        no_underscore_prefix_in_properties: true
        no_underscore_prefix_in_methods: true
        no_trailing_whitespace: true
        no_space_inside_cast_operator: true
        no_space_before_semicolon: true
        no_space_around_object_operator: true
        no_goto: true
        no_global_keyword: true
        no_exit: true
        no_empty_statements: true
        no_else_if_statements: true
        no_duplicate_arguments: true
        no_debug_code: true
        no_commented_out_code: true
        newline_at_end_of_file: true
        naming_conventions:
            local_variable: '^[a-z][a-zA-Z0-9]*$'
            abstract_class_name: ^Abstract|Factory$
            utility_class_name: 'Utils?$'
            constant_name: '^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$'
            property_name: '^[a-z][a-zA-Z0-9]*$'
            method_name: '^(?:[a-z]|__)[a-zA-Z0-9]*$'
            parameter_name: '^[a-z][a-zA-Z0-9]*$'
            interface_name: '^[A-Z][a-zA-Z0-9]*Interface$'
            type_name: '^[A-Z][a-zA-Z0-9]*$'
            exception_name: '^[A-Z][a-zA-Z0-9]*Exception$'
            isser_method_name: '^(?:is|has|should|may|supports|was)'
        lowercase_php_keywords: true
        more_specific_types_in_doc_comments: true
        missing_arguments: true
        method_calls_on_non_object: true
        line_length:
            max_length: '120'
        lowercase_basic_constants: true
        instanceof_class_exists: true
        function_in_camel_caps: true
        function_body_start_on_new_line: true
        fix_use_statements:
            remove_unused: true
            preserve_multiple: false
            preserve_blanklines: false
            order_alphabetically: true
        foreach_traversable: true
        foreach_usable_as_reference: true
        fix_php_opening_tag: true
        fix_line_ending: true
        fix_identation_4spaces: true
        fix_doc_comments: true
        ensure_lower_case_builtin_functions: true
        encourage_postdec_operator: true
        classes_in_camel_caps: true
        catch_class_exists: true
        blank_line_after_namespace_declaration: true
        avoid_usage_of_logical_operators: true
        avoid_unnecessary_concatenation: true
        avoid_tab_indentation: true
        avoid_superglobals: true
        avoid_perl_style_comments: true
        avoid_multiple_statements_on_same_line: true
        avoid_fixme_comments: true
        avoid_length_functions_in_loops: true
        avoid_entity_manager_injection: true
        avoid_duplicate_types: true
        avoid_corrupting_byteorder_marks: true
        argument_type_checks: true
        avoid_aliased_php_functions: true
        deadlock_detection_in_loops: true

Hey,

first of all, thanks for this amazing library.

I have a problem with returning a correct response for a relationship self link.
Consider a resource object "Course". A "Course" can have a to many relationship the resource object "Participant".

So for example a GET to the URL "/courses/1" will return:

GET: http://example.com/courses/1

{
    "data": {
        "type": "course",
        "id": "1",
        "attributes": {
            "title": "My Course Title"
        },
        "relationships": {
            "participants": {
                "links": {
                     "self": "http://example.com/courses/1/relationships/participants",
                     "related": "http://example.com/curses/1/participants"
                },
                "data": [
                    { "type": "participant", "id": "5" },
                    { "type": "participant", "id": "12" }
                ]
            }
        }
    }
}

The response of the related link is easy to achieve. But the self link makes some problems. According to the link http://discuss.jsonapi.org/t/relation-link-usage/149/2 it should be returned the following:

GET: http://example.com/courses/1/relationships/participants

{ 
    "data": [{
        "type": "participant",
        "id": "5" 
      }, {
        "type": "participant",
        "id": "12" 
      }]
}

I can only achieve this response:

GET: http://example.com/courses/1/relationships/participants

{ 
    "data": [{
        "type": "participant",
        "id": "5",
        "attributes": []
      }, {
        "type": "participant",
        "id": "12" ,
        "attributes": []
      }]
}

To do so, I have written a new Serializer which returns null when getAttributes() is called. But this doesn't exclude the "attributes" array. I haven't found a way to do so. Maybe there is one, so please give me a hint.

Even if there is a way, it would be the best not to write a new Serializer at all.
Maybe the following is a good idea:

$collection = new Collection($participants, 'participant');
$document = new Document($collection);
return response($document, 200)

$participants contains the two participants with id 5 and 12. The second parameter of new Collection contains the string which will be used as type in the resulting json (same function as the $type variable in AbstractSerializer).

I was following the example in the README regarding Relationships.

I'm implementing a very similar situation to 'comments', but with 'tags'. As you know, a post can have no tags at all, so there is a point where I pass an empty array to the collection method:

protected function tags()
    {
        return function ($post, $include, array $included, array $linked) {
            $serializer = new TagSerializer($included, $linked);

            $serializerTags = array();
            if ($include) $serializerTags = $post->tags;
            else foreach ($post->tags as $t) $serializerTags[] = $t->id;

            $tags = $serializer->collection($serializerTags); 
            $relationship = new Tobscure\JsonApi\Relationship($tags);

            return $relationship;
        };
    }

When $serializerTags is empty, collection() returns NULL!

When passing a null parameter to the Relationship constructor, it throws:
Catchable fatal error</b>: Argument 1 passed to Tobscure\JsonApi\Relationship::__construct() must implement interface Tobscure\JsonApi\Elements\ElementInterface, null given

So, what's the right way to handle relationships and empty cases?

This package would do well to have extensive test coverage.

I can see a lot of tabs.

This is the guide to add StyleCI support:

1. Sign up at https://styleci.io/

2. Go to the repositories page https://styleci.io/account#repos

3. Enable this repository.

4. Press Show Analysis and then Settings.

5. Add the following settings:

   enabled:
     - unalign_double_arrow
   
   disabled:
     - psr0
     - align_double_arrow
     - phpdoc_align

6. Press Save Configuration.

7. Press Analyze Now.

This has to be done by the owner of the repository.

support for underscore_case relationship name

This packages doesn't yet fully support the latest changes to the JSON API standards.

Hi,
First of all, thank you for the great job! 👍

I encountered the following error when using Relationships

 PHP Fatal error:  Call to undefined function Tobscure\\JsonApi\\array_get() in /opt/ami/Ami/web/rest/vendor/tobscure/json-api/src/SerializerAbstract.php on line 108

So I tried to prefix the calls to array_get with \ but the error persists. After googling a bit, I found that such a function isn't natively supported in PHP (I use >5.4), it's a Laravel helper function.
Maybe Laravel should be declared as a dependency?

If this sounds too overkill to you, I tried adding the following at the end of SerializerAbstract (right after the class)

function array_get(array $array, $id, $fallback = '')
{
    return isset($array[$id]) ? $array[$id] : $fallback;
}

Which works.

Now, put in this way, right into the SerializerAbstract.php file, it's quite dirty. So, if you are ok with this solution (rather than Laravel as a dependency) I can put it into a Utils.php file and submit a pull request.

From what I can see, the inclusion of relationships in this library will always result in the addition of:

• a data object within the relationships object
• the included object being populated

I am trying to implement a billboard response like this:

{
    "data": {
        "type": "home",
        "id": "1",
        "links": {
            "self": "http://api.example.com"
        },
        "relationships": {
            "products": {
                "links": {
                    "related": "http://api.example.com/products"
                }
            }
        }
    }
}

Notice the above does not contain relationships:products:data, which is intentional. It also does not contain the included section at the bottom.

From what I can gather, your implementation of relationships assumes there will always be some data, is that correct? I am hoping I have missed something and there is an easy way to achieve the above.

Looking over the specification your meant to be able to add relationships with links, as shown below in relationships, is there a way to do this with this library that I'm missing? Thanks.

"data": [{
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON API paints my bikeshed!"
},
"relationships": {
"author": {
"links": {
"self": "http://example.com/articles/1/relationships/author",
"related": "http://example.com/articles/1/author"
},
"data": { "type": "people", "id": "9" }
},
"comments": {
"links": {
"self": "http://example.com/articles/1/relationships/comments",
"related": "http://example.com/articles/1/comments"
},
"data": [
{ "type": "comments", "id": "5" },
{ "type": "comments", "id": "12" }
]
}
},
"links": {
"self": "http://example.com/articles/1"
}
}],

Thank you again for this library!

I am reading through the JSON-API spec, and am looking at this section here which states that "A "relationship object" MUST contain at least one of the following," where the list is data, links, and meta.

I'm wondering if there is any way to create a "spare" relationship. i.e. I know the ID of the relationship, but the data is not currently available to me -- currently, if I just try to throw this at Resource, it will call getAttributes, and error out. I'm wondering if there is a way to only include links to the related object.

What adding a PHP CS fixer configuration file? Sounds interesting?

Hi guys, I just started to experiment some with your awesome package. So I took it for a spin in Laravel, trying to get the fields that should be included for a specific resource. It went really well when defining the fields[type]=field1,field2 as parameter. But when I got everything working, I tried to remove the fields parameter from the request and it resulted in a fatal error.

The error is raised because the input array, that is passed to the Parameters's constructor, doesn't have a fields key. Within the Parameters getFields method, the absence of this key isn't caught by using a default empty array. This results in an array_map call, with null instead of an (empty) array.

So my question should this be fixed? I will create a pull request for this issue anyways. I personally think it would be better to not-crash when the fields parameter is not provided.

There is some stuff in master that is useful. Can you consider cutting a new release as so consumers don't have to pin to a commit?

Hi, I'm getting this error, maybe someone face this before.

This is my UserSerializer:

class UserSerializer extends AbstractSerializer
{
    protected $type = 'user';

    public function getAttributes($item, array $fields = null)
    {
        return [
            'id' => $item->id,
            'name' => $item->name,
            'email' => $item->email
        ];
    }
}

And this is the example I'm trying to get to work:

$user = new \stdClass();
$user->id = 24;
$user->name = 'Hello World';
$collection = new Collection([$user], new UserSerializer);

$document = new Document($collection);

echo json_encode($document);

Am I doing something wrong?

suppose we have a request url http://xxx/jsonapi/speakers/1654?include=sessions

the result will be one primary resource of speakers, and it will include sessions, which will come from (in this test scenario) from SpeakerSerializer->sessions()

but that sessions() method gets called twice (and it should be called only once, since there is only 1 primary element). if the request would call for a list of speakers, like so: http://xxx/jsonapi/speakers/?include=sessions, then the SpeakerSerializer->sessions() will get called twice the time of the count of the speakers items

i debugged the code, and found that the SpeakerSerializer->sessions() gets called:

1. here
   AbstractSerializer.php
   line 75, inside of public function getRelationship($model, $name)

$relationship = $this->$method($model);

this AbstractSerializer.php:getRelationship() gets called from Resource.php:toArray()

2. and again the same line (meaning AbstractSerializer.php:getRelationship()) will be called from Document.php::toArray() from within the line saying:

$resources = $this->getIncluded($this->data);

so to sum it up:
Documen.php:toArray() calls the same code twice per each resource, and does so on the line saying
$document['data'] = $this->data->toArray();
and just next to it
$resources = $this->getIncluded($this->data);

Hi.

Great little library! Are there any plans to support json api error responses?

Thanks.

Dan

Hi there!

When dealing with many-to-many relations, sometimes there's the need to include data which doesn't belong to any of the types, but does belong to the relation they form (the pivot table).

Currently, there's no way to add that kind of data, since the only thing that goes into relationships is the id and the type of any related type, as we can see here.

I asked how we could handle that case in the JSON API discuss, in which I was pointed to this other question, from where I got my answer.

What's the possibility to add that feature to the library?

Cheers,
Quetzy

I've updated this great lib after some months and sadly I've discovered that the compatibility with PHP 5.3 has been dropped.
Is there a chance to get it back?

What do you think about if your library could be able to validate a given json depending on the JSON-API specification part about creating and updating resources?

I'm using your library to serialize my resources for the output. It could be interesting to use it to validate the incoming data too.

Since sparse fieldsets and includes are a global concept, ie, they are specified once in the URL and have an effect on all resources in the document:

GET /articles/1?fields[comments]=body,author&include=comments.author

Does it make sense to be specifying them on Resources/Collections, rather than on the Document itself? eg,

$collection = new Collection($posts, new PostSerializer);

$document = new Document($collection);
$document->setInclude(['comments.author']);
$document->setFields(['comments' => ['body', 'author']]);

Cause all package needs to be tested before using them in production.

Can we have the Document class implement the JsonSerializable interface?
I'd love to have that for easier JSON response creation in Flarum.

That would also require changing the version requirement to PHP 5.4.

From the spec:

If a server is unable to identify a relationship path or does not support inclusion of resources from a path, it MUST respond with 400 Bad Request.