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

api-platform / core / 10027319583

21 Jul 2024 09:36AM UTC coverage: 7.847%. Remained the same
10027319583

push

github

web-flow
ci: fix naming of Windows Behat matrix line (#6489)

12688 of 161690 relevant lines covered (7.85%)

26.88 hits per line

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

93.64
/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 array $extraProperties = [],
208
    ) {
209
        if (\is_string($types)) {
832✔
210
            $this->types = (array) $types;
×
211
        }
212
    }
213

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

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

224
        return $self;
×
225
    }
226

227
    public function getDescription(): ?string
228
    {
229
        return $this->description;
1,004✔
230
    }
231

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

237
        return $self;
283✔
238
    }
239

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

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

250
        return $self;
736✔
251
    }
252

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

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

263
        return $self;
727✔
264
    }
265

266
    public function isReadableLink(): ?bool
267
    {
268
        return $this->readableLink;
1,052✔
269
    }
270

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

276
        return $self;
305✔
277
    }
278

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

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

289
        return $self;
302✔
290
    }
291

292
    public function isRequired(): ?bool
293
    {
294
        return $this->required;
1,129✔
295
    }
296

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

302
        return $self;
811✔
303
    }
304

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

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

315
        return $self;
540✔
316
    }
317

318
    public function getDefault()
319
    {
320
        return $this->default;
676✔
321
    }
322

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

328
        return $self;
328✔
329
    }
330

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

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

341
        return $self;
12✔
342
    }
343

344
    public function getDeprecationReason(): ?string
345
    {
346
        return $this->deprecationReason;
1,004✔
347
    }
348

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

354
        return $self;
39✔
355
    }
356

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

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

367
        return $self;
×
368
    }
369

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

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

380
        return $self;
4✔
381
    }
382

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

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

393
        return $self;
21✔
394
    }
395

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

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

406
        return $self;
15✔
407
    }
408

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

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

419
        return $self;
24✔
420
    }
421

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

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

432
        return $self;
14✔
433
    }
434

435
    public function getSecurity(): ?string
436
    {
437
        return $this->security instanceof \Stringable ? (string) $this->security : $this->security;
2,308✔
438
    }
439

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

445
        return $self;
18✔
446
    }
447

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

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

458
        return $self;
20✔
459
    }
460

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

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

474
        return $self;
100✔
475
    }
476

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

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

493
        return $self;
757✔
494
    }
495

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

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

506
        return $self;
787✔
507
    }
508

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

514
        return $self;
673✔
515
    }
516

517
    public function isInitializable(): ?bool
518
    {
519
        return $this->initializable;
1,102✔
520
    }
521

522
    public function getExtraProperties(): ?array
523
    {
524
        return $this->extraProperties;
1,028✔
525
    }
526

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

532
        return $self;
205✔
533
    }
534

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

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

553
        return $metadata;
41✔
554
    }
555

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

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

569
        return $metadata;
13✔
570
    }
571

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

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

587
        return $metadata;
15✔
588
    }
589
}
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

© 2026 Coveralls, Inc