From bc6bbab6d911a3b3ce1e152fe1715dbf1ba72664 Mon Sep 17 00:00:00 2001 From: soyuka Date: Mon, 18 Dec 2023 21:48:16 +0100 Subject: [PATCH] fix: use html for code-selector --- core/content-negotiation.md | 4 +-- core/controllers.md | 16 ++++----- core/data-providers.md | 4 +-- core/default-order.md | 16 ++++----- core/deprecations.md | 4 +-- core/dto.md | 8 ++--- core/extending-jsonld-context.md | 4 +-- core/filters.md | 60 ++++++++++++++++---------------- core/getting-started.md | 4 +-- core/graphql.md | 4 +-- core/identifiers.md | 8 ++--- core/messenger.md | 4 +-- core/openapi.md | 8 ++--- core/operations.md | 24 ++++++------- core/security.md | 20 +++++------ core/serialization.md | 40 ++++++++++----------- core/subresources.md | 8 ++--- core/url-generation-strategy.md | 4 +-- 18 files changed, 120 insertions(+), 120 deletions(-) diff --git a/core/content-negotiation.md b/core/content-negotiation.md index e505b0b0960..e17d732275b 100644 --- a/core/content-negotiation.md +++ b/core/content-negotiation.md @@ -122,7 +122,7 @@ this configuration might disable the `json` or the `html` on this resource for e You can specify different accepted formats at operation level too, it's especially convenient for to configure formats available for the `PATCH` method: -[codeSelector] + ```php ``` -[/codeSelector] + ## Supporting Custom Formats diff --git a/core/controllers.md b/core/controllers.md index 75620cbd237..93a73cd6b6f 100644 --- a/core/controllers.md +++ b/core/controllers.md @@ -82,7 +82,7 @@ the client. The routing has not been configured yet because we will add it at the resource configuration level: -[codeSelector] + ```php ``` -[/codeSelector] + It is mandatory to set the `method`, `path` and `controller` attributes. They allow API Platform to configure the routing path and the associated controller respectively. @@ -147,7 +147,7 @@ the associated controller respectively. You may want different serialization groups for your custom operations. Just configure the proper `normalization_context` and/or `denormalization_context` in your operation: -[codeSelector] + ```php ``` -[/codeSelector] + ## Retrieving the Entity If you want to bypass the automatic retrieval of the entity in your custom operation, you can set `"read"=false` in the operation attribute: -[codeSelector] + ```php ``` -[/codeSelector] + This way, it will skip the `ReadListener`. You can do the same for some other built-in listeners. See [Built-in Event Listeners](events.md#built-in-event-listeners) for more information. @@ -301,7 +301,7 @@ for `book_post_discontinuation` when neither `method` nor `route_name` attribute First, let's create your resource configuration: -[codeSelector] + ```php ``` -[/codeSelector] + API Platform will automatically map this `post_publication` operation to the route `book_post_publication`. Let's create a custom action and its related route using annotations: diff --git a/core/data-providers.md b/core/data-providers.md index bf08d623820..5377c0bc5d6 100644 --- a/core/data-providers.md +++ b/core/data-providers.md @@ -215,7 +215,7 @@ API Platform provides a few extensions that you can reuse in your custom DataPro Note that there are a few kinds of extensions which are detailed in [their own chapter of the documentation](extensions.md). Because extensions are tagged services, you can use the [injection of tagged services](https://symfony.com/blog/new-in-symfony-3-4-simpler-injection-of-tagged-services): -[codeSelector] + ```yaml services: @@ -232,7 +232,7 @@ services: ``` -[/codeSelector] + Your data provider will now have access to the core extensions, here is an example on how to use them: diff --git a/core/default-order.md b/core/default-order.md index b47a8c1cb8b..a5df6ad574a 100644 --- a/core/default-order.md +++ b/core/default-order.md @@ -5,7 +5,7 @@ API Platform Core provides an easy way to override the default order of items in By default, items in the collection are ordered in ascending (ASC) order by their resource identifier(s). If you want to customize this order, you must add an `order` attribute on your ApiResource annotation: -[codeSelector] + ```php This `order` attribute is used as an array: the key defines the order field, the values defines the direction. If you only specify the key, `ASC` direction will be used as default. For example, to order by `foo` & `bar`: -[codeSelector] + ```php It's also possible to configure the default order on an association property: -[codeSelector] + ```php Another possibility is to apply the default order for a specific collection operation, which will override the global default order configuration. -[codeSelector] + ```php #[ApiResource( @@ -161,4 +161,4 @@ App\Entity\Book: name: ASC ``` -[/codeSelector] + diff --git a/core/deprecations.md b/core/deprecations.md index da03d33e32d..92f7fe802cb 100644 --- a/core/deprecations.md +++ b/core/deprecations.md @@ -67,7 +67,7 @@ class Parchment It's also possible to deprecate a single property: -[codeSelector] + ```php * 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 * With Swagger / OpenAPI, [a `deprecated` property](https://swagger.io/docs/specification/2-0/paths-and-operations/) will be added diff --git a/core/dto.md b/core/dto.md index 739e1df9a58..504449365e8 100644 --- a/core/dto.md +++ b/core/dto.md @@ -9,7 +9,7 @@ However, it's sometimes useful to use a specific class to represent the input or For a given resource class, you may want to have a different representation of this class as input (write) or output (read). To do so, a resource can take an input and/or an output class: -[codeSelector] + ```php ``` -[/codeSelector] + The `input` attribute is used during [the deserialization process](serialization.md), when transforming the user-provided data to a resource instance. Similarly, the `output` attribute is used during [the serialization process](serialization.md). This class represents how the `Book` resource will be represented in the `Response`. @@ -357,7 +357,7 @@ will be skipped. If `output` is `false`, the serialization process will be skipp `input` and `output` attributes can be set on a per operation basis: -[codeSelector] + ```php ``` -[/codeSelector] + ## Input/Output Metadata diff --git a/core/extending-jsonld-context.md b/core/extending-jsonld-context.md index d6d56a967c0..41b944021ca 100644 --- a/core/extending-jsonld-context.md +++ b/core/extending-jsonld-context.md @@ -70,7 +70,7 @@ Note that you do not have to provide the `@id` attribute. If you do not provide It's also possible to replace the Hydra context used by the documentation generator: -[codeSelector] + ```php ``` -[/codeSelector] + diff --git a/core/filters.md b/core/filters.md index 1cc31e986fb..77aa1e6b60d 100644 --- a/core/filters.md +++ b/core/filters.md @@ -42,7 +42,7 @@ to a Resource in two ways: We're linking the filter `offer.date_filter` with the resource like this: - [codeSelector] + ```php ``` - [/codeSelector] + 2. By using the `#[ApiFilter]` attribute. @@ -145,7 +145,7 @@ Syntax: `?property[]=foo&property[]=bar` In the following example, we will see how to allow the filtering of a list of e-commerce offers: -[codeSelector] + ```php `http://localhost:8000/api/offers?price=10` will return all offers with a price being exactly `10`. `http://localhost:8000/api/offers?description=shirt` will return all offers with a description containing the word "shirt". @@ -195,7 +195,7 @@ Filters can be combined together: `http://localhost:8000/api/offers?price=10&des It is possible to filter on relations too, if `Offer` has a `Product` relation: -[codeSelector] + ```php With this service definition, it is possible to find all offers belonging to the product identified by a given IRI. Try the following: `http://localhost:8000/api/offers?product=/api/products/12`. @@ -256,7 +256,7 @@ The `after` and `before` filters will filter including the value whereas `strict Like others filters, the date filter must be explicitly enabled: -[codeSelector] + ```php Given that the collection endpoint is `/offers`, you can filter offers by date with the following query: `/offers?createdAt[after]=2018-03-19`. @@ -317,7 +317,7 @@ Always include items | `ApiPlatform\Core\Bridge\Doctrine\Orm\Fil For instance, exclude entries with a property value of `null` with the following service definition: -[codeSelector] + ```php ### Boolean Filter @@ -368,7 +368,7 @@ Syntax: `?property=` Enable the filter: -[codeSelector] + ```php Given that the collection endpoint is `/offers`, you can filter offers with the following query: `/offers?isAvailableGenericallyInMyCountry=true`. @@ -423,7 +423,7 @@ Syntax: `?property=` Enable the filter: -[codeSelector] + ```php Given that the collection endpoint is `/offers`, you can filter offers with the following query: `/offers?sold=1`. @@ -478,7 +478,7 @@ Syntax: `?property[]=value` Enable the filter: -[codeSelector] + ```php Given that the collection endpoint is `/offers`, you can filter the price with the following query: `/offers?price[between]=12.99..15.99`. @@ -538,7 +538,7 @@ Previous syntax (deprecated): `?property[exists]=` Enable the filter: -[codeSelector] + ```php Given that the collection endpoint is `/offers`, you can filter offers on nullable field with the following query: `/offers?exists[transportFees]=true`. @@ -605,7 +605,7 @@ Syntax: `?order[property]=` Enable the filter: -[codeSelector] + ```php Given that the collection endpoint is `/offers`, you can filter offers by name in ascending order and then by ID in descending order with the following query: `/offers?order[name]=desc&order[id]=asc`. @@ -656,7 +656,7 @@ order with the following query: `/offers?order[name]=desc&order[id]=asc`. By default, whenever the query does not specify the direction explicitly (e.g.: `/offers?order[name]&order[id]`), filters will not be applied unless you configure a default order direction to use: -[codeSelector] + ```php #### Comparing with Null Values @@ -712,7 +712,7 @@ Consider items as largest | `ApiPlatform\Core\Bridge\Doctrine\Orm\Fil For instance, treat entries with a property value of `null` as the smallest, with the following service definition: -[codeSelector] + ```php #### Using a Custom Order Query Parameter Name @@ -772,7 +772,7 @@ api_platform: Sometimes, you need to be able to perform filtering based on some linked resources (on the other side of a relation). All built-in filters support nested properties using the dot (`.`) syntax, e.g.: -[codeSelector] + ```php The above allows you to find offers by their respective product's color: `http://localhost:8000/api/offers?product.color=red`, or order offers by the product's release date: `http://localhost:8000/api/offers?order[product.releaseDate]=desc` @@ -835,7 +835,7 @@ As we have seen in previous examples, properties where filters can be applied mu care about security and performance (e.g. an API with restricted access), it is also possible to enable built-in filters for all properties: -[codeSelector] + ```php **Note: Filters on nested properties must still be enabled explicitly, in order to keep things sane.** @@ -902,7 +902,7 @@ Syntax: `?order[property]=` Enable the filter: -[codeSelector] + ```php Given that the collection endpoint is `/tweets`, you can filter tweets by id and date in ascending or descending order: `/tweets?order[id]=asc&order[date]=desc`. diff --git a/core/getting-started.md b/core/getting-started.md index 0bac68320ec..504f12d9e0d 100644 --- a/core/getting-started.md +++ b/core/getting-started.md @@ -166,7 +166,7 @@ It is also possible to override the naming convention using [operation path nami As an alternative to annotations, you can map entity classes using YAML or XML: -[codeSelector] + ```yaml # api/config/api_platform/resources.yaml @@ -198,7 +198,7 @@ resources: ``` -[/codeSelector] + If you prefer to use YAML or XML files instead of annotations, you must configure API Platform to load the appropriate files: diff --git a/core/graphql.md b/core/graphql.md index bc51d5b3766..1d93c98402b 100644 --- a/core/graphql.md +++ b/core/graphql.md @@ -1249,7 +1249,7 @@ final class ErrorHandler implements ErrorHandlerInterface Then register the service: -[codeSelector] + ```yaml # api/config/services.yaml @@ -1291,7 +1291,7 @@ return function(ContainerConfigurator $configurator) { }; ``` -[/codeSelector] + ### Formatting Exceptions and Errors diff --git a/core/identifiers.md b/core/identifiers.md index bbc7d82c156..27b8f7b52af 100644 --- a/core/identifiers.md +++ b/core/identifiers.md @@ -9,7 +9,7 @@ To help with your development experience, we introduced an identifier normalizat Let's say you have the following class, which is identified by a `UUID` type. In this example, `UUID` is not a simple string but an object with many attributes. -[codeSelector] + ```php ``` -[/codeSelector] + Once registered as an `ApiResource`, having an existing person, it will be accessible through the following URL: `/people/110e8400-e29b-11d4-a716-446655440000`. Note that the property identifying our resource is named `code`. @@ -123,7 +123,7 @@ final class UuidNormalizer implements DenormalizerInterface Tag this service as an `api_platform.identifier.denormalizer`: -[codeSelector] + ```yaml services: @@ -138,7 +138,7 @@ services: ``` -[/codeSelector] + Your `PersonDataProvider` will now work as expected! diff --git a/core/messenger.md b/core/messenger.md index 6c9e475ff5d..36460835882 100644 --- a/core/messenger.md +++ b/core/messenger.md @@ -20,7 +20,7 @@ docker-compose exec php \ Set the `messenger` attribute to `true`, and API Platform will automatically dispatch the API Resource instance as a message using the message bus provided by the Messenger Component. The following example allows you to create a new `Person` in an asynchronous manner: -[codeSelector] + ```php Because the `messenger` attribute is `true`, when a `POST` is handled by API Platform, the corresponding instance of the `Person` will be dispatched. diff --git a/core/openapi.md b/core/openapi.md index b4979420df1..3133b3d2a50 100644 --- a/core/openapi.md +++ b/core/openapi.md @@ -109,7 +109,7 @@ The impact on the swagger-ui is the following: Sometimes you may want to change the information included in your OpenAPI documentation. The following configuration will give you total control over your OpenAPI definitions: -[codeSelector] + ```php ``` -[/codeSelector] + This will produce the following Swagger documentation: @@ -293,7 +293,7 @@ class User You also have full control over both built-in and custom operations documentation. -[codeSelector] + ```php ``` -[/codeSelector] + ![Impact on Swagger UI](../distribution/images/swagger-ui-2.png) diff --git a/core/operations.md b/core/operations.md index a044c33b5af..2ae06575c8f 100644 --- a/core/operations.md +++ b/core/operations.md @@ -68,7 +68,7 @@ empty list of operations is provided, all operations are disabled. If the operation's name matches a supported HTTP methods (`GET`, `POST`, `PUT`, `PATCH` or `DELETE`), the corresponding `method` property will be automatically added. -[codeSelector] + ```php ``` -[/codeSelector] + The previous example can also be written with an explicit method definition: -[codeSelector] + ```php ``` -[/codeSelector] + API Platform Core is smart enough to automatically register the applicable Symfony route referencing a built-in CRUD action just by specifying the method name as key, or by checking the explicitly configured HTTP method. If you do not want to allow access to the resource item (i.e. you don't want a `GET` item operation), instead of omitting it altogether, you should instead declare a `GET` item operation which returns HTTP 404 (Not Found), so that the resource item can still be identified by an IRI. For example: -[codeSelector] + ```php ``` -[/codeSelector] + ## Configuring Operations @@ -255,7 +255,7 @@ The URL, the method and the default status code (among other options) can be con In the next example, both `GET` and `POST` operations are registered with custom URLs. Those will override the URLs generated by default. In addition to that, we require the `id` parameter in the URL of the `GET` operation to be an integer, and we configure the status code generated after successful `POST` request to be `301`: -[codeSelector] + ```php ``` -[/codeSelector] + In all these examples, the `method` attribute is omitted because it matches the operation name. When specifying sub options, you must always use snake case as demonstrated below with the `denormalization_context` option on the `put` operation: -[codeSelector] + ```php ``` -[/codeSelector] + ## Prefixing All Routes of All Operations @@ -440,7 +440,7 @@ Sometimes it's also useful to put a whole resource into its own "namespace" rega put everything that's related to a `Book` into the `library` so that URIs become `library/book/{id}`. In that case you don't need to override all the operations to set the path but configure the `route_prefix` attribute for the whole entity instead: -[codeSelector] + ```php ``` -[/codeSelector] + Alternatively, the more verbose attribute syntax can be used: `#[ApiResource(attributes: ["route_prefix" => "/library"])]`. diff --git a/core/security.md b/core/security.md index 5632de660bd..a09e8981226 100644 --- a/core/security.md +++ b/core/security.md @@ -6,7 +6,7 @@ API Platform also provides convenient [access control expressions](https://symfo

Security screencast
Watch the Security screencast

-[codeSelector] + ```php Resource signature can be modified at the property level as well: -[codeSelector] + ```php class Book @@ -91,7 +91,7 @@ App\Entity\Book: security: 'is_granted("ROLE_ADMIN")' ``` -[/codeSelector] + In this example: @@ -113,7 +113,7 @@ It means than for `PUT` or `PATCH` requests, `object` doesn't contain the value In some cases, it might be useful to execute a security after the denormalization step. To do so, use the `security_post_denormalize` attribute: -[codeSelector] + ```php This time, the `object` variable contains data that have been extracted from the HTTP request body during the denormalization process. However, the object is not persisted yet. @@ -164,7 +164,7 @@ In order to give the current `object` to your voter, use the expression `is_gran For example: -[codeSelector] + ```php Please note that if you use both `attributes={"security"="..` and then `"post" = { "security_post_denormalize" = "...`, the `security` on top level is called first, and after `security_post_denormalize`. This could lead to unwanted behaviour, so avoid using both of them simultaneously. If you need to use `security_post_denormalize`, consider adding `security` for the other operations instead of the global one. @@ -280,7 +280,7 @@ You can change it by configuring the `security_message` attribute or the `securi For example: -[codeSelector] + ```php ## Filtering Collection According to the Current User Permissions diff --git a/core/serialization.md b/core/serialization.md index 974f6a55df0..33df9fda592 100644 --- a/core/serialization.md +++ b/core/serialization.md @@ -74,7 +74,7 @@ It is simple to specify what groups to use in the API system: 1. Add the normalization context and denormalization context attributes to the resource, and specify which groups to use. Here you see that we add `read` and `write`, respectively. You can use any group names you wish. 2. Apply the groups to properties in the object. -[codeSelector] + ```php Alternatively, you can use the more verbose syntax: @@ -158,7 +158,7 @@ level ignored. In the following example we use different serialization groups for the `GET` and `PUT` operations: -[codeSelector] + ```php The `name` and `author` properties will be included in the document generated during a `GET` operation because the configuration defined at the resource level is inherited. However the document generated when a `PUT` request will be received will only @@ -247,7 +247,7 @@ response through the use of serialization groups. By using the following seriali a JSON representation of the author is embedded in the book response. As soon as any of the author's attributes is in the `book` group, the author will be embedded. -[codeSelector] + ```php -[codeSelector] + ```php The generated JSON using previous settings is below: @@ -347,7 +347,7 @@ Instead of embedding relations in the main HTTP response, you may want [to "push It is also possible to embed a relation in `PUT`, `PATCH` and `POST` requests. To enable that feature, set the serialization groups the same way as normalization. For example: -[codeSelector] + ```php The following rules apply when denormalizing embedded relations: @@ -386,7 +386,7 @@ You can specify as many embedded relation levels as you want. It is a common problem to have entities that reference other entities of the same type: -[codeSelector] + ```php The problem here is that the **$parent** property become automatically an embedded object. Besides, the property won't be shown on the OpenAPI view. To force the **$parent** property to be used as an IRI, add an **#[ApiProperty(readableLink: false, writableLink: false)]** annotation: -[codeSelector] + ```php ## Property Normalization Context @@ -602,7 +602,7 @@ class Book Sometimes you need to expose calculated fields. This can be done by leveraging the groups. This time not on a property, but on a method. -[codeSelector] + ```php ## Changing the Serialization Context Dynamically @@ -675,7 +675,7 @@ App\Entity\Greeting: Let's imagine a resource where most fields can be managed by any user, but some can be managed only by admin users: -[codeSelector] + ```php All entry points are the same for all users, so we should find a way to detect if the authenticated user is an admin, and if so dynamically add the `admin:input` value to deserialization groups in the `$context` array. @@ -1040,7 +1040,7 @@ an IRI. A client that uses JSON-LD must send a second HTTP request to retrieve i You can configure API Platform to embed the JSON-LD context in the root document by adding the `jsonld_embed_context` attribute to the `#[ApiResource]` annotation: -[codeSelector] + ```php The JSON output will now include the embedded context: diff --git a/core/subresources.md b/core/subresources.md index 970f10922c1..efda2a79359 100644 --- a/core/subresources.md +++ b/core/subresources.md @@ -9,7 +9,7 @@ The starting point of a subresource must be a relation on an existing resource. For example, let's create two entities (Question, Answer) and set up a subresource so that `/question/42/answer` gives us the answer to the question 42: -[codeSelector] + ```php Note that all we had to do is to set up `#[ApiSubresource]` on the `Question::answer` relation. Because the `answer` is a to-one relation, we know that this subresource is an item. Therefore the response will look like this: @@ -109,7 +109,7 @@ Note: only for `GET` operations are supported at the moment You may want custom groups on subresources, you can set `normalization_context` or `denormalization_context` on that operation. To do so, add a `subresourceOperations` node. For example: -[codeSelector] + ```php ``` -[/codeSelector] + In the previous examples, the `method` attribute is mandatory, because the operation name doesn't match a supported HTTP method. diff --git a/core/url-generation-strategy.md b/core/url-generation-strategy.md index 0e6b78b8ea8..fedb9780a97 100644 --- a/core/url-generation-strategy.md +++ b/core/url-generation-strategy.md @@ -33,7 +33,7 @@ api_platform: It can also be configured only for a specific resource: -[codeSelector] + ```php ``` -[/codeSelector] + For the above configuration, the collection will be like this: