ArrayOf.php
2 months ago
ConnectionOf.php
2 months ago
Deprecated.php
2 months ago
Description.php
2 months ago
Experimental.php
4 weeks ago
HiddenFromMetadataQuery.php
4 weeks ago
Ignore.php
2 months ago
Internal.php
4 weeks ago
Metadata.php
4 weeks ago
Name.php
2 months ago
Parameter.php
2 months ago
ParameterDescription.php
2 months ago
PublicAccess.php
4 weeks ago
RequiredCapability.php
4 weeks ago
ReturnType.php
2 months ago
ScalarType.php
2 months ago
Unroll.php
2 months ago
Experimental.php
54 lines
| 1 | <?php |
| 2 | |
| 3 | declare(strict_types=1); |
| 4 | |
| 5 | namespace Automattic\WooCommerce\Api\Attributes; |
| 6 | |
| 7 | use Attribute; |
| 8 | |
| 9 | /** |
| 10 | * Marks a code-API element as experimental: present in the schema, but not |
| 11 | * stable enough to be relied on in production. |
| 12 | * |
| 13 | * Discoverable through the `_apiMetadata` GraphQL field as an entry with |
| 14 | * `name = "experimental"` and `value = true`. The marking is informational: |
| 15 | * it does not gate access in any way. |
| 16 | * |
| 17 | * When a class, property or enum case has this attribute, the generated |
| 18 | * GraphQL `description` is prefixed with `[Experimental] `, and |
| 19 | * when the element has no `#[Description]` at all, a default body |
| 20 | * (`[Experimental] Not to be used in production environments.`) is emitted |
| 21 | * so the marker still reaches stock introspection. |
| 22 | * |
| 23 | * `#[Experimental]` on a class marks only that class: its fields and enum |
| 24 | * cases are not implicitly marked too. A tool that wants to treat the |
| 25 | * contents of an experimental type as experimental by association must |
| 26 | * apply that rule itself when it reads the metadata. |
| 27 | * |
| 28 | * The attribute targets classes, properties, and enum cases; see |
| 29 | * {@see Metadata} for the reasoning behind excluding methods. |
| 30 | */ |
| 31 | #[Attribute( Attribute::TARGET_CLASS | Attribute::TARGET_PROPERTY | Attribute::TARGET_CLASS_CONSTANT )] |
| 32 | class Experimental extends Metadata { |
| 33 | /** |
| 34 | * Construct an `experimental` metadata entry with value `true`. |
| 35 | */ |
| 36 | public function __construct() { |
| 37 | parent::__construct( 'experimental', true ); |
| 38 | } |
| 39 | |
| 40 | /** |
| 41 | * Prepend `[Experimental] ` to the description, supplying a default body |
| 42 | * when the element has no `#[Description]` of its own. See |
| 43 | * {@see Metadata::transform_description()} for the contract. |
| 44 | * |
| 45 | * @param string $description Incoming description (empty when no `#[Description]`). |
| 46 | */ |
| 47 | public function transform_description( string $description ): string { |
| 48 | if ( '' === $description ) { |
| 49 | $description = 'Not to be used in production environments.'; |
| 50 | } |
| 51 | return '[Experimental] ' . $description; |
| 52 | } |
| 53 | } |
| 54 |