├── .laminas-ci.json
├── COPYRIGHT.md
├── LICENSE.md
├── README.md
├── composer.json
├── composer.lock
├── psalm-baseline.xml
├── psalm.xml.dist
├── renovate.json
└── src
├── ConfigProvider.php
├── Exception
├── ExceptionInterface.php
├── InvalidObjectException.php
├── InvalidResourceValueException.php
├── InvalidStrategyException.php
└── UnknownMetadataTypeException.php
├── HalResource.php
├── HalResponseFactory.php
├── HalResponseFactoryFactory.php
├── Link.php
├── LinkCollection.php
├── LinkGenerator.php
├── LinkGenerator
├── MezzioUrlGenerator.php
├── MezzioUrlGeneratorFactory.php
└── UrlGeneratorInterface.php
├── LinkGeneratorFactory.php
├── Metadata
├── AbstractCollectionMetadata.php
├── AbstractMetadata.php
├── AbstractResourceMetadata.php
├── Exception
│ ├── DuplicateMetadataException.php
│ ├── ExceptionInterface.php
│ ├── InvalidConfigException.php
│ ├── UndefinedClassException.php
│ └── UndefinedMetadataException.php
├── MetadataFactoryInterface.php
├── MetadataMap.php
├── MetadataMapFactory.php
├── RouteBasedCollectionMetadata.php
├── RouteBasedCollectionMetadataFactory.php
├── RouteBasedResourceMetadata.php
├── RouteBasedResourceMetadataFactory.php
├── UrlBasedCollectionMetadata.php
├── UrlBasedCollectionMetadataFactory.php
├── UrlBasedResourceMetadata.php
└── UrlBasedResourceMetadataFactory.php
├── Psr17ResponseFactoryTrait.php
├── Renderer
├── JsonRenderer.php
├── RendererInterface.php
└── XmlRenderer.php
├── ResourceGenerator.php
├── ResourceGenerator
├── Exception
│ ├── ExceptionInterface.php
│ ├── InvalidCollectionException.php
│ ├── InvalidConfigException.php
│ ├── InvalidExtractorException.php
│ ├── OutOfBoundsException.php
│ └── UnexpectedMetadataTypeException.php
├── ExtractCollectionTrait.php
├── ExtractInstanceTrait.php
├── GenerateSelfLinkTrait.php
├── RouteBasedCollectionStrategy.php
├── RouteBasedResourceStrategy.php
├── StrategyInterface.php
├── UrlBasedCollectionStrategy.php
└── UrlBasedResourceStrategy.php
├── ResourceGeneratorFactory.php
├── ResourceGeneratorInterface.php
└── Response
└── CallableResponseFactoryDecorator.php
/.laminas-ci.json:
--------------------------------------------------------------------------------
1 | {
2 | "ignore_php_platform_requirements": {
3 | "8.4": true
4 | },
5 | "backwardCompatibilityCheck": true
6 | }
7 |
--------------------------------------------------------------------------------
/COPYRIGHT.md:
--------------------------------------------------------------------------------
1 | Copyright (c) 2020 Laminas Project a Series of LF Projects, LLC. (https://getlaminas.org/)
2 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | Copyright (c) 2020 Laminas Project a Series of LF Projects, LLC.
2 |
3 | Redistribution and use in source and binary forms, with or without
4 | modification, are permitted provided that the following conditions are met:
5 |
6 | - Redistributions of source code must retain the above copyright notice, this
7 | list of conditions and the following disclaimer.
8 |
9 | - Redistributions in binary form must reproduce the above copyright notice,
10 | this list of conditions and the following disclaimer in the documentation
11 | and/or other materials provided with the distribution.
12 |
13 | - Neither the name of Laminas Foundation nor the names of its contributors may
14 | be used to endorse or promote products derived from this software without
15 | specific prior written permission.
16 |
17 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
18 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
21 | ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
24 | ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Hypertext Application Language (HAL) for PSR-7 Applications
2 |
3 | [](https://github.com/mezzio/mezzio-hal/actions/workflows/continuous-integration.yml)
4 | [](https://shepherd.dev/github/mezzio/mezzio-hal)
5 | [](https://shepherd.dev/github/mezzio/mezzio-hal)
6 |
7 | > ## 🇷🇺 Русским гражданам
8 | >
9 | > Мы, участники Laminas, родились и живем в разных странах. У многих из нас есть друзья, родственники и коллеги как в России, так и в Украине. Некоторые из нас родились в России. Некоторые из нас живут в России. У некоторых бабушки и дедушки сражались с фашистами во Второй мировой войне. Здесь никто не поддерживает фашизм.
10 | >
11 | > У одного из нас есть украинская родственница, которая спаслась из дома вместе с сыном. Поезд задержался из-за бомбежки на дороге впереди. У нас есть друзья, которые прячутся в бомбоубежищах. Мы с тревогой ждем весточки от них после воздушных налетов, которые беспорядочно наносят удары и попадают по больницам, школам, детским садам и домам. Мы не берем это из каких-либо СМИ. Мы наблюдаем это напрямую.
12 | >
13 | > Вы доверяете нам достаточно, чтоб использовать наши программы, и мы просим вас довериться нам вновь. Мы нуждаемся в помощи. Выходите и протестуйте против этой бесполезной войны. Остановите кровопролитие. Скажите "Нет войне!"
14 | >
15 | > ## 🇺🇸 To Citizens of Russia
16 | >
17 | > 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.
18 | >
19 | > 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.
20 | >
21 | > 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!"
22 |
23 | This library provides utilities for modeling HAL resources with links and generating [PSR-7](https://www.php-fig.org/psr/psr-7/) responses representing both JSON and XML serializations of them.
24 | (The library consumes [PSR-17](https://www.php-fig.org/psr/psr-17/) `ResponseFactoryInterface` implementations in order to provide HAL response instances.)
25 |
26 | ## Installation
27 |
28 | Run the following to install this library:
29 |
30 | ```bash
31 | $ composer require mezzio/mezzio-hal
32 | ```
33 |
34 | ## Documentation
35 |
36 | Documentation is [in the doc tree](docs/book/), and can be compiled using [mkdocs](https://www.mkdocs.org):
37 |
38 | ```bash
39 | $ mkdocs build
40 | ```
41 |
42 | You may also [browse the documentation online](https://docs.mezzio.dev/mezzio-hal/).
43 |
--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "mezzio/mezzio-hal",
3 | "description": "Hypertext Application Language implementation for PHP and PSR-7",
4 | "license": "BSD-3-Clause",
5 | "keywords": [
6 | "laminas",
7 | "mezzio",
8 | "hal",
9 | "http",
10 | "psr",
11 | "psr-7",
12 | "psr-11",
13 | "psr-13",
14 | "psr-17",
15 | "rest"
16 | ],
17 | "homepage": "https://mezzio.dev",
18 | "support": {
19 | "docs": "https://docs.mezzio.dev/mezzio-hal/",
20 | "issues": "https://github.com/mezzio/mezzio-hal/issues",
21 | "source": "https://github.com/mezzio/mezzio-hal",
22 | "rss": "https://github.com/mezzio/mezzio-hal/releases.atom",
23 | "chat": "https://laminas.dev/chat",
24 | "forum": "https://discourse.laminas.dev"
25 | },
26 | "config": {
27 | "sort-packages": true,
28 | "platform": {
29 | "php": "8.1.99"
30 | },
31 | "allow-plugins": {
32 | "dealerdirect/phpcodesniffer-composer-installer": true
33 | }
34 | },
35 | "extra": {
36 | "laminas": {
37 | "config-provider": "Mezzio\\Hal\\ConfigProvider"
38 | }
39 | },
40 | "require": {
41 | "php": "~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0",
42 | "ext-dom": "*",
43 | "ext-json": "*",
44 | "psr/container": "^1.1.2 || ^2.0.2",
45 | "psr/http-factory": "^1.0",
46 | "psr/http-message": "^1.0.1 || ^2.0.0",
47 | "psr/link": "^1.0",
48 | "webmozart/assert": "^1.10",
49 | "willdurand/negotiation": "^3.0"
50 | },
51 | "require-dev": {
52 | "doctrine/orm": "^2.20.2",
53 | "laminas/laminas-coding-standard": "~3.1.0",
54 | "laminas/laminas-hydrator": "^4.16",
55 | "laminas/laminas-paginator": "^2.19.0",
56 | "mezzio/mezzio-helpers": "^5.17",
57 | "phpspec/prophecy-phpunit": "^2.3.0",
58 | "phpunit/phpunit": "^9.6.22",
59 | "psalm/plugin-phpunit": "^0.19.0",
60 | "vimeo/psalm": "^5.26.1"
61 | },
62 | "provide": {
63 | "psr/link-implementation": "1.0"
64 | },
65 | "suggest": {
66 | "laminas/laminas-hydrator": "^4.3 in order to use the ResourceGenerator to create Resource instances from objects",
67 | "laminas/laminas-paginator": "^2.11 in order to provide paginated collections",
68 | "mezzio/mezzio-helpers": "^5.7 in order to use UrlHelper/ServerUrlHelper-based MezzioUrlGenerator with the LinkGenerator",
69 | "psr/container-implementation": "^1.0 in order to use the provided PSR-11 factories"
70 | },
71 | "autoload": {
72 | "psr-4": {
73 | "Mezzio\\Hal\\": "src/"
74 | }
75 | },
76 | "autoload-dev": {
77 | "psr-4": {
78 | "MezzioTest\\Hal\\": "test/"
79 | }
80 | },
81 | "scripts": {
82 | "check": [
83 | "@cs-check",
84 | "@test"
85 | ],
86 | "cs-check": "phpcs",
87 | "cs-fix": "phpcbf",
88 | "static-analysis": "psalm --shepherd --stats",
89 | "test": "phpunit --colors=always",
90 | "test-coverage": "phpunit --colors=always --coverage-clover clover.xml"
91 | },
92 | "conflict": {
93 | "zendframework/zend-expressive-hal": "*"
94 | }
95 | }
96 |
--------------------------------------------------------------------------------
/psalm-baseline.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | $item->toArray()]]>
20 |
21 |
22 | embedded]]>
58 | embedded]]>
59 | embedded]]>
60 |
61 |
62 | aggregateEmbeddedCollection($name, $resource, $context)]]>
64 | getValue(), 'json')]]>
70 |
71 |
72 | getValue()]]>
73 |
74 |
75 | validateRelation($relation)]]>
107 |
108 |
109 | get($this->urlHelperServiceName)]]>
139 | has(ServerUrlHelper::class)
140 | ? $container->get(ServerUrlHelper::class)
141 | : ($container->has(\Zend\Expressive\Helper\ServerUrlHelper::class)
142 | ? $container->get(\Zend\Expressive\Helper\ServerUrlHelper::class)
143 | : null)]]>
144 | get($this->urlGeneratorServiceName)]]>
150 | $method($metadata)]]>
189 |
190 |
191 |
192 |
193 | 'id'],
238 | $metadata['max_depth'] ?? 10
239 | )]]>
240 |
241 |
242 | 'id'],
249 | $metadata['max_depth'] ?? 10
250 | )]]>
251 |
252 |
253 | >>]]>
306 |
307 |
308 | getExtractor()]]>
387 |
388 |
389 | getQueryStringArguments()]]>
402 | getQueryStringArguments()]]>
403 | getRoute()]]>
404 | getRouteParams()]]>
405 | getQueryParams(), $metadata->getQueryStringArguments())]]>
412 |
413 |
414 | get($strategy)]]>
459 | get($this->linkGeneratorServiceName)]]>
460 | get(HydratorPluginManager::class)]]>
461 | get(Metadata\MetadataMap::class)]]>
462 | getHref()]]>
480 | getRels()]]>
481 |
482 |
483 | $embedded]]]>
504 | 'bar']]]>
505 |
506 |
507 | reveal()]]>
783 | reveal()]]>
784 | reveal()]]>
785 |
786 |
787 | array_key_exists('foo_id', $params)
809 | && array_key_exists('bar_id', $params)
810 | && $params['foo_id'] === 1234
811 | && $params['bar_id'] === $i)]]>
812 | array_key_exists('foo_id', $params)
813 | && array_key_exists('p', $params)
814 | && $params['foo_id'] === 1234
815 | && $params['p'] === $page)]]>
816 |
817 |
818 | reveal()]]>
819 | reveal()]]>
820 | createCollectionItems(
821 | $linkGenerator,
822 | $request
823 | )]]>
824 |
825 |
826 | array_key_exists('foo_id', $params)
835 | && array_key_exists('bar_id', $params)
836 | && $params['foo_id'] === 1234
837 | && $params['bar_id'] === $i)]]>
838 |
839 |
840 | reveal()]]>
841 | createCollectionItems($linkGenerator, $request)]]>
842 |
843 |
844 | container->reveal()]]>
858 | container->reveal()]]>
859 | container->reveal()]]>
860 | container->reveal()]]>
861 | array_key_exists('foo_bar_id', $params)
895 | && array_key_exists('test', $params)
896 | && $params['foo_bar_id'] === $i
897 | && $params['test'] === 'param')]]>
898 | array_key_exists('foo_bar_id', $params)
899 | && array_key_exists('test', $params)
900 | && $params['foo_bar_id'] === $i
901 | && $params['test'] === 'param')]]>
902 | array_key_exists('foo_bar_id', $params)
903 | && array_key_exists('test', $params)
904 | && $params['foo_bar_id'] === 'XXXX-YYYY-ZZZZ'
905 | && $params['test'] === 'param')]]>
906 |
40 | * $config['mezzio-hal']['metadata-factories'][MyMetadata::class] = MyMetadataFactory::class;
41 | *
42 | *
43 | * The factory mapped should implement `MetadataFactoryInterface`.
44 | */
45 | class MetadataMapFactory
46 | {
47 | public function __invoke(ContainerInterface $container): MetadataMap
48 | {
49 | $config = $container->has('config') ? $container->get('config') : [];
50 | $metadataMapConfig = $config[MetadataMap::class] ?? [];
51 |
52 | if (! is_array($metadataMapConfig)) {
53 | throw Exception\InvalidConfigException::dueToNonArray($metadataMapConfig);
54 | }
55 |
56 | $metadataFactories = $config['mezzio-hal']['metadata-factories'] ?? [];
57 |
58 | return $this->populateMetadataMapFromConfig(
59 | new MetadataMap(),
60 | $metadataMapConfig,
61 | $metadataFactories
62 | );
63 | }
64 |
65 | private function populateMetadataMapFromConfig(
66 | MetadataMap $metadataMap,
67 | array $metadataMapConfig,
68 | array $metadataFactories
69 | ): MetadataMap {
70 | foreach ($metadataMapConfig as $metadata) {
71 | if (! is_array($metadata)) {
72 | throw Exception\InvalidConfigException::dueToNonArrayMetadata($metadata);
73 | }
74 |
75 | $this->injectMetadata($metadataMap, $metadata, $metadataFactories);
76 | }
77 |
78 | return $metadataMap;
79 | }
80 |
81 | /**
82 | * @throws Exception\InvalidConfigException If the metadata is missing a
83 | * "__class__" entry.
84 | * @throws Exception\InvalidConfigException If the "__class__" entry is not
85 | * a class.
86 | * @throws Exception\InvalidConfigException If the "__class__" entry is not
87 | * an AbstractMetadata class.
88 | * @throws Exception\InvalidConfigException If no matching `create*()`
89 | * method is found for the "__class__" entry.
90 | */
91 | private function injectMetadata(MetadataMap $metadataMap, array $metadata, array $metadataFactories): void
92 | {
93 | if (! isset($metadata['__class__'])) {
94 | throw Exception\InvalidConfigException::dueToMissingMetadataClass();
95 | }
96 |
97 | if (! class_exists($metadata['__class__'])) {
98 | throw Exception\InvalidConfigException::dueToInvalidMetadataClass($metadata['__class__']);
99 | }
100 |
101 | $metadataClass = $metadata['__class__'];
102 | if (! in_array(AbstractMetadata::class, class_parents($metadataClass), true)) {
103 | throw Exception\InvalidConfigException::dueToNonMetadataClass($metadataClass);
104 | }
105 |
106 | if (isset($metadataFactories[$metadataClass])) {
107 | // A factory was registered. Use it!
108 | $metadataMap->add($this->createMetadataViaFactoryClass(
109 | $metadataClass,
110 | $metadata,
111 | $metadataFactories[$metadataClass]
112 | ));
113 | return;
114 | }
115 |
116 | // No factory was registered. Use the deprecated factory method.
117 | $metadataMap->add($this->createMetadataViaFactoryMethod(
118 | $metadataClass,
119 | $metadata
120 | ));
121 | }
122 |
123 | /**
124 | * Uses the registered factory class to create the metadata instance.
125 | */
126 | private function createMetadataViaFactoryClass(
127 | string $metadataClass,
128 | array $metadata,
129 | string $factoryClass
130 | ): AbstractMetadata {
131 | if (! in_array(MetadataFactoryInterface::class, class_implements($factoryClass), true)) {
132 | throw Exception\InvalidConfigException::dueToInvalidMetadataFactoryClass($factoryClass);
133 | }
134 |
135 | $factory = new $factoryClass();
136 | /** @var MetadataFactoryInterface $factory */
137 | return $factory->createMetadata($metadataClass, $metadata);
138 | }
139 |
140 | /**
141 | * Call the factory method in this class namend "createMyMetadata(array $metadata)".
142 | *
143 | * This function is to ensure backwards compatibility with versions prior to 0.6.0.
144 | */
145 | private function createMetadataViaFactoryMethod(string $metadataClass, array $metadata): AbstractMetadata
146 | {
147 | $normalizedClass = $this->stripNamespaceFromClass($metadataClass);
148 | $method = sprintf('create%s', $normalizedClass);
149 |
150 | if (! method_exists($this, $method)) {
151 | throw Exception\InvalidConfigException::dueToUnrecognizedMetadataClass($metadataClass);
152 | }
153 |
154 | return $this->$method($metadata);
155 | }
156 |
157 | private function stripNamespaceFromClass(string $class): string
158 | {
159 | $segments = explode('\\', $class);
160 | return array_pop($segments);
161 | }
162 | }
163 |
--------------------------------------------------------------------------------
/src/Metadata/RouteBasedCollectionMetadata.php:
--------------------------------------------------------------------------------
1 | $routeParams
11 | * @param array $queryStringArguments
12 | */
13 | public function __construct(
14 | string $class,
15 | string $collectionRelation,
16 | private readonly string $route,
17 | string $paginationParam = 'page',
18 | string $paginationParamType = self::TYPE_QUERY,
19 | private array $routeParams = [],
20 | private array $queryStringArguments = []
21 | ) {
22 | $this->class = $class;
23 | $this->collectionRelation = $collectionRelation;
24 | $this->paginationParam = $paginationParam;
25 | $this->paginationParamType = $paginationParamType;
26 | }
27 |
28 | public function getRoute(): string
29 | {
30 | return $this->route;
31 | }
32 |
33 | /** @return array */
34 | public function getRouteParams(): array
35 | {
36 | return $this->routeParams;
37 | }
38 |
39 | /** @return array */
40 | public function getQueryStringArguments(): array
41 | {
42 | return $this->queryStringArguments;
43 | }
44 |
45 | /**
46 | * Allow run-time overriding/injection of route parameters.
47 | *
48 | * In particular, this is useful for setting a parent identifier
49 | * in the route when dealing with child resources.
50 | *
51 | * @param array $routeParams
52 | */
53 | public function setRouteParams(array $routeParams): void
54 | {
55 | $this->routeParams = $routeParams;
56 | }
57 |
58 | /**
59 | * Allow run-time overriding/injection of query string arguments.
60 | *
61 | * In particular, this is useful for setting query string arguments for
62 | * searches, sorts, limits, etc.
63 | *
64 | * @param array $query
65 | */
66 | public function setQueryStringArguments(array $query): void
67 | {
68 | $this->queryStringArguments = $query;
69 | }
70 | }
71 |
--------------------------------------------------------------------------------
/src/Metadata/RouteBasedCollectionMetadataFactory.php:
--------------------------------------------------------------------------------
1 |
18 | * [
19 | * // Fully qualified class name of the AbstractMetadata type.
20 | * '__class__' => RouteBasedCollectionMetadata::class,
21 | *
22 | * // Fully qualified class name of the collection class.
23 | * 'collection_class' => MyCollection::class,
24 | *
25 | * // The embedded relation for the collection in the generated resource.
26 | * 'collection_relation' => 'items',
27 | *
28 | * // The route to use when generating a self relational link for the
29 | * // collection resource.
30 | * 'route' => 'items.list',
31 | *
32 | * // Optional params
33 | *
34 | * // The name of the parameter indicating what page of data is present.
35 | * // Defaults to "page".
36 | * 'pagination_param' => 'page',
37 | *
38 | * // Whether the pagination parameter is a query string or path placeholder.
39 | * // Use either AbstractCollectionMetadata::TYPE_QUERY (the default)
40 | * // or AbstractCollectionMetadata::TYPE_PLACEHOLDER.
41 | * 'pagination_param_type' => AbstractCollectionMetadata::TYPE_QUERY,
42 | *
43 | * // An array of additional routing parameters to use when generating
44 | * // the self relational link for the collection resource.
45 | * // Defaults to an empty array.
46 | * 'route_params' => [],
47 | *
48 | * // An array of query string parameters to include when generating the
49 | * // self relational link for the collection resource.
50 | * // Defaults to an empty array.
51 | * 'query_string_arguments' => [],
52 | * ]
53 | *
54 | * @throws Exception\InvalidConfigException
55 | */
56 | public function createMetadata(string $requestedName, array $metadata): AbstractMetadata
57 | {
58 | $requiredKeys = [
59 | 'collection_class',
60 | 'collection_relation',
61 | 'route',
62 | ];
63 |
64 | if ($requiredKeys !== array_intersect($requiredKeys, array_keys($metadata))) {
65 | throw Exception\InvalidConfigException::dueToMissingMetadata(
66 | RouteBasedCollectionMetadata::class,
67 | $requiredKeys
68 | );
69 | }
70 |
71 | return new $requestedName(
72 | $metadata['collection_class'],
73 | $metadata['collection_relation'],
74 | $metadata['route'],
75 | $metadata['pagination_param'] ?? 'page',
76 | $metadata['pagination_param_type'] ?? RouteBasedCollectionMetadata::TYPE_QUERY,
77 | $metadata['route_params'] ?? [],
78 | $metadata['query_string_arguments'] ?? []
79 | );
80 | }
81 | }
82 |
--------------------------------------------------------------------------------
/src/Metadata/RouteBasedResourceMetadata.php:
--------------------------------------------------------------------------------
1 | class = $class;
33 | $this->route = $route;
34 | $this->extractor = $extractor;
35 | $this->resourceIdentifier = $resourceIdentifier;
36 | $this->routeParams = $routeParams;
37 | $this->identifiersToPlaceHoldersMapping = $identifiersToPlaceholdersMapping;
38 | $this->maxDepth = $maxDepth;
39 | }
40 |
41 | public function getRoute(): string
42 | {
43 | return $this->route;
44 | }
45 |
46 | public function getIdentifiersToPlaceholdersMapping(): array
47 | {
48 | return $this->identifiersToPlaceHoldersMapping;
49 | }
50 |
51 | /**
52 | * This method has been kept for BC and should be deprecated.
53 | */
54 | public function getResourceIdentifier(): string
55 | {
56 | return $this->resourceIdentifier;
57 | }
58 |
59 | public function getRouteParams(): array
60 | {
61 | return $this->routeParams;
62 | }
63 |
64 | public function setRouteParams(array $routeParams): void
65 | {
66 | $this->routeParams = $routeParams;
67 | }
68 | }
69 |
--------------------------------------------------------------------------------
/src/Metadata/RouteBasedResourceMetadataFactory.php:
--------------------------------------------------------------------------------
1 |
18 | * [
19 | * // Fully qualified class name of the AbstractMetadata type.
20 | * '__class__' => RouteBasedResourceMetadata::class,
21 | *
22 | * // Fully qualified class name of the resource class.
23 | * 'resource_class' => MyResource::class,
24 | *
25 | * // The route to use when generating a self relational link for
26 | * // the resource.
27 | * 'route' => 'my-resouce',
28 | *
29 | * // The extractor/hydrator service to use to extract resource data.
30 | * 'extractor' => 'MyExtractor',
31 | *
32 | * // Optional params
33 | *
34 | * // What property in the resource represents its identifier.
35 | * // Defaults to "id".
36 | * 'resource_identifier' => 'id',
37 | *
38 | * // An array of additional routing parameters to use when
39 | * // generating the self relational link for the collection
40 | * // resource. Defaults to an empty array.
41 | * 'route_params' => [],
42 | *
43 | * // An array mapping resource properties to routing placeholder
44 | * // names. This can also be used to replace the
45 | * // 'route_identifier_placeholder' setting, which will be removed
46 | * // in version 2.0.
47 | * 'identifiers_to_placeholders_mapping' => ['id' => 'id'],
48 | *
49 | * // Max depth to render
50 | * // Defaults to 10.
51 | * 'max_depth' => 10,
52 | * ]
53 | *
54 | * @throws Exception\InvalidConfigException
55 | */
56 | public function createMetadata(string $requestedName, array $metadata): AbstractMetadata
57 | {
58 | $requiredKeys = [
59 | 'resource_class',
60 | 'route',
61 | 'extractor',
62 | ];
63 |
64 | if ($requiredKeys !== array_intersect($requiredKeys, array_keys($metadata))) {
65 | throw Exception\InvalidConfigException::dueToMissingMetadata(
66 | RouteBasedResourceMetadata::class,
67 | $requiredKeys
68 | );
69 | }
70 |
71 | return new $requestedName(
72 | $metadata['resource_class'],
73 | $metadata['route'],
74 | $metadata['extractor'],
75 | $metadata['resource_identifier'] ?? 'id',
76 | $metadata['route_params'] ?? [],
77 | $metadata['identifiers_to_placeholders_mapping'] ?? ['id' => 'id'],
78 | $metadata['max_depth'] ?? 10
79 | );
80 | }
81 | }
82 |
--------------------------------------------------------------------------------
/src/Metadata/UrlBasedCollectionMetadata.php:
--------------------------------------------------------------------------------
1 | class = $class;
42 | $this->collectionRelation = $collectionRelation;
43 | $this->paginationParam = $paginationParam;
44 | $this->paginationParamType = $paginationParamType;
45 | }
46 |
47 | public function getUrl(): string
48 | {
49 | return $this->url;
50 | }
51 | }
52 |
--------------------------------------------------------------------------------
/src/Metadata/UrlBasedCollectionMetadataFactory.php:
--------------------------------------------------------------------------------
1 |
18 | * [
19 | * // Fully qualified class name of the AbstractMetadata type.
20 | * '__class__' => UrlBasedCollectionMetadata::class,
21 | *
22 | * // Fully qualified class name of the collection class.
23 | * 'collection_class' => MyCollection::class,
24 | *
25 | * // The embedded relation for the collection in the generated
26 | * // resource.
27 | * 'collection_relation' => 'items',
28 | *
29 | * // The URL to use when generating a self-relational link for
30 | * // the collection resource.
31 | * 'url' => 'https://example.org/my-collection',
32 | *
33 | * // Optional params
34 | *
35 | * // The name of the parameter indicating what page of data is
36 | * // present. Defaults to "page".
37 | * 'pagination_param' => 'page',
38 | *
39 | * // Whether the pagination parameter is a query string or path
40 | * // placeholder use either AbstractCollectionMetadata::TYPE_QUERY
41 | * // (the default) or AbstractCollectionMetadata::TYPE_PLACEHOLDER.
42 | * 'pagination_param_type' => AbstractCollectionMetadata::TYPE_QUERY,
43 | * ]
44 | *
45 | * @throws Exception\InvalidConfigException
46 | */
47 | public function createMetadata(string $requestedName, array $metadata): AbstractMetadata
48 | {
49 | $requiredKeys = [
50 | 'collection_class',
51 | 'collection_relation',
52 | 'url',
53 | ];
54 |
55 | if ($requiredKeys !== array_intersect($requiredKeys, array_keys($metadata))) {
56 | throw Exception\InvalidConfigException::dueToMissingMetadata(
57 | UrlBasedCollectionMetadata::class,
58 | $requiredKeys
59 | );
60 | }
61 |
62 | return new $requestedName(
63 | $metadata['collection_class'],
64 | $metadata['collection_relation'],
65 | $metadata['url'],
66 | $metadata['pagination_param'] ?? 'page',
67 | $metadata['pagination_param_type'] ?? UrlBasedCollectionMetadata::TYPE_QUERY
68 | );
69 | }
70 | }
71 |
--------------------------------------------------------------------------------
/src/Metadata/UrlBasedResourceMetadata.php:
--------------------------------------------------------------------------------
1 | class = $class;
12 | $this->extractor = $extractor;
13 | $this->maxDepth = $maxDepth;
14 | }
15 |
16 | public function getUrl(): string
17 | {
18 | return $this->url;
19 | }
20 | }
21 |
--------------------------------------------------------------------------------
/src/Metadata/UrlBasedResourceMetadataFactory.php:
--------------------------------------------------------------------------------
1 |
18 | * [
19 | * // Fully qualified class name of the AbstractMetadata type.
20 | * '__class__' => RouteBasedResourceMetadata::class,
21 | *
22 | * // Fully qualified class name of the resource class.
23 | * 'resource_class' => MyResource::class,
24 | *
25 | * // The URL to use when generating a self-relational link for
26 | * // the resource.
27 | * 'url' => 'https://example.org/my-resource',
28 | *
29 | * // The extractor/hydrator service to use to extract resource data.
30 | * 'extractor' => 'MyExtractor',
31 | *
32 | * // Max depth to render
33 | * // Defaults to 10.
34 | * 'max_depth' => 10,
35 | * ]
36 | *
37 | * @throws Exception\InvalidConfigException
38 | */
39 | public function createMetadata(string $requestedName, array $metadata): AbstractMetadata
40 | {
41 | $requiredKeys = [
42 | 'resource_class',
43 | 'url',
44 | 'extractor',
45 | ];
46 |
47 | if ($requiredKeys !== array_intersect($requiredKeys, array_keys($metadata))) {
48 | throw Exception\InvalidConfigException::dueToMissingMetadata(
49 | UrlBasedResourceMetadata::class,
50 | $requiredKeys
51 | );
52 | }
53 |
54 | return new $requestedName(
55 | $metadata['resource_class'],
56 | $metadata['url'],
57 | $metadata['extractor'],
58 | $metadata['max_depth'] ?? 10
59 | );
60 | }
61 | }
62 |
--------------------------------------------------------------------------------
/src/Psr17ResponseFactoryTrait.php:
--------------------------------------------------------------------------------
1 | has(ResponseFactoryInterface::class);
23 |
24 | if (! $psr17FactoryAvailable) {
25 | return $this->createResponseFactoryFromDeprecatedCallable($container);
26 | }
27 |
28 | if ($this->doesConfigurationProvidesDedicatedResponseFactory($container)) {
29 | return $this->createResponseFactoryFromDeprecatedCallable($container);
30 | }
31 |
32 | $responseFactory = $container->get(ResponseFactoryInterface::class);
33 | Assert::isInstanceOf($responseFactory, ResponseFactoryInterface::class);
34 | return $responseFactory;
35 | }
36 |
37 | private function createResponseFactoryFromDeprecatedCallable(
38 | ContainerInterface $container
39 | ): ResponseFactoryInterface {
40 | /** @var callable():ResponseInterface $responseFactory */
41 | $responseFactory = $container->get(ResponseInterface::class);
42 |
43 | return new CallableResponseFactoryDecorator($responseFactory);
44 | }
45 |
46 | private function doesConfigurationProvidesDedicatedResponseFactory(ContainerInterface $container): bool
47 | {
48 | if (! $container->has('config')) {
49 | return false;
50 | }
51 |
52 | $config = $container->get('config');
53 | Assert::isArrayAccessible($config);
54 | $dependencies = $config['dependencies'] ?? [];
55 | Assert::isMap($dependencies);
56 |
57 | $delegators = $dependencies['delegators'] ?? [];
58 | $aliases = $dependencies['aliases'] ?? [];
59 | Assert::isArrayAccessible($delegators);
60 | Assert::isArrayAccessible($aliases);
61 |
62 | if (isset($delegators[ResponseInterface::class]) || isset($aliases[ResponseInterface::class])) {
63 | // Even tho, aliases could point to a different service, we assume that there is a dedicated factory
64 | // available. The alias resolving is not worth it.
65 | return true;
66 | }
67 |
68 | /** @psalm-suppress MixedAssignment */
69 | $deprecatedResponseFactory = $dependencies['factories'][ResponseInterface::class] ?? null;
70 |
71 | return $deprecatedResponseFactory !== null && $deprecatedResponseFactory !== ResponseFactoryFactory::class;
72 | }
73 | }
74 |
--------------------------------------------------------------------------------
/src/Renderer/JsonRenderer.php:
--------------------------------------------------------------------------------
1 | jsonFlags);
26 | }
27 | }
28 |
--------------------------------------------------------------------------------
/src/Renderer/RendererInterface.php:
--------------------------------------------------------------------------------
1 | formatOutput = true;
26 | $dom->appendChild($this->createResourceNode($dom, $resource->toArray()));
27 | return trim($dom->saveXML());
28 | }
29 |
30 | private function createResourceNode(DOMDocument $doc, array $resource, string $resourceRel = 'self'): DOMNode
31 | {
32 | // Normalize resource
33 | $resource['_links'] ??= [];
34 | $resource['_embedded'] ??= [];
35 |
36 | $node = $doc->createElement('resource');
37 |
38 | // Self-relational link attributes, if present and singular
39 | if (isset($resource['_links']['self']['href'])) {
40 | $node->setAttribute('rel', $resourceRel);
41 | $node->setAttribute('href', $resource['_links']['self']['href']);
42 | foreach ($resource['_links']['self'] as $attribute => $value) {
43 | if ($attribute === 'href') {
44 | continue;
45 | }
46 | $node->setAttribute($attribute, $value);
47 | }
48 | unset($resource['_links']['self']);
49 | }
50 |
51 | /**
52 | * @var string $rel
53 | * @var array $linkData
54 | */
55 | foreach ($resource['_links'] as $rel => $linkData) {
56 | if ($this->isAssocArray($linkData)) {
57 | $node->appendChild($this->createLinkNode($doc, $rel, $linkData));
58 | continue;
59 | }
60 |
61 | foreach ($linkData as $linkDatum) {
62 | $node->appendChild($this->createLinkNode($doc, $rel, $linkDatum));
63 | }
64 | }
65 | unset($resource['_links']);
66 |
67 | /**
68 | * @var string $rel
69 | * @var array $childData
70 | */
71 | foreach ($resource['_embedded'] as $rel => $childData) {
72 | if ($this->isAssocArray($childData)) {
73 | $node->appendChild($this->createResourceNode($doc, $childData, $rel));
74 | continue;
75 | }
76 |
77 | foreach ($childData as $childDatum) {
78 | $node->appendChild($this->createResourceNode($doc, $childDatum, $rel));
79 | }
80 | }
81 | unset($resource['_embedded']);
82 |
83 | return $this->createNodeTree($doc, $node, $resource);
84 | }
85 |
86 | private function createLinkNode(DOMDocument $doc, string $rel, array $data): DOMNode
87 | {
88 | $link = $doc->createElement('link');
89 | $link->setAttribute('rel', $rel);
90 | foreach ($data as $key => $value) {
91 | $value = $this->normalizeConstantValue($value);
92 | $link->setAttribute($key, $value);
93 | }
94 | return $link;
95 | }
96 |
97 | /**
98 | * Convert true and false to appropriate strings.
99 | *
100 | * In all other cases, return the value as-is.
101 | *
102 | * @param mixed $value
103 | * @return string|mixed
104 | */
105 | private function normalizeConstantValue($value)
106 | {
107 | $value = $value === true ? 'true' : $value;
108 | $value = $value === false ? 'false' : $value;
109 | return $value;
110 | }
111 |
112 | private function isAssocArray(array $value): bool
113 | {
114 | return array_values($value) !== $value;
115 | }
116 |
117 | /**
118 | * @param mixed $data
119 | * @return ((DOMNode|DOMNode[])[]|DOMNode|false)[]|DOMNode|false
120 | * @psalm-return DOMNode|false|list>>
121 | */
122 | private function createResourceElement(DOMDocument $doc, string $name, $data)
123 | {
124 | if ($data === null) {
125 | return $doc->createElement($name);
126 | }
127 |
128 | if (is_scalar($data)) {
129 | $data = $this->normalizeConstantValue($data);
130 | $element = $doc->createElement($name);
131 | $textNode = $doc->createTextNode((string) $data);
132 | $element->appendChild($textNode);
133 |
134 | return $element;
135 | }
136 |
137 | if (is_object($data)) {
138 | $data = $this->createDataFromObject($data);
139 | return $doc->createElement($name, $data);
140 | }
141 |
142 | if (! is_array($data)) {
143 | throw Exception\InvalidResourceValueException::fromValue($data);
144 | }
145 |
146 | if ($this->isAssocArray($data)) {
147 | return $this->createNodeTree($doc, $doc->createElement($name), $data);
148 | }
149 |
150 | $elements = [];
151 | foreach ($data as $child) {
152 | $elements[] = $this->createResourceElement($doc, $name, $child);
153 | }
154 | return $elements;
155 | }
156 |
157 | private function createNodeTree(DOMDocument $doc, DOMNode $node, array $data): DOMNode
158 | {
159 | foreach ($data as $key => $value) {
160 | $element = $this->createResourceElement($doc, $key, $value);
161 | if (! is_array($element)) {
162 | $node->appendChild($element);
163 | continue;
164 | }
165 | foreach ($element as $child) {
166 | $node->appendChild($child);
167 | }
168 | }
169 |
170 | return $node;
171 | }
172 |
173 | /**
174 | * @todo Detect JsonSerializable, and pass to
175 | * json_decode(json_encode($object), true), passing the final value
176 | * back to createResourceElement()?
177 | * @param object $object
178 | * @throws Exception\InvalidResourceValueException If unable to serialize
179 | * the data to a string.
180 | */
181 | private function createDataFromObject($object): string
182 | {
183 | if ($object instanceof DateTimeInterface) {
184 | return $object->format('c');
185 | }
186 |
187 | if (! method_exists($object, '__toString')) {
188 | throw Exception\InvalidResourceValueException::fromObject($object);
189 | }
190 |
191 | return (string) $object;
192 | }
193 | }
194 |
--------------------------------------------------------------------------------
/src/ResourceGenerator.php:
--------------------------------------------------------------------------------
1 | */
21 | private array $strategies = [];
22 |
23 | /**
24 | * @param Metadata\MetadataMap $metadataMap Metadata on known objects.
25 | * @param ContainerInterface $hydrators Service locator for hydrators.
26 | * @param LinkGenerator $linkGenerator Route-based link generation.
27 | */
28 | public function __construct(
29 | private readonly Metadata\MetadataMap $metadataMap,
30 | private readonly ContainerInterface $hydrators,
31 | private readonly LinkGenerator $linkGenerator
32 | ) {
33 | }
34 |
35 | public function getHydrators(): ContainerInterface
36 | {
37 | return $this->hydrators;
38 | }
39 |
40 | public function getLinkGenerator(): LinkGenerator
41 | {
42 | return $this->linkGenerator;
43 | }
44 |
45 | public function getMetadataMap(): Metadata\MetadataMap
46 | {
47 | return $this->metadataMap;
48 | }
49 |
50 | /**
51 | * Link a metadata type to a strategy that can create a resource for it.
52 | *
53 | * @param class-string|StrategyInterface $strategy
54 | */
55 | public function addStrategy(string $metadataType, $strategy): void
56 | {
57 | if (
58 | ! class_exists($metadataType)
59 | || ! in_array(AbstractMetadata::class, class_parents($metadataType), true)
60 | ) {
61 | throw Exception\UnknownMetadataTypeException::forInvalidMetadataClass($metadataType);
62 | }
63 |
64 | if (
65 | is_string($strategy)
66 | && (
67 | ! class_exists($strategy)
68 | || ! in_array(StrategyInterface::class, class_implements($strategy), true)
69 | )
70 | ) {
71 | throw Exception\InvalidStrategyException::forType($strategy);
72 | }
73 |
74 | if (is_string($strategy)) {
75 | $strategy = new $strategy();
76 | }
77 |
78 | if (! $strategy instanceof StrategyInterface) {
79 | throw Exception\InvalidStrategyException::forInstance($strategy);
80 | }
81 |
82 | $this->strategies[$metadataType] = $strategy;
83 | }
84 |
85 | /**
86 | * Returns the registered strategies.
87 | *
88 | * @return array
89 | */
90 | public function getStrategies(): array
91 | {
92 | return $this->strategies;
93 | }
94 |
95 | public function fromArray(array $data, ?string $uri = null): HalResource
96 | {
97 | /** @var array $config */
98 | $config = $this->hydrators->has('config') ? $this->hydrators->get('config') : [];
99 |
100 | $embedEmptyCollections = (bool) ($config['mezzio-hal']['embed-empty-collections'] ?? false);
101 |
102 | $resource = new HalResource($data, [], [], $embedEmptyCollections);
103 |
104 | if (null !== $uri) {
105 | return $resource->withLink(new Link('self', $uri));
106 | }
107 |
108 | return $resource;
109 | }
110 |
111 | /**
112 | * @param object $instance An object of any type; the type will be checked
113 | * against types registered in the metadata map.
114 | */
115 | public function fromObject(object $instance, ServerRequestInterface $request, int $depth = 0): HalResource
116 | {
117 | $metadata = $this->getClassMetadata($instance);
118 | $metadataType = $metadata::class;
119 |
120 | if (! isset($this->strategies[$metadataType])) {
121 | throw Exception\UnknownMetadataTypeException::forMetadata($metadata);
122 | }
123 |
124 | $strategy = $this->strategies[$metadataType];
125 | return $strategy->createResource(
126 | $instance,
127 | $metadata,
128 | $this,
129 | $request,
130 | $depth
131 | );
132 | }
133 |
134 | private function getClassMetadata(object $instance): AbstractMetadata
135 | {
136 | $class = $instance::class;
137 | if (! $this->metadataMap->has($class)) {
138 | foreach (class_parents($instance) as $parent) {
139 | if ($this->metadataMap->has($parent)) {
140 | return $this->metadataMap->get($parent);
141 | }
142 | }
143 | throw Exception\InvalidObjectException::forUnknownType($class);
144 | }
145 |
146 | return $this->metadataMap->get($class);
147 | }
148 | }
149 |
--------------------------------------------------------------------------------
/src/ResourceGenerator/Exception/ExceptionInterface.php:
--------------------------------------------------------------------------------
1 | extractPaginator($collection, $metadata, $resourceGenerator, $request, $depth);
57 | }
58 |
59 | if ($collection instanceof DoctrinePaginator) {
60 | return $this->extractDoctrinePaginator($collection, $metadata, $resourceGenerator, $request, $depth);
61 | }
62 |
63 | return $this->extractIterator($collection, $metadata, $resourceGenerator, $request, $depth);
64 | }
65 |
66 | /**
67 | * Generates a paginated hal resource from a collection
68 | *
69 | * @throws Exception\OutOfBoundsException If requested page if outside the available pages.
70 | */
71 | private function extractPaginator(
72 | Paginator $collection,
73 | AbstractCollectionMetadata $metadata,
74 | ResourceGeneratorInterface $resourceGenerator,
75 | ServerRequestInterface $request,
76 | int $depth = 0
77 | ): HalResource {
78 | $data = ['_total_items' => $collection->getTotalItemCount()];
79 | $pageCount = $collection->count();
80 |
81 | return $this->createPaginatedCollectionResource(
82 | $pageCount,
83 | $data,
84 | function (int $page) use ($collection) {
85 | $collection->setCurrentPageNumber($page);
86 | },
87 | $collection,
88 | $metadata,
89 | $resourceGenerator,
90 | $request,
91 | $depth
92 | );
93 | }
94 |
95 | /**
96 | * Extract a collection from a Doctrine paginator.
97 | *
98 | * When pagination is requested, and a valid page is found, calls the
99 | * paginator's `setFirstResult()` method with an offset based on the
100 | * max results value set on the paginator.
101 | */
102 | private function extractDoctrinePaginator(
103 | DoctrinePaginator $collection,
104 | AbstractCollectionMetadata $metadata,
105 | ResourceGeneratorInterface $resourceGenerator,
106 | ServerRequestInterface $request,
107 | int $depth = 0
108 | ): HalResource {
109 | $query = $collection->getQuery();
110 | $totalItems = count($collection);
111 | $perPage = $query->getMaxResults();
112 | $pageCount = (int) ceil($totalItems / $perPage);
113 |
114 | $data = ['_total_items' => $totalItems];
115 |
116 | return $this->createPaginatedCollectionResource(
117 | $pageCount,
118 | $data,
119 | function (int $page) use ($query, $perPage) {
120 | $query->setFirstResult($perPage * ($page - 1));
121 | },
122 | $collection,
123 | $metadata,
124 | $resourceGenerator,
125 | $request,
126 | $depth
127 | );
128 | }
129 |
130 | private function extractIterator(
131 | Traversable $collection,
132 | AbstractCollectionMetadata $metadata,
133 | ResourceGeneratorInterface $resourceGenerator,
134 | ServerRequestInterface $request,
135 | int $depth = 0
136 | ): HalResource {
137 | $isCountable = $collection instanceof Countable;
138 | $count = $isCountable ? $collection->count() : 0;
139 |
140 | $resources = [];
141 | foreach ($collection as $item) {
142 | $resources[] = $resourceGenerator->fromObject($item, $request, $depth + 1);
143 | $count = $isCountable ? $count : $count + 1;
144 | }
145 |
146 | $data = ['_total_items' => $count];
147 | $links = [
148 | $this->generateSelfLink(
149 | $metadata,
150 | $resourceGenerator,
151 | $request
152 | ),
153 | ];
154 |
155 | return new HalResource($data, $links, [
156 | $metadata->getCollectionRelation() => $resources,
157 | ]);
158 | }
159 |
160 | /**
161 | * Create a collection resource representing a paginated set.
162 | *
163 | * Determines if the metadata uses a query or placeholder pagination type.
164 | * If not, it generates a self relational link, and then immediately creates
165 | * and returns a collection resource containing every item in the collection.
166 | *
167 | * If it does, it pulls the pagination parameter from the request using the
168 | * appropriate source (query string arguments or routing parameter), and
169 | * then checks to see if we have a valid page number, throwing an out of
170 | * bounds exception if we do not. From the page, it then determines which
171 | * relational pagination links to create, including a `self` relation,
172 | * and aggregates the current page and total page count in the $data array
173 | * before calling on createCollectionResource() to generate the final
174 | * HAL resource instance.
175 | *
176 | * @param array $data Data to render in the root of the HAL
177 | * resource.
178 | * @param callable $notifyCollectionOfPage A callback that receives an integer
179 | * $page argument; this should be used to update the paginator instance
180 | * with the current page number.
181 | */
182 | private function createPaginatedCollectionResource(
183 | int $pageCount,
184 | array $data,
185 | callable $notifyCollectionOfPage,
186 | iterable $collection,
187 | AbstractCollectionMetadata $metadata,
188 | ResourceGeneratorInterface $resourceGenerator,
189 | ServerRequestInterface $request,
190 | int $depth = 0
191 | ): HalResource {
192 | $links = [];
193 | $paginationParamType = $metadata->getPaginationParamType();
194 |
195 | if (! in_array($paginationParamType, $this->paginationTypes, true)) {
196 | $links[] = $this->generateSelfLink($metadata, $resourceGenerator, $request);
197 | return $this->createCollectionResource(
198 | $links,
199 | $data,
200 | $collection,
201 | $metadata,
202 | $resourceGenerator,
203 | $request,
204 | $depth
205 | );
206 | }
207 |
208 | $paginationParam = $metadata->getPaginationParam();
209 | $page = $paginationParamType === AbstractCollectionMetadata::TYPE_QUERY
210 | ? (int) ($request->getQueryParams()[$paginationParam] ?? 1)
211 | : (int) $request->getAttribute($paginationParam, 1);
212 |
213 | if ($page < 1 || ($page > $pageCount && $pageCount > 0)) {
214 | throw new Exception\OutOfBoundsException(sprintf(
215 | 'Page %d is out of bounds. Collection has %d page%s.',
216 | $page,
217 | $pageCount,
218 | $pageCount > 1 ? 's' : ''
219 | ));
220 | }
221 |
222 | $notifyCollectionOfPage($page);
223 |
224 | $links[] = $this->generateLinkForPage('self', $page, $metadata, $resourceGenerator, $request);
225 | if ($page > 1) {
226 | $links[] = $this->generateLinkForPage('first', 1, $metadata, $resourceGenerator, $request);
227 | $links[] = $this->generateLinkForPage('prev', $page - 1, $metadata, $resourceGenerator, $request);
228 | }
229 | if ($page < $pageCount) {
230 | $links[] = $this->generateLinkForPage('next', $page + 1, $metadata, $resourceGenerator, $request);
231 | $links[] = $this->generateLinkForPage('last', $pageCount, $metadata, $resourceGenerator, $request);
232 | }
233 |
234 | $data['_page'] = $page;
235 | $data['_page_count'] = $pageCount;
236 |
237 | return $this->createCollectionResource(
238 | $links,
239 | $data,
240 | $collection,
241 | $metadata,
242 | $resourceGenerator,
243 | $request,
244 | $depth
245 | );
246 | }
247 |
248 | /**
249 | * Create the collection resource with its embedded resources.
250 | *
251 | * Iterates the collection, passing each item to the resource generator
252 | * to produce a HAL resource. These are then used to create an embedded
253 | * relation in a master HAL resource that contains metadata around the
254 | * collection itself (number of items, number of pages, etc.), and any
255 | * relational links.
256 | */
257 | private function createCollectionResource(
258 | array $links,
259 | array $data,
260 | iterable $collection,
261 | AbstractCollectionMetadata $metadata,
262 | ResourceGeneratorInterface $resourceGenerator,
263 | ServerRequestInterface $request,
264 | int $depth = 0
265 | ): HalResource {
266 | $resources = [];
267 | foreach ($collection as $item) {
268 | $resources[] = $resourceGenerator->fromObject($item, $request, $depth + 1);
269 | }
270 |
271 | return new HalResource($data, $links, [
272 | $metadata->getCollectionRelation() => $resources,
273 | ]);
274 | }
275 | }
276 |
--------------------------------------------------------------------------------
/src/ResourceGenerator/ExtractInstanceTrait.php:
--------------------------------------------------------------------------------
1 | getHydrators();
29 | $extractor = $hydrators->get($metadata->getExtractor());
30 | if (! $extractor instanceof ExtractionInterface) {
31 | throw Exception\InvalidExtractorException::fromInstance($extractor);
32 | }
33 |
34 | $array = $extractor->extract($instance);
35 |
36 | if ($metadata->hasReachedMaxDepth($depth)) {
37 | return $array;
38 | }
39 |
40 | // Extract nested resources if present in metadata map
41 | $metadataMap = $resourceGenerator->getMetadataMap();
42 | foreach ($array as $key => $value) {
43 | if (! is_object($value)) {
44 | continue;
45 | }
46 |
47 | $childClass = $value::class;
48 | if (! $metadataMap->has($childClass)) {
49 | continue;
50 | }
51 |
52 | $childData = $resourceGenerator->fromObject($value, $request, $depth + 1);
53 |
54 | // Nested collections need to be merged.
55 | $childMetadata = $metadataMap->get($childClass);
56 | if ($childMetadata instanceof AbstractCollectionMetadata) {
57 | $childData = $childData->getElement($childMetadata->getCollectionRelation());
58 | }
59 |
60 | $array[$key] = $childData;
61 | }
62 |
63 | return $array;
64 | }
65 | }
66 |
--------------------------------------------------------------------------------
/src/ResourceGenerator/GenerateSelfLinkTrait.php:
--------------------------------------------------------------------------------
1 | extractCollection($instance, $metadata, $resourceGenerator, $request, $depth);
42 | }
43 |
44 | /**
45 | * @param string $rel Relation to use when creating Link
46 | * @param int $page Page number for generated link
47 | * @param Metadata\AbstractCollectionMetadata $metadata Used to provide the
48 | * base URL, pagination parameter, and type of pagination used (query
49 | * string, path parameter)
50 | * @param ResourceGeneratorInterface $resourceGenerator Used to retrieve link
51 | * generator in order to generate link based on routing information.
52 | * @param ServerRequestInterface $request Passed to link generator when
53 | * generating link based on routing information.
54 | */
55 | protected function generateLinkForPage(
56 | string $rel,
57 | int $page,
58 | Metadata\AbstractCollectionMetadata $metadata,
59 | ResourceGeneratorInterface $resourceGenerator,
60 | ServerRequestInterface $request
61 | ): Link {
62 | $route = $metadata->getRoute();
63 | $paginationType = $metadata->getPaginationParamType();
64 | $paginationParam = $metadata->getPaginationParam();
65 | $routeParams = $metadata->getRouteParams();
66 | $queryStringArgs = array_merge($request->getQueryParams(), $metadata->getQueryStringArguments());
67 |
68 | $paramsWithPage = [$paginationParam => $page];
69 | $routeParams = $paginationType === Metadata\AbstractCollectionMetadata::TYPE_PLACEHOLDER
70 | ? array_merge($routeParams, $paramsWithPage)
71 | : $routeParams;
72 | $queryParams = $paginationType === Metadata\AbstractCollectionMetadata::TYPE_QUERY
73 | ? array_merge($queryStringArgs, $paramsWithPage)
74 | : $queryStringArgs;
75 |
76 | return $resourceGenerator
77 | ->getLinkGenerator()
78 | ->fromRoute(
79 | $rel,
80 | $request,
81 | $route,
82 | $routeParams,
83 | $queryParams
84 | );
85 | }
86 |
87 | /**
88 | * @param Metadata\AbstractCollectionMetadata $metadata Provides base URL
89 | * for self link.
90 | * @param ResourceGeneratorInterface $resourceGenerator Used to retrieve link
91 | * generator in order to generate link based on routing information.
92 | * @param ServerRequestInterface $request Passed to link generator when
93 | * generating link based on routing information.
94 | * @return Link
95 | */
96 | protected function generateSelfLink(
97 | Metadata\AbstractCollectionMetadata $metadata,
98 | ResourceGeneratorInterface $resourceGenerator,
99 | ServerRequestInterface $request
100 | ) {
101 | return $resourceGenerator
102 | ->getLinkGenerator()
103 | ->fromRoute(
104 | 'self',
105 | $request,
106 | $metadata->getRoute(),
107 | $metadata->getRouteParams(),
108 | array_merge($request->getQueryParams(), $metadata->getQueryStringArguments())
109 | );
110 | }
111 | }
112 |
--------------------------------------------------------------------------------
/src/ResourceGenerator/RouteBasedResourceStrategy.php:
--------------------------------------------------------------------------------
1 | extractInstance(
35 | $instance,
36 | $metadata,
37 | $resourceGenerator,
38 | $request,
39 | $depth
40 | );
41 |
42 | $routeParams = $metadata->getRouteParams();
43 | $placeholderMap = $metadata->getIdentifiersToPlaceholdersMapping();
44 |
45 | // Inject all scalar entity keys automatically into route parameters
46 | foreach ($data as $key => $value) {
47 | if (! is_scalar($value)) {
48 | continue;
49 | }
50 |
51 | if (array_key_exists($key, $placeholderMap)) {
52 | $routeParams[$placeholderMap[$key]] = $value;
53 | continue;
54 | }
55 |
56 | $routeParams[$key] = $value;
57 | }
58 |
59 | if ($metadata->hasReachedMaxDepth($depth)) {
60 | $data = [];
61 | }
62 |
63 | return new HalResource($data, [
64 | $resourceGenerator->getLinkGenerator()->fromRoute(
65 | 'self',
66 | $request,
67 | $metadata->getRoute(),
68 | $routeParams
69 | ),
70 | ]);
71 | }
72 | }
73 |
--------------------------------------------------------------------------------
/src/ResourceGenerator/StrategyInterface.php:
--------------------------------------------------------------------------------
1 | extractCollection($instance, $metadata, $resourceGenerator, $request, $depth);
50 | }
51 |
52 | /**
53 | * @param string $rel Relation to use when creating Link
54 | * @param int $page Page number for generated link
55 | * @param Metadata\AbstractCollectionMetadata $metadata Used to provide the
56 | * base URL, pagination parameter, and type of pagination used (query
57 | * string, path parameter)
58 | * @param ResourceGeneratorInterface $resourceGenerator Ignored; required to fulfill
59 | * abstract.
60 | * @param ServerRequestInterface $request Ignored; required to fulfill
61 | * abstract.
62 | */
63 | protected function generateLinkForPage(
64 | string $rel,
65 | int $page,
66 | Metadata\AbstractCollectionMetadata $metadata,
67 | ResourceGeneratorInterface $resourceGenerator,
68 | ServerRequestInterface $request
69 | ): Link {
70 | $paginationParam = $metadata->getPaginationParam();
71 | $paginationType = $metadata->getPaginationParamType();
72 | $url = $metadata->getUrl() . '?' . http_build_query($request->getQueryParams());
73 |
74 | switch ($paginationType) {
75 | case Metadata\AbstractCollectionMetadata::TYPE_PLACEHOLDER:
76 | $url = str_replace($url, $paginationParam, (string) $page);
77 | break;
78 | case Metadata\AbstractCollectionMetadata::TYPE_QUERY:
79 | // fall-through
80 | default:
81 | $url = $this->stripUrlFragment($url);
82 | $url = $this->appendPageQueryToUrl($url, $page, $paginationParam);
83 | }
84 |
85 | return new Link($rel, $url);
86 | }
87 |
88 | /**
89 | * @param Metadata\AbstractCollectionMetadata $metadata Provides base URL
90 | * for self link.
91 | * @param ResourceGeneratorInterface $resourceGenerator Ignored; required to fulfill
92 | * abstract.
93 | * @param ServerRequestInterface $request Ignored; required to fulfill
94 | * abstract.
95 | * @return Link
96 | */
97 | protected function generateSelfLink(
98 | Metadata\AbstractCollectionMetadata $metadata,
99 | ResourceGeneratorInterface $resourceGenerator,
100 | ServerRequestInterface $request
101 | ) {
102 | $queryStringArgs = $request->getQueryParams();
103 | $url = $metadata->getUrl();
104 | if ($queryStringArgs !== []) {
105 | $url .= '?' . http_build_query($queryStringArgs);
106 | }
107 |
108 | return new Link('self', $url);
109 | }
110 |
111 | private function stripUrlFragment(string $url): string
112 | {
113 | $fragment = parse_url($url, PHP_URL_FRAGMENT);
114 | if (null === $fragment) {
115 | // parse_url returns null both for absence of fragment and empty fragment
116 | return preg_replace('/#$/', '', $url);
117 | }
118 |
119 | return str_replace('#' . $fragment, '', $url);
120 | }
121 |
122 | private function appendPageQueryToUrl(string $url, int $page, string $paginationParam): string
123 | {
124 | $query = parse_url($url, PHP_URL_QUERY);
125 | if (null === $query) {
126 | // parse_url returns null both for absence of query and empty query
127 | $url = preg_replace('/\?$/', '', $url);
128 | return sprintf('%s?%s=%s', $url, $paginationParam, $page);
129 | }
130 |
131 | parse_str($query, $qsa);
132 | $qsa[$paginationParam] = $page;
133 |
134 | return str_replace('?' . $query, '?' . http_build_query($qsa), $url);
135 | }
136 | }
137 |
--------------------------------------------------------------------------------
/src/ResourceGenerator/UrlBasedResourceStrategy.php:
--------------------------------------------------------------------------------
1 | extractInstance($instance, $metadata, $resourceGenerator, $request, $depth),
34 | [new Link('self', $metadata->getUrl())]
35 | );
36 | }
37 | }
38 |
--------------------------------------------------------------------------------
/src/ResourceGeneratorFactory.php:
--------------------------------------------------------------------------------
1 | get(Metadata\MetadataMap::class),
39 | $container->get(HydratorPluginManager::class),
40 | $container->get($this->linkGeneratorServiceName)
41 | );
42 |
43 | $this->injectStrategies($container, $generator);
44 |
45 | return $generator;
46 | }
47 |
48 | /**
49 | * @throws InvalidConfigException If the config service is not an array or
50 | * ArrayAccess implementation.
51 | * @throws InvalidConfigException If the configured strategies value is not
52 | * an array or traversable.
53 | */
54 | private function injectStrategies(ContainerInterface $container, ResourceGenerator $generator): void
55 | {
56 | if (! $container->has('config')) {
57 | return;
58 | }
59 |
60 | $config = $container->get('config');
61 |
62 | if (! is_array($config) && ! $config instanceof ArrayAccess) {
63 | throw InvalidConfigException::dueToNonArray($config);
64 | }
65 |
66 | if (! isset($config['mezzio-hal']['resource-generator']['strategies'])) {
67 | return;
68 | }
69 |
70 | $strategies = $config['mezzio-hal']['resource-generator']['strategies'];
71 |
72 | if (! is_array($strategies) && ! $strategies instanceof Traversable) {
73 | throw InvalidConfigException::dueToInvalidStrategies($strategies);
74 | }
75 |
76 | foreach ($strategies as $metadataType => $strategy) {
77 | if (! is_string($metadataType) || empty($metadataType)) {
78 | continue;
79 | }
80 |
81 | $generator->addStrategy(
82 | $metadataType,
83 | $container->get($strategy)
84 | );
85 | }
86 | }
87 | }
88 |
--------------------------------------------------------------------------------
/src/ResourceGeneratorInterface.php:
--------------------------------------------------------------------------------
1 | responseFactory = $responseFactory;
25 | }
26 |
27 | public function createResponse(int $code = 200, string $reasonPhrase = ''): ResponseInterface
28 | {
29 | return $this->getResponseFromCallable()->withStatus($code, $reasonPhrase);
30 | }
31 |
32 | public function getResponseFromCallable(): ResponseInterface
33 | {
34 | return ($this->responseFactory)();
35 | }
36 | }
37 |
--------------------------------------------------------------------------------