mezzio / mezzio-hal

Hypertext Application Language implementation for PHP and PSR-7

Hypertext Application Language (HAL) for PSR-7 Applications

🇷🇺 Русским гражданам

Мы, участники Laminas, родились и живем в разных странах. У многих из нас есть друзья, родственники и коллеги как в России, так и в Украине. Некоторые из нас родились в России. Некоторые из нас живут в России. У некоторых бабушки и дедушки сражались с фашистами во Второй мировой войне. Здесь никто не поддерживает фашизм.

У одного из нас есть украинская родственница, которая спаслась из дома вместе с сыном. Поезд задержался из-за бомбежки на дороге впереди. У нас есть друзья, которые прячутся в бомбоубежищах. Мы с тревогой ждем весточки от них после воздушных налетов, которые беспорядочно наносят удары и попадают по больницам, школам, детским садам и домам. Мы не берем это из каких-либо СМИ. Мы наблюдаем это напрямую.

Вы доверяете нам достаточно, чтоб использовать наши программы, и мы просим вас довериться нам вновь. Мы нуждаемся в помощи. Выходите и протестуйте против этой бесполезной войны. Остановите кровопролитие. Скажите "Нет войне!"

🇺🇸 To Citizens of Russia

We at Laminas come from all over the world. Many of us have friends, family and colleagues in both Russia and Ukraine. Some of us were born in Russia. Some of us currently live in Russia. Some have grandparents who fought Nazis in World War II. Nobody here supports fascism.

One team member has a Ukrainian relative who fled her home with her son. The train was delayed due to bombing on the road ahead. We have friends who are hiding in bomb shelters. We anxiously follow up on them after the air raids, which indiscriminately fire at hospitals, schools, kindergartens and houses. We're not taking this from any media. These are our actual experiences.

You trust us enough to use our software. We ask that you trust us to say the truth on this. We need your help. Go out and protest this unnecessary war. Stop the bloodshed. Say "stop the war!"

This library provides utilities for modeling HAL resources with links and generating PSR-7 responses representing both JSON and XML serializations of them. (The library consumes PSR-17 ResponseFactoryInterface implementations in order to provide HAL response instances.)

Installation

Run the following to install this library:

$ composer require mezzio/mezzio-hal

Documentation

Documentation is in the doc tree, and can be compiled using mkdocs:

$ mkdocs build

You may also browse the documentation online.

mezzio-hal's Issues

Version documentation for v2.0

Feature Request

Q	A
New Feature	no
RFC	no
BC Break	yes

Summary

When prepping for the v2 release, we need to version the documentation, and provide redirects from old URLs to the new ones.

Broken self links when using RouteBasedResourceStrategy with resource identifiers that are objects

BC Break Report

Q	A
Version	1.4.0

Summary

When using RouteBasedResourceStrategy, the generated self link for individual HAL resources is broken when the resource identifier references a property that contains an object, regardless of whether the object can be represented as a scalar value. In my specific case, I am using the ramsey/uuid-doctrine library which represents the ID as an object once the entity is hydrated with data from the database.

Previous behavior

Due to this library not previously checking explicitly for scalar values in RouteBasedResourceStrategy::createResource, and the UUID objects employing __toString (and other serialisation methods), the UUID object was accepted and the self links were generated as expected.

Current behavior

The property value of a mapped resource containing such an object is not passed through as a route parameter in RouteBasedResourceStrategy::createResource like it was before, resulting in the self link being broken. After updating from 1.3.1 to 1.4.0, all the self links are showing paths such as /some-resource/%7Bid%7D, instead of the value of the field (e.g. /some-resource/1b7e838c-5758-11eb-b1fe-0242281aebdd).

How to reproduce

It seems like this was a change specifically made as a result of a test in this library (commit a05bd84). Attempting to use a non-scalar value in this scenario, as described above, should suffice.

Switch to GHA CI workflow

Switch from Travis-CI to GHA CI workflow, as documented at https://gist.github.com/weierophinney/b003e50c3c2667d08076caf31ebd36a4

PHP 8.0 support

Feature Request

Q	A
New Feature	yes

Summary

To be prepared for the december release of PHP 8.0, this repository has some additional TODOs to be tested against the new major version.

In order to make this repository compatible, one has to follow these steps:

• Modify composer.json to provide support for PHP 8.0 by adding the constraint ~8.0.0
• Modify composer.json to drop support for PHP less than 7.3
• Modify composer.json to implement phpunit 9.3 which supports PHP 7.3+
• Modify .travis.yml to ignore platform requirements when installing composer dependencies (simply add --ignore-platform-reqs to COMPOSER_ARGS env variable)
• Modify .travis.yml to add PHP 8.0 to the matrix (NOTE: Do not allow failures as PHP 8.0 has a feature freeze since 2020-08-04!)
• Modify source code in case there are incompatibilities with PHP 8.0

Syntax Highlight on Documentation is "broken"

Bug Report

Q	A
Version(s)	2.3.0

Summary

The syntax highlight in this documentation have an issue. The background is black and the text is also black - so we can't read something. It only works correctly on the index page, but not on each other sites.
Maybe an issue occured whilst building the documentation page. The Markdown files seems to be OK.

Current behavior

PHP Code is not readable on documentation.

How to reproduce

Simple check the documentation pages - like https://docs.mezzio.dev/mezzio-hal/v2/hal/

Expected behavior

Code is readable again

Exposed embedded key existence in HalResource, added a test to check …

Provide a narrative description of what you are trying to accomplish:

• Are you fixing a bug?
  • Detail how the bug is invoked currently.
  • Detail the original, incorrect behavior.
  • Detail the new, expected behavior.
  • Base your feature on the master branch, and submit against that branch.
  • Add a regression test that demonstrates the bug, and proves the fix.
  • Add a CHANGELOG.md entry for the fix.

See zendframework/zend-expressive-hal#52 for details

---

Originally posted by @jguittard at zendframework/zend-expressive-hal#53

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Repository problems

These problems occurred while renovating this repository. View logs.

• WARN: Use matchDepNames instead of matchPackageNames

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• Update dependency psalm/plugin-phpunit to ^0.19.0
• Update dependency doctrine/orm to v3
• Update dependency phpunit/phpunit to v11
• Lock file maintenance
• Click on this checkbox to rebase all open PRs at once

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.

• Update dependency psr/link to v2

Detected dependencies

composer

composer.json

• php ~8.1.0 || ~8.2.0 || ~8.3.0
• psr/container ^1.1.2 || ^2.0.2
• psr/http-factory ^1.0
• psr/http-message ^1.0.1 || ^2.0.0
• psr/link ^1.0
• webmozart/assert ^1.10
• willdurand/negotiation ^3.0
• doctrine/orm ^2.14.1
• laminas/laminas-coding-standard ~2.5.0
• laminas/laminas-hydrator ^4.12
• laminas/laminas-paginator ^2.17
• mezzio/mezzio-helpers ^5.12
• phpspec/prophecy-phpunit ^2.0.1
• phpunit/phpunit ^9.5.28
• psalm/plugin-phpunit ^0.18.4
• vimeo/psalm ^5.18

github-actions

.github/workflows/continuous-integration.yml

.github/workflows/docs-build.yml

.github/workflows/release-on-milestone-closed.yml

---

• Check this box to trigger a request for Renovate to run again on this repository

Remove deprecated functionality for 2.0.0

Feature Request

Q	A
New Feature	yes
RFC	no
BC Break	yes

Summary

The following features were marked deprecated during the 1.x series:

• The RouteBasedResourceMetadata::$routeIdentifierPlaceholder property and constructor argument.
• The RouteBasedResourceMetadataFactory configuration setting route_identifier_placeholder.

`HalResource` does not allow `_embed` data that is based on a `oneOf:` JSONSchema definition

Bug Report

Q	A
Version(s)	2.3.1

Summary

This is a union of Foo and Tab in a JSONSchema resource:

{
  "components": {
    "SomeResource": {
      "oneOf": [
        {"$ref": "#/components/Foo"},
        {"$ref": "#/components/Tab"}
      ]
    },
    "Foo": {
      "type": "object",
      "required": ["bar"],
      "properties": {
        "bar": {"type": "string"}
      }
    },
    "Tab": {
      "type": "object",
      "required": ["taz"],
      "properties": {
        "taz": {"type": "string"}
      }
    }
  }
}

In practice, when rendering a list<SomeResource>, you will get an array of JSON objects with different properties:

[
  {"bar": "haha"},
  {"taz": "hehe"},
  {"bar": "hihi"}
]

Current behavior

HalResource#__construct() does some pretty aggressive validation of its JSON contents, specifically on $embedded data:

mezzio-hal/src/HalResource.php

Lines 512 to 529 in 29f006b

	/**
	* @throws InvalidArgumentException If $a and $b are not structurally equivalent.
	*/
	private function compareResources(self $a, self $b, string $name, string $context): bool
	{
	$structureA = array_keys($a->getElements());
	$structureB = array_keys($b->getElements());
	sort($structureA);
	sort($structureB);
	if ($structureA !== $structureB) {
	throw new InvalidArgumentException(sprintf(
	'%s detected structurally inequivalent resources for element %s',
	$context,
	$name
	));
	}
	return true;
	}

This precludes usage of well-documented resources of different types.

How to reproduce

• configure a resource for class Foo { public string $bar = 'baz'; }
• configure a resource for class Tab { public string $taz = 'tar'; }
• render a (pseudo-code) new HalResource(..., ..., [new Foo(), new Tab()]) - it will crash due to Foo and Tab not sharing same properties

Expected behavior

A HalResource can be instantiated with $embedded data of different types:

mezzio-hal/src/HalResource.php

Lines 52 to 54 in 29f006b

	* @param HalResource[][] $embedded
	*/
	public function __construct(array $data = [], array $links = [], array $embedded = [])

Suggested solution

Let's just drop the exception: it was seemingly designed to support developers that have difficulty with keeping their data consistent, but it hinders proper union type design.

Allow an arbitrary number of entity properties to route placeholders mappings in metadatamaps

Feature Request

Q	A
New Feature	yes
RFC	yes
BC Break	no

Summary

Let's say I have an applicant table, a skill table and a N:M relationship table to list applicant's skills.

Let's say I have a REST API with these routes:

Read applicants collection: /api/rest/v1/applicants^GET
Read applicant entity: /api/rest/v1/applicants/{id}^GET

Read skills collection: /api/rest/v1/skills^GET
Read skill entity: /api/rest/v1/skills/{id}^GET

Read an applicant's skills collection: /api/rest/v1/applicants/{applicant_id}/skills^GET
Read an applicant's skill entity: /api/rest/v1/applicants/{id0}/skills/{id1}^GET

For this last case, in my metadatamap, I can't use resource_identifier, route_identifier_placeholder options twice to map my entity properties to the route palceholder.

I propose o add the possibility of mapping an arbitrary number of entity properties to palceholders.

Settings would look like this in MetadataMap:

        [
            'identifiers_to_placeholders_mapping' => [
                'applicant_id' => 'id0',
                'skill_id' => 'id1',
            ],
            '__class__' => RouteBasedResourceMetadata::class,
            'extractor' => ObjectPropertyHydrator::class,
            'resource_class' => ApplicantSkillEntity::class,
            'route' => '/api/rest/v1/applicants/{id0}/skills/{id1}^GET',
        ],

Unable to generate HAL from proxy

Having an issue generating HAL response when a collection/entity contains proxies instead of their equivalent entities. I've found a discussion related to this here, but the provided solutions don't seem to fix the issue.
Is there a workaround for this?
We've made a fork in which at MetadataMap->__construct() we're pushing the entities to MetadataMap->$map to make sure that MetadataMap->has($class) looks for and finds the entities and not their proxies, but this does not seem to be the correct approach to the issue.

Extend `RouteBasedCollectionStrategy`

I am trying to modify the default fields which appear in a collection response. In particular I'm filtering and paginating my collection and, beside _total_items I would like to have also other fields like _total_items_without_filters and _total_items_with filters_but_without_pagination.

The fact is that inside RouteBasedCollectionStrategy, the creation of the resource happens in the private method extractIterator which is called by the private method extractCollection, which requires also the presence of the method extractPaginator.

All of this said, to add a new field to the resource I must extends the RouteBasedCollectionStrategy class, copy and paste all the above mentioned methods, just to edit the line $data = ['_total_items' => $count];

It would be nice if just the creation of the $data could be exposed, at least in a protected method, so that modifying it could become easier

---

Originally posted by @marcosh at zendframework/zend-expressive-hal#47

Update to laminas-coding-standard 2.0.0+

Feature Request

Q	A
New Feature	yes
RFC	no
BC Break	no

Summary

When prepping for v2, we should update the CS ruleset to v2.

Fast route with two placeholders

Already opened a similar discussion on https://discourse.laminas.dev/t/fast-route-with-two-placeholders/1403

Solution would be:

RouteBasedResourceStrategy.php

if (isset($data[$resourceIdentifier])) {
    $routeParams[$routeIdentifier] = $data[$resourceIdentifier];
}

// Auto inject all entity keys in route params
foreach($data as $key => $value) {
    $routeParams[$key] = $value;
}

Mapped NULL values are serialized outside of the _embedded key

• I was not able to find an open or closed issue matching what I'm seeing.
• This is not a question. (Questions should be asked on slack (Signup for Slack here) or our forums.)

Provide a narrative description of what you are trying to accomplish.

Code to reproduce the issue

User.php

namespace App;

class User
{
   /**
    * @var string
    */
   protected $id;

   /**
    * @var string
    */
   protected $name;

   /**
    * @var string
    */
   protected $email;

   /**
    * @var Avatar
    */
   protected $avatar;

   public function getName(): ?string
   {
       return $this->name;
   }

   public function setName(?string $name): User
   {
       $this->name = $name;
       return $this;
   }

   public function getEmail(): ?string
   {
       return $this->email;
   }

   public function setEmail(?string $email): User
   {
       $this->email = $email;
       return $this;
   }

   public function getAvatar(): ?Avatar
   {
       return $this->avatar;
   }

   public function setAvatar(?Avatar $avatar): User
   {
       $this->avatar = $avatar;
       return $this;
   }
}

Avatar.php

namespace App;

class Avatar
{
   /**
    * @var string|null
    */
   protected $id;

   /**
    * @var string|null
    */
   protected $url;

   public function getId(): ?string
   {
       return $this->id;
   }

   public function setId(?string $id): User
   {
       $this->id = $id;
       return $this;
   }

   public function getUrl(): ?string
   {
       return $this->url;
   }

   public function setUrl(?string $url): User
   {
       $this->url = $url;
       return $this;
   }
}

config.php

MetadataMap::class => [
    [
        '__class__' => RouteBasedResourceMetadata::class,
        'resource_class' => App\User::class,
        'route' => 'api.user',
        'extractor' => ClassMethodsHydrator::class,
    ],
    [
        '__class__' => RouteBasedResourceMetadata::class,
        'resource_class' => App\Avatar::class,
        'route' => 'api.avatar',
        'extractor' => ClassMethodsHydrator::class,
    ],
],

$renderer = new JsonRenderer();
$avatar = new Avatar();
$avatar->setId('1234');
$avatar->setUrl('https://superfastcdn.com/myavatar.png');
$user = new User();
$user->setId('5678');
$user->setName('John Doe');
$user->setEmail('[email protected]');
$user->setAvatar($avatar);

Expected results

$resource = $resourceGenerator->fromObject($user, $request);
echo $renderer->render($resource);

$user->setAvatar(null);

$resource = $resourceGenerator->fromObject($user, $request);
echo $renderer->render($resource);

{
    "name": "John Doe",
    "email": "[email protected]",
    "_embedded": {
        "avatar": {
            "id": "1234",
            "url": "https://superfastcdn.com/myavatar.png",
            "_links": {
                "self": {
                    "href": "https://api.acme.com/avatars/1234"
                }
            }
        }
    },
    "_links": {
        "self": {
            "href": "https://api.acme.com/users/5678"
        }
    }
}

{
    "name": "John Doe",
    "email": "[email protected]",
    "_embedded": {
        "avatar": null
    },
    "_links": {
        "self": {
            "href": "https://api.acme.com/users/5678"
        }
    }
}

Actual results

{
    "name": "John Doe",
    "email": "[email protected]",
    "_embedded": {
        "avatar": {
            "id": "1234",
            "url": "https://superfastcdn.com/myavatar.png",
            "_links": {
                "self": {
                    "href": "https://api.acme.com/avatars/1234"
                }
            }
        }
    },
    "_links": {
        "self": {
            "href": "https://api.acme.com/users/5678"
        }
    }
}

{
    "name": "John Doe",
    "email": "[email protected]",
    "avatar": null,
    "_links": {
        "self": {
            "href": "https://api.acme.com/users/5678"
        }
    }
}

---

Originally posted by @jguittard at zendframework/zend-expressive-hal#52

Psalm integration

Feature Request

Q	A
QA	yes

Summary

As decided during the Technical-Steering-Committee Meeting on August 3rd, 2020, Laminas wants to implement vimeo/psalm in all packages.

Implementing psalm is quite easy.

Required

• Create a psalm.xml in the project root
• Copy and paste the contents from this psalm.xml.dist
• Run $ composer require --dev vimeo/psalm
• Run $ vendor/bin/psalm --set-baseline=psalm-baseline.xml
• Add a composer script static-analysis with the command psalm --shepherd --stats
• Add a new line to script: in .travis.yml: - if [[ $TEST_COVERAGE == 'true' ]]; then composer static-analysis ; fi
• Remove phpstan from the project (phpstan.neon.dist, .travis.yml entry, composer.json require-dev and scripts)

Optional

• Fix as many psalm errors as possible.

The Parent-Child (self) relationship is visible only on first page in pagination.

Bug Report

The Parent-Child (self) relationship isn't working properly

Q	A
Mezzio-Hal	^2.0

Summary

The Parent-Child (self) relationship isn't working properly in pagination.

Current behavior

While listing the parent-child data of an Entity, parent data is visible only on first page. In rest of the pages only original data is visible along with following portion.

"parent": {
          "__initializer__": {},
          "__cloner__": {},
          "__isInitialized__": false
        },

How to reproduce

http://localhost:8080/banks or http://localhost:8080/banks?page=1 lists following data.

GET http://localhost:8080/banks?page=1

HTTP/1.1 200 OK
Date: Sat, 06 Mar 2021 06:41:18 GMT
Server: Apache/2.4.38 (Debian)
X-Powered-By: PHP/7.3.27
Content-Length: 4446
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/hal+json

{
  "_total_items": 5,
  "_page": 1,
  "_page_count": 3,
  "_links": {
    "self": {
      "href": "http://localhost:8080/banks/?page=1"
    },
    "next": {
      "href": "http://localhost:8080/banks/?page=2"
    },
    "last": {
      "href": "http://localhost:8080/banks/?page=3"
    }
  },
  "_embedded": {
    "bank": [
      {
        "id": 1,
        "parent_id": 0,
        "children": {},
        "parent": {
          "__initializer__": {},
          "__cloner__": {},
          "__isInitialized__": false
        },
        "name": "Bank #1",
        "phone": "555-555-5555",
        "fax": "666-666-6666",
        "address1": "55 Any Street",
        "address2": "Suite 100",
        "city": "Wellington",
        "zone_id": 18,
        "zip": "33496",
        "product_1_price": "0.00",
        "product_2_price": "0.00",
        "allow_email_attachment": 1,
        "is_active": 1,
        "created": {
          "date": "2011-06-04 00:26:43.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "modified": {
          "date": "2011-12-29 14:19:29.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "_links": {
          "self": {
            "href": "http://localhost:8080/banks/1"
          }
        }
      },
      {
        "id": 2,
        "parent_id": 1,
        "children": {},
        "name": "Bank #2",
        "phone": "555-555-5555",
        "fax": "666-666-6666",
        "address1": "55 Any Street",
        "address2": "Suite 100",
        "city": "Boca Raton",
        "zone_id": 18,
        "zip": "33496",
        "product_1_price": "0.00",
        "product_2_price": "0.00",
        "allow_email_attachment": 0,
        "is_active": 1,
        "created": {
          "date": "2011-06-05 14:33:30.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "modified": {
          "date": "2012-04-03 16:25:40.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "_links": {
          "self": {
            "href": "http://localhost:8080/banks/2"
          }
        },
        "_embedded": {
          "parent": {
            "id": 1,
            "parent_id": 0,
            "children": {},
            "parent": {
              "__initializer__": {},
              "__cloner__": {},
              "__isInitialized__": false
            },
            "name": "Bank #1",
            "phone": "555-555-5555",
            "fax": "666-666-6666",
            "address1": "55 Any Street",
            "address2": "Suite 100",
            "city": "Wellington",
            "zone_id": 18,
            "zip": "33496",
            "product_1_price": "0.00",
            "product_2_price": "0.00",
            "allow_email_attachment": 1,
            "is_active": 1,
            "created": {
              "date": "2011-06-04 00:26:43.000000",
              "timezone_type": 3,
              "timezone": "UTC"
            },
            "modified": {
              "date": "2011-12-29 14:19:29.000000",
              "timezone_type": 3,
              "timezone": "UTC"
            },
            "_links": {
              "self": {
                "href": "http://localhost:8080/banks/1"
              }
            }
          }
        }
      }
    ]
  }
}

Response code: 200 (OK); Time: 6720ms; Content length: 4446 bytes

And http://localhost:8080/banks?page=2 shows following data.

GET http://localhost:8080/banks?page=2

HTTP/1.1 200 OK
Date: Sat, 06 Mar 2021 06:42:26 GMT
Server: Apache/2.4.38 (Debian)
X-Powered-By: PHP/7.3.27
Content-Length: 3169
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/hal+json

{
  "_total_items": 5,
  "_page": 2,
  "_page_count": 3,
  "_links": {
    "self": {
      "href": "http://localhost:8080/banks/?page=2"
    },
    "first": {
      "href": "http://localhost:8080/banks/?page=1"
    },
    "prev": {
      "href": "http://localhost:8080/banks/?page=1"
    },
    "next": {
      "href": "http://localhost:8080/banks/?page=3"
    },
    "last": {
      "href": "http://localhost:8080/banks/?page=3"
    }
  },
  "_embedded": {
    "bank": [
      {
        "id": 4,
        "parent_id": 1,
        "children": {},
        "parent": {
          "__initializer__": {},
          "__cloner__": {},
          "__isInitialized__": false
        },
        "name": "New Child Bank",
        "phone": "555-555-5555",
        "fax": "666-666-6666",
        "address1": "55 Any Street",
        "address2": "Suite 100",
        "city": "Wellington",
        "zone_id": 18,
        "zip": "33496",
        "product_1_price": "8.50",
        "product_2_price": "7.80",
        "allow_email_attachment": 1,
        "is_active": 1,
        "created": {
          "date": "2021-03-04 09:29:05.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "modified": {
          "date": "2021-03-04 09:29:05.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "_links": {
          "self": {
            "href": "http://localhost:8080/banks/4"
          }
        }
      },
      {
        "id": 5,
        "parent_id": 1,
        "children": {},
        "parent": {
          "__initializer__": {},
          "__cloner__": {},
          "__isInitialized__": false
        },
        "name": "New Child Bank #2",
        "phone": "555-555-5555",
        "fax": "666-666-6666",
        "address1": "55 Any Street",
        "address2": "Suite 100",
        "city": "Wellington",
        "zone_id": 18,
        "zip": "33496",
        "product_1_price": "8.50",
        "product_2_price": "7.80",
        "allow_email_attachment": 1,
        "is_active": 1,
        "created": {
          "date": "2021-03-04 11:23:58.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "modified": {
          "date": "2021-03-04 11:23:58.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "_links": {
          "self": {
            "href": "http://localhost:8080/banks/5"
          }
        }
      }
    ]
  }
}

Response code: 200 (OK); Time: 6778ms; Content length: 3169 bytes

See the difference of portion starting from

          "parent": {
            "id": 1,
            "parent_id": 0,
            "children": {},
            "parent": {
              "__initializer__": {},
              "__cloner__": {},
              "__isInitialized__": false
            },
...
...

Expected behavior

http://localhost:8080/banks?page=1

GET http://localhost:8080/banks?page=1

HTTP/1.1 200 OK
Date: Sat, 06 Mar 2021 06:41:18 GMT
Server: Apache/2.4.38 (Debian)
X-Powered-By: PHP/7.3.27
Content-Length: 4446
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/hal+json

{
  "_total_items": 5,
  "_page": 1,
  "_page_count": 3,
  "_links": {
    "self": {
      "href": "http://localhost:8080/banks/?page=1"
    },
    "next": {
      "href": "http://localhost:8080/banks/?page=2"
    },
    "last": {
      "href": "http://localhost:8080/banks/?page=3"
    }
  },
  "_embedded": {
    "bank": [
      {
        "id": 1,
        "parent_id": 0,
        "children": {},
        "parent": {
          "__initializer__": {},
          "__cloner__": {},
          "__isInitialized__": false
        },
        "name": "Bank #1",
        "phone": "555-555-5555",
        "fax": "666-666-6666",
        "address1": "55 Any Street",
        "address2": "Suite 100",
        "city": "Wellington",
        "zone_id": 18,
        "zip": "33496",
        "product_1_price": "0.00",
        "product_2_price": "0.00",
        "allow_email_attachment": 1,
        "is_active": 1,
        "created": {
          "date": "2011-06-04 00:26:43.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "modified": {
          "date": "2011-12-29 14:19:29.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "_links": {
          "self": {
            "href": "http://localhost:8080/banks/1"
          }
        }
      },
      {
        "id": 2,
        "parent_id": 1,
        "children": {},
        "name": "Bank #2",
        "phone": "555-555-5555",
        "fax": "666-666-6666",
        "address1": "55 Any Street",
        "address2": "Suite 100",
        "city": "Boca Raton",
        "zone_id": 18,
        "zip": "33496",
        "product_1_price": "0.00",
        "product_2_price": "0.00",
        "allow_email_attachment": 0,
        "is_active": 1,
        "created": {
          "date": "2011-06-05 14:33:30.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "modified": {
          "date": "2012-04-03 16:25:40.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "_links": {
          "self": {
            "href": "http://localhost:8080/banks/2"
          }
        },
        "_embedded": {
          "parent": {
            "id": 1,
            "parent_id": 0,
            "children": {},
            "parent": {
              "__initializer__": {},
              "__cloner__": {},
              "__isInitialized__": false
            },
            "name": "Bank #1",
            "phone": "555-555-5555",
            "fax": "666-666-6666",
            "address1": "55 Any Street",
            "address2": "Suite 100",
            "city": "Wellington",
            "zone_id": 18,
            "zip": "33496",
            "product_1_price": "0.00",
            "product_2_price": "0.00",
            "allow_email_attachment": 1,
            "is_active": 1,
            "created": {
              "date": "2011-06-04 00:26:43.000000",
              "timezone_type": 3,
              "timezone": "UTC"
            },
            "modified": {
              "date": "2011-12-29 14:19:29.000000",
              "timezone_type": 3,
              "timezone": "UTC"
            },
            "_links": {
              "self": {
                "href": "http://localhost:8080/banks/1"
              }
            }
          }
        }
      }
    ]
  }
}

Response code: 200 (OK); Time: 6720ms; Content length: 4446 bytes

http://localhost:8080/banks?page=2

GET http://localhost:8080/banks?page=2

HTTP/1.1 200 OK
Date: Sat, 06 Mar 2021 06:42:26 GMT
Server: Apache/2.4.38 (Debian)
X-Powered-By: PHP/7.3.27
Content-Length: 3169
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/hal+json

{
  "_total_items": 5,
  "_page": 2,
  "_page_count": 3,
  "_links": {
    "self": {
      "href": "http://localhost:8080/banks/?page=2"
    },
    "first": {
      "href": "http://localhost:8080/banks/?page=1"
    },
    "prev": {
      "href": "http://localhost:8080/banks/?page=1"
    },
    "next": {
      "href": "http://localhost:8080/banks/?page=3"
    },
    "last": {
      "href": "http://localhost:8080/banks/?page=3"
    }
  },
  "_embedded": {
    "bank": [
      {
        "id": 4,
        "parent_id": 1,
        "children": {},
        "parent": {
          "__initializer__": {},
          "__cloner__": {},
          "__isInitialized__": false
        },
        "name": "New Child Bank",
        "phone": "555-555-5555",
        "fax": "666-666-6666",
        "address1": "55 Any Street",
        "address2": "Suite 100",
        "city": "Wellington",
        "zone_id": 18,
        "zip": "33496",
        "product_1_price": "8.50",
        "product_2_price": "7.80",
        "allow_email_attachment": 1,
        "is_active": 1,
        "created": {
          "date": "2021-03-04 09:29:05.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "modified": {
          "date": "2021-03-04 09:29:05.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "_links": {
          "self": {
            "href": "http://localhost:8080/banks/4"
          }
        },
        "_embedded": {
          "parent": {
            "id": 1,
            "parent_id": 0,
            "children": {},
            "name": "Bank #1",
            "phone": "555-555-5555",
            "fax": "666-666-6666",
            "address1": "55 Any Street",
            "address2": "Suite 100",
            "city": "Wellington",
            "zone_id": 18,
            "zip": "33496",
            "product_1_price": "0.00",
            "product_2_price": "0.00",
            "allow_email_attachment": 1,
            "is_active": 1,
            "created": {
              "date": "2011-06-04 00:26:43.000000",
              "timezone_type": 3,
              "timezone": "UTC"
            },
            "modified": {
              "date": "2011-12-29 14:19:29.000000",
              "timezone_type": 3,
              "timezone": "UTC"
            },
            "_links": {
              "self": {
                "href": "http://localhost:8080/banks/1"
              }
            }
          }
        }
      },
      {
        "id": 5,
        "parent_id": 1,
        "children": {},
        name": "New Child Bank #2",
        "phone": "555-555-5555",
        "fax": "666-666-6666",
        "address1": "55 Any Street",
        "address2": "Suite 100",
        "city": "Wellington",
        "zone_id": 18,
        "zip": "33496",
        "product_1_price": "8.50",
        "product_2_price": "7.80",
        "allow_email_attachment": 1,
        "is_active": 1,
        "created": {
          "date": "2021-03-04 11:23:58.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "modified": {
          "date": "2021-03-04 11:23:58.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "_links": {
          "self": {
            "href": "http://localhost:8080/banks/5"
          }
        },
        "_embedded": {
          "parent": {
            "id": 1,
            "parent_id": 0,
            "children": {},
            "parent": {
              "__initializer__": {},
              "__cloner__": {},
              "__isInitialized__": false
            },
            "name": "Bank #1",
            "phone": "555-555-5555",
            "fax": "666-666-6666",
            "address1": "55 Any Street",
            "address2": "Suite 100",
            "city": "Wellington",
            "zone_id": 18,
            "zip": "33496",
            "product_1_price": "0.00",
            "product_2_price": "0.00",
            "allow_email_attachment": 1,
            "is_active": 1,
            "created": {
              "date": "2011-06-04 00:26:43.000000",
              "timezone_type": 3,
              "timezone": "UTC"
            },
            "modified": {
              "date": "2011-12-29 14:19:29.000000",
              "timezone_type": 3,
              "timezone": "UTC"
            },
            "_links": {
              "self": {
                "href": "http://localhost:8080/banks/1"
              }
            }
          }
        }
      }
    ]
  }
}

Response code: 200 (OK); Time: 6778ms; Content length: 3169 bytes

Unable to convert self-referring instances to resources

• Are you fixing a bug?
  • Detail how the bug is invoked currently.
  • Detail the original, incorrect behavior.
  • Detail the new, expected behavior.
  • Base your feature on the master branch, and submit against that branch.
  • Add a regression test that demonstrates the bug, and proves the fix.
  • Add a CHANGELOG.md entry for the fix.

Imagine the following example:

class Parent {
    /** @var Child[] */
    public $childs;
    public function addChild(Child $child) {
        $this->childs[] = $child;
        $child->parent = $this;
    }
}
class Child {
    /** @var Parent */
    public $parent;
}

$parent = new Parent();
$parent->addChild(new Child());
$parent->addChild(new Child());

$generator->fromObject($parent, $request);
// the call above will result in an error:
// Error : Maximum function nesting level of '256' reached, aborting!

Other examples:
One-To-One, Bidirectional
One-To-One, Self-referencing
One-To-Many, Bidirectional
One-To-Many, Self-referencing
Many-To-Many, Bidirectional
Many-To-Many, Self-referencing

The zfcampus/zf-hal component solved this issue by using a $maxDepth property in metadata which is then passed through here and here.

Using this approach would result in a change of the \Zend\Expressive\Hal\ResourceGenerator\StrategyInterface interface which would be a BC break.

I would love if someone comes up with an alternate solution which will not break BC.

---

Originally posted by @tobias-trozowski at zendframework/zend-expressive-hal#57

Replace Prophecy with Native PHPUnit Mocks

Feature Request

Q	A
New Feature	yes
RFC	no
BC Break	no

Summary

All of the tests need to be altered to use native PHPUnit Mocks instead of Prophecy. Prophecy needs removing from dependencies. A huge chunk of the Psalm baseline is due to prophecy usage here.

Option to avoid structure equivalence check

I suspect that sometimes it would be nice to have the option to skip the check provided by the HalResource::compareResources method.

This is because sometimes resources could have optional fields, or because an embedded resource makes sense only in certain cases

---

Originally posted by @marcosh at zendframework/zend-expressive-hal#54

HalResource::validateElementName() with numbered array

While trying to create a resource from a numbered array an exception is thrown due to empty($name) check on zero index on this line.

Code to reproduce the issue

$array = [
    ['foo' => 'bar'],
];
$resource->embed('foobar', $resourceGenerator->fromArray($array));

Expected results

The resource should be generated just fine.

Actual results

Exception is thrown: $name provided to Zend\Expressive\Hal\HalResource cannot be empty

---

Originally posted by @grizzm0 at zendframework/zend-expressive-hal#42

Link with `null` attribute

Creating a Link with a null attribute, I get an InvalidArgumentException. I'm not 100% sure about it but I guess that having null attributes should be allowed in Hal links

Code to reproduce the issue

new Link('a', 'b', false, ['c' => null]);

Expected results

I would expect to get a Link with a c attribute with a null value

Actual results

An InvalidArgumentException with message Zend\\Expressive\\Hal\\Link expects the $value to be a PHP primitive or array of strings; received NULL is thrown

---

Originally posted by @marcosh at zendframework/zend-expressive-hal#46

Resource Generator abstract class

Feature Request

Q	A
New Feature	yes
RFC	yes/no
BC Break	yes/no

Summary

Library heavily depends on static ResourceGenerator class. It is nearly impossible to create your own. As strategy methods accepts this type of class. It is possible to extend the class but its constructor requires metadatamap, hydrators, linkgenerator etc. Some of them I don't need and assigning null to them is not possible.

So there should be a an abstract ResourceGenerator class (or interface class) to implement our own.