• Home
  • Features
  • Pricing
  • Docs
  • Announcements
  • Sign In

api-platform / core / 10729306835

05 Sep 2024 10:46PM UTC coverage: 7.655% (-0.01%) from 7.665%
10729306835

push

github

web-flow
Merge pull request #6586 from soyuka/merge-342

Merge 3.4

0 of 54 new or added lines in 12 files covered. (0.0%)

8760 existing lines in 277 files now uncovered.

12505 of 163357 relevant lines covered (7.66%)

22.84 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

91.23
/src/Metadata/ApiProperty.php
1
<?php
2

3
/*
4
 * This file is part of the API Platform project.
5
 *
6
 * (c) Kévin Dunglas <dunglas@gmail.com>
7
 *
8
 * For the full copyright and license information, please view the LICENSE
9
 * file that was distributed with this source code.
10
 */
11

12
declare(strict_types=1);
13

14
namespace ApiPlatform\Metadata;
15

16
use Symfony\Component\PropertyInfo\Type;
17

18
/**
19
 * ApiProperty annotation.
20
 *
21
 * @author Kévin Dunglas <dunglas@gmail.com>
22
 */
23
#[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::TARGET_PARAMETER | \Attribute::TARGET_CLASS_CONSTANT | \Attribute::TARGET_CLASS)]
24
final class ApiProperty
25
{
26
    /**
27
     * @param bool|null               $readableLink            https://api-platform.com/docs/core/serialization/#force-iri-with-relations-of-the-same-type-parentchilds-relations
28
     * @param bool|null               $writableLink            https://api-platform.com/docs/core/serialization/#force-iri-with-relations-of-the-same-type-parentchilds-relations
29
     * @param bool|null               $required                https://api-platform.com/docs/admin/validation/#client-side-validation
30
     * @param bool|null               $identifier              https://api-platform.com/docs/core/identifiers/
31
     * @param mixed                   $example                 https://api-platform.com/docs/core/openapi/#using-the-openapi-and-swagger-contexts
32
     * @param string|null             $deprecationReason       https://api-platform.com/docs/core/deprecations/#deprecating-resource-classes-operations-and-properties
33
     * @param bool|null               $fetchEager              https://api-platform.com/docs/core/performance/#eager-loading
34
     * @param array|null              $jsonldContext           https://api-platform.com/docs/core/extending-jsonld-context/#extending-json-ld-and-hydra-contexts
35
     * @param array|null              $openapiContext          https://api-platform.com/docs/core/openapi/#using-the-openapi-and-swagger-contexts
36
     * @param bool|null               $push                    https://api-platform.com/docs/core/push-relations/
37
     * @param string|\Stringable|null $security                https://api-platform.com/docs/core/security
38
     * @param string|\Stringable|null $securityPostDenormalize https://api-platform.com/docs/core/security/#executing-access-control-rules-after-denormalization
39
     * @param string[]                $types                   the RDF types of this property
40
     * @param string[]                $iris
41
     * @param Type[]                  $builtinTypes
42
     * @param string|null             $uriTemplate             (experimental) whether to return the subRessource collection IRI instead of an iterable of IRI
43
     * @param string|null             $property                The property name
44
     */
45
    public function __construct(
46
        private ?string $description = null,
47
        private ?bool $readable = null,
48
        private ?bool $writable = null,
49
        private ?bool $readableLink = null,
50
        private ?bool $writableLink = null,
51
        private ?bool $required = null,
52
        private ?bool $identifier = null,
53
        private mixed $default = null,
54
        private mixed $example = null,
55
        /**
56
         * The `deprecationReason` option deprecates the current operation with a deprecation message.
57
         *
58
         * <div data-code-selector>
59
         *
60
         * ```php
61
         * <?php
62
         * // api/src/Entity/Review.php
63
         * use ApiPlatform\Metadata\ApiProperty;
64
         * use ApiPlatform\Metadata\ApiResource;
65
         *
66
         * #[ApiResource]
67
         * class Review
68
         * {
69
         *     #[ApiProperty(deprecationReason: "Use the rating property instead")]
70
         *     public string $letter;
71
         * }
72
         * ```
73
         *
74
         * ```yaml
75
         * # api/config/api_platform/properties.yaml
76
         * properties:
77
         *     App\Entity\Review:
78
         *         letter:
79
         *             deprecationReason: 'Create a Book instead'
80
         * ```
81
         *
82
         * ```xml
83
         * <?xml version="1.0" encoding="UTF-8" ?>
84
         * <!-- api/config/api_platform/properties.xml -->
85
         *
86
         * <properties
87
         *         xmlns="https://api-platform.com/schema/metadata/properties-3.0"
88
         *         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
89
         *         xsi:schemaLocation="https://api-platform.com/schema/metadata/properties-3.0
90
         *         https://api-platform.com/schema/metadata/properties-3.0.xsd">
91
         *     <property resource="App\Entity\Review" name="letter" deprecationReason="Create a Book instead" />
92
         * </properties>
93
         * ```
94
         *
95
         * </div>
96
         *
97
         * - With JSON-lD / Hydra, [an `owl:deprecated` annotation property](https://www.w3.org/TR/owl2-syntax/#Annotation_Properties) will be added to the appropriate data structure
98
         * - With Swagger / OpenAPI, [a `deprecated` property](https://swagger.io/docs/specification/2-0/paths-and-operations/) will be added
99
         * - With GraphQL, the [`isDeprecated` and `deprecationReason` properties](https://facebook.github.io/graphql/June2018/#sec-Deprecation) will be added to the schema
100
         */
101
        private ?string $deprecationReason = null,
102
        private ?bool $fetchable = null,
103
        private ?bool $fetchEager = null,
104
        private ?array $jsonldContext = null,
105
        private ?array $openapiContext = null,
106
        private ?array $jsonSchemaContext = null,
107
        private ?bool $push = null,
108
        /**
109
         * The `security` option defines the access to the current property, on normalization process, based on Symfony Security.
110
         * It receives an `object` variable related to the current object, and a `property` variable related to the current property.
111
         *
112
         * <div data-code-selector>
113
         *
114
         * ```php
115
         * <?php
116
         * // api/src/Entity/Review.php
117
         * use ApiPlatform\Metadata\ApiProperty;
118
         * use ApiPlatform\Metadata\ApiResource;
119
         *
120
         * #[ApiResource]
121
         * class Review
122
         * {
123
         *     #[ApiProperty(security: 'is_granted("ROLE_ADMIN")')]
124
         *     public string $letter;
125
         * }
126
         * ```
127
         *
128
         * ```yaml
129
         * # api/config/api_platform/properties.yaml
130
         * properties:
131
         *     App\Entity\Review:
132
         *         letter:
133
         *             security: 'is_granted("ROLE_ADMIN")'
134
         * ```
135
         *
136
         * ```xml
137
         * <?xml version="1.0" encoding="UTF-8" ?>
138
         * <!-- api/config/api_platform/properties.xml -->
139
         *
140
         * <properties
141
         *         xmlns="https://api-platform.com/schema/metadata/properties-3.0"
142
         *         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
143
         *         xsi:schemaLocation="https://api-platform.com/schema/metadata/properties-3.0
144
         *         https://api-platform.com/schema/metadata/properties-3.0.xsd">
145
         *     <property resource="App\Entity\Review" name="letter" security="is_granted('ROLE_ADMIN')" />
146
         * </properties>
147
         * ```
148
         *
149
         * </div>
150
         */
151
        private string|\Stringable|null $security = null,
152
        /**
153
         * The `securityPostDenormalize` option defines access to the current property after the denormalization process, based on Symfony Security.
154
         * It receives an `object` variable related to the current object, and a `property` variable related to the current property.
155
         *
156
         * <div data-code-selector>
157
         *
158
         * ```php
159
         * <?php
160
         * // api/src/Entity/Review.php
161
         * use ApiPlatform\Metadata\ApiProperty;
162
         * use ApiPlatform\Metadata\ApiResource;
163
         *
164
         * #[ApiResource]
165
         * class Review
166
         * {
167
         *     #[ApiProperty(securityPostDenormalize: 'is_granted("ROLE_ADMIN")')]
168
         *     public string $letter;
169
         * }
170
         * ```
171
         *
172
         * ```yaml
173
         * # api/config/api_platform/properties.yaml
174
         * properties:
175
         *     App\Entity\Review:
176
         *         letter:
177
         *             securityPostDenormalize: 'is_granted("ROLE_ADMIN")'
178
         * ```
179
         *
180
         * ```xml
181
         * <?xml version="1.0" encoding="UTF-8" ?>
182
         * <!-- api/config/api_platform/properties.xml -->
183
         *
184
         * <properties
185
         *         xmlns="https://api-platform.com/schema/metadata/properties-3.0"
186
         *         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
187
         *         xsi:schemaLocation="https://api-platform.com/schema/metadata/properties-3.0
188
         *         https://api-platform.com/schema/metadata/properties-3.0.xsd">
189
         *     <property resource="App\Entity\Review" name="letter" securityPostDenormalize="is_granted('ROLE_ADMIN')" />
190
         * </properties>
191
         * ```
192
         *
193
         * </div>
194
         */
195
        private string|\Stringable|null $securityPostDenormalize = null,
196
        private array|string|null $types = null,
197
        /*
198
         * The related php types.
199
         */
200
        private ?array $builtinTypes = null,
201
        private ?array $schema = null,
202
        private ?bool $initializable = null,
203
        private $iris = null,
204
        private ?bool $genId = null,
205
        private ?string $uriTemplate = null,
206
        private ?string $property = null,
207
        private ?string $policy = null,
208
        private array $extraProperties = [],
209
    ) {
UNCOV
210
        if (\is_string($types)) {
529✔
211
            $this->types = (array) $types;
×
212
        }
213
    }
214

215
    public function getProperty(): ?string
216
    {
UNCOV
217
        return $this->property;
142✔
218
    }
219

220
    public function withProperty(string $property): self
221
    {
222
        $self = clone $this;
×
223
        $self->property = $property;
×
224

225
        return $self;
×
226
    }
227

228
    public function getDescription(): ?string
229
    {
UNCOV
230
        return $this->description;
848✔
231
    }
232

233
    public function withDescription(string $description): self
234
    {
UNCOV
235
        $self = clone $this;
184✔
UNCOV
236
        $self->description = $description;
184✔
237

UNCOV
238
        return $self;
184✔
239
    }
240

241
    public function isReadable(): ?bool
242
    {
UNCOV
243
        return $this->readable;
2,056✔
244
    }
245

246
    public function withReadable(bool $readable): self
247
    {
UNCOV
248
        $self = clone $this;
529✔
UNCOV
249
        $self->readable = $readable;
529✔
250

UNCOV
251
        return $self;
529✔
252
    }
253

254
    public function isWritable(): ?bool
255
    {
UNCOV
256
        return $this->writable;
1,116✔
257
    }
258

259
    public function withWritable(bool $writable): self
260
    {
UNCOV
261
        $self = clone $this;
529✔
UNCOV
262
        $self->writable = $writable;
529✔
263

UNCOV
264
        return $self;
529✔
265
    }
266

267
    public function isReadableLink(): ?bool
268
    {
UNCOV
269
        return $this->readableLink;
875✔
270
    }
271

272
    public function withReadableLink(bool $readableLink): self
273
    {
UNCOV
274
        $self = clone $this;
230✔
UNCOV
275
        $self->readableLink = $readableLink;
230✔
276

UNCOV
277
        return $self;
230✔
278
    }
279

280
    public function isWritableLink(): ?bool
281
    {
UNCOV
282
        return $this->writableLink;
378✔
283
    }
284

285
    public function withWritableLink(bool $writableLink): self
286
    {
UNCOV
287
        $self = clone $this;
230✔
UNCOV
288
        $self->writableLink = $writableLink;
230✔
289

UNCOV
290
        return $self;
230✔
291
    }
292

293
    public function isRequired(): ?bool
294
    {
UNCOV
295
        return $this->required;
799✔
296
    }
297

298
    public function withRequired(bool $required): self
299
    {
UNCOV
300
        $self = clone $this;
529✔
UNCOV
301
        $self->required = $required;
529✔
302

UNCOV
303
        return $self;
529✔
304
    }
305

306
    public function isIdentifier(): ?bool
307
    {
UNCOV
308
        return $this->identifier;
589✔
309
    }
310

311
    public function withIdentifier(bool $identifier): self
312
    {
UNCOV
313
        $self = clone $this;
432✔
UNCOV
314
        $self->identifier = $identifier;
432✔
315

UNCOV
316
        return $self;
432✔
317
    }
318

319
    public function getDefault()
320
    {
UNCOV
321
        return $this->default;
532✔
322
    }
323

324
    public function withDefault($default): self
325
    {
UNCOV
326
        $self = clone $this;
226✔
UNCOV
327
        $self->default = $default;
226✔
328

UNCOV
329
        return $self;
226✔
330
    }
331

332
    public function getExample(): mixed
333
    {
UNCOV
334
        return $this->example;
529✔
335
    }
336

337
    public function withExample(mixed $example): self
338
    {
UNCOV
339
        $self = clone $this;
9✔
UNCOV
340
        $self->example = $example;
9✔
341

UNCOV
342
        return $self;
9✔
343
    }
344

345
    public function getDeprecationReason(): ?string
346
    {
UNCOV
347
        return $this->deprecationReason;
848✔
348
    }
349

350
    public function withDeprecationReason($deprecationReason): self
351
    {
UNCOV
352
        $self = clone $this;
27✔
UNCOV
353
        $self->deprecationReason = $deprecationReason;
27✔
354

UNCOV
355
        return $self;
27✔
356
    }
357

358
    public function isFetchable(): ?bool
359
    {
UNCOV
360
        return $this->fetchable;
142✔
361
    }
362

363
    public function withFetchable($fetchable): self
364
    {
365
        $self = clone $this;
×
366
        $self->fetchable = $fetchable;
×
367

368
        return $self;
×
369
    }
370

371
    public function getFetchEager(): ?bool
372
    {
UNCOV
373
        return $this->fetchEager;
269✔
374
    }
375

376
    public function withFetchEager($fetchEager): self
377
    {
UNCOV
378
        $self = clone $this;
4✔
UNCOV
379
        $self->fetchEager = $fetchEager;
4✔
380

UNCOV
381
        return $self;
4✔
382
    }
383

384
    public function getJsonldContext(): ?array
385
    {
UNCOV
386
        return $this->jsonldContext;
250✔
387
    }
388

389
    public function withJsonldContext($jsonldContext): self
390
    {
UNCOV
391
        $self = clone $this;
9✔
UNCOV
392
        $self->jsonldContext = $jsonldContext;
9✔
393

UNCOV
394
        return $self;
9✔
395
    }
396

397
    public function getOpenapiContext(): ?array
398
    {
UNCOV
399
        return $this->openapiContext;
514✔
400
    }
401

402
    public function withOpenapiContext($openapiContext): self
403
    {
UNCOV
404
        $self = clone $this;
9✔
UNCOV
405
        $self->openapiContext = $openapiContext;
9✔
406

UNCOV
407
        return $self;
9✔
408
    }
409

410
    public function getJsonSchemaContext(): ?array
411
    {
UNCOV
412
        return $this->jsonSchemaContext;
142✔
413
    }
414

415
    public function withJsonSchemaContext($jsonSchemaContext): self
416
    {
UNCOV
417
        $self = clone $this;
9✔
UNCOV
418
        $self->jsonSchemaContext = $jsonSchemaContext;
9✔
419

UNCOV
420
        return $self;
9✔
421
    }
422

423
    public function getPush(): ?bool
424
    {
UNCOV
425
        return $this->push;
356✔
426
    }
427

428
    public function withPush($push): self
429
    {
UNCOV
430
        $self = clone $this;
8✔
UNCOV
431
        $self->push = $push;
8✔
432

UNCOV
433
        return $self;
8✔
434
    }
435

436
    public function getSecurity(): ?string
437
    {
UNCOV
438
        return $this->security instanceof \Stringable ? (string) $this->security : $this->security;
1,993✔
439
    }
440

441
    public function withSecurity($security): self
442
    {
UNCOV
443
        $self = clone $this;
15✔
UNCOV
444
        $self->security = $security;
15✔
445

UNCOV
446
        return $self;
15✔
447
    }
448

449
    public function getSecurityPostDenormalize(): ?string
450
    {
UNCOV
451
        return $this->securityPostDenormalize instanceof \Stringable ? (string) $this->securityPostDenormalize : $this->securityPostDenormalize;
660✔
452
    }
453

454
    public function withSecurityPostDenormalize($securityPostDenormalize): self
455
    {
UNCOV
456
        $self = clone $this;
17✔
UNCOV
457
        $self->securityPostDenormalize = $securityPostDenormalize;
17✔
458

UNCOV
459
        return $self;
17✔
460
    }
461

462
    public function getTypes(): ?array
463
    {
UNCOV
464
        return $this->types;
529✔
465
    }
466

467
    /**
468
     * @param string[]|string $types
469
     */
470
    public function withTypes(array|string $types = []): self
471
    {
UNCOV
472
        $self = clone $this;
67✔
UNCOV
473
        $self->types = (array) $types;
67✔
474

UNCOV
475
        return $self;
67✔
476
    }
477

478
    /**
479
     * @return Type[]
480
     */
481
    public function getBuiltinTypes(): ?array
482
    {
UNCOV
483
        return $this->builtinTypes;
2,105✔
484
    }
485

486
    /**
487
     * @param Type[] $builtinTypes
488
     */
489
    public function withBuiltinTypes(array $builtinTypes = []): self
490
    {
UNCOV
491
        $self = clone $this;
529✔
UNCOV
492
        $self->builtinTypes = $builtinTypes;
529✔
493

UNCOV
494
        return $self;
529✔
495
    }
496

497
    public function getSchema(): ?array
498
    {
UNCOV
499
        return $this->schema;
562✔
500
    }
501

502
    public function withSchema(array $schema = []): self
503
    {
UNCOV
504
        $self = clone $this;
529✔
UNCOV
505
        $self->schema = $schema;
529✔
506

UNCOV
507
        return $self;
529✔
508
    }
509

510
    public function withInitializable(?bool $initializable): self
511
    {
UNCOV
512
        $self = clone $this;
529✔
UNCOV
513
        $self->initializable = $initializable;
529✔
514

UNCOV
515
        return $self;
529✔
516
    }
517

518
    public function isInitializable(): ?bool
519
    {
UNCOV
520
        return $this->initializable;
949✔
521
    }
522

523
    public function getExtraProperties(): ?array
524
    {
UNCOV
525
        return $this->extraProperties;
575✔
526
    }
527

528
    public function withExtraProperties(array $extraProperties = []): self
529
    {
UNCOV
530
        $self = clone $this;
142✔
UNCOV
531
        $self->extraProperties = $extraProperties;
142✔
532

UNCOV
533
        return $self;
142✔
534
    }
535

536
    /**
537
     * Gets IRI of this property.
538
     */
539
    public function getIris()
540
    {
UNCOV
541
        return $this->iris;
250✔
542
    }
543

544
    /**
545
     * Returns a new instance with the given IRI.
546
     *
547
     * @param string|string[] $iris
548
     */
549
    public function withIris(string|array $iris): self
550
    {
UNCOV
551
        $metadata = clone $this;
23✔
UNCOV
552
        $metadata->iris = (array) $iris;
23✔
553

UNCOV
554
        return $metadata;
23✔
555
    }
556

557
    /**
558
     * Whether to generate a skolem iri on anonymous resources.
559
     */
560
    public function getGenId()
561
    {
UNCOV
562
        return $this->genId;
889✔
563
    }
564

565
    public function withGenId(bool $genId): self
566
    {
UNCOV
567
        $metadata = clone $this;
10✔
UNCOV
568
        $metadata->genId = $genId;
10✔
569

UNCOV
570
        return $metadata;
10✔
571
    }
572

573
    /**
574
     * Whether to return the subRessource collection IRI instead of an iterable of IRI.
575
     *
576
     * @experimental
577
     */
578
    public function getUriTemplate(): ?string
579
    {
UNCOV
580
        return $this->uriTemplate;
1,255✔
581
    }
582

583
    public function withUriTemplate(?string $uriTemplate): self
584
    {
UNCOV
585
        $metadata = clone $this;
15✔
UNCOV
586
        $metadata->uriTemplate = $uriTemplate;
15✔
587

UNCOV
588
        return $metadata;
15✔
589
    }
590

591
    public function getPolicy(): ?string
592
    {
UNCOV
593
        return $this->policy;
1,895✔
594
    }
595

596
    public function withPolicy(?string $policy): static
597
    {
598
        $self = clone $this;
×
599
        $self->policy = $policy;
×
600

601
        return $self;
×
602
    }
603
}
STATUS · Troubleshooting · Open an Issue · Sales · Support · CAREERS · ENTERPRISE · START FREE · SCHEDULE DEMO
ANNOUNCEMENTS · TWITTER · TOS & SLA · Supported CI Services · What's a CI service? · Automated Testing

© 2025 Coveralls, Inc