A simple example will be provided to show usage for each annotation, but may not be a completely functioning snippet. All usages may not have an example.
- Body
- DELETE
- ErrorBody
- Field
- FieldMap
- GET
- HEAD
- Header
- HeaderMap
- Headers
- OPTIONS
- Part
- PartMap
- PATCH
- Path
- POST
- PUT
- Query
- QueryMap
- QueryName
- REQUEST
- ResponseBody
- Url
Defines a json body for the HTTP request.
This annotation sets the content type of the request to
application/json
. By default, the parameter must be a PSR-7
StreamInterface
, but adding a converter will allow additional
types to be provided and converted to json.
/**
* @Body("myBody")
*/
public function example(Mybody $myBody): Call;
Performs a DELETE request to the provided path.
/**
* @DELETE("/foo?q=test")
*/
public function example(): Call;
Defines the type the response body should be converted to on errors.
Errors are defined as any http status code outside of 200-300. By
default, only StreamInterface
is supported, but a converter
will extend the supported types.
/**
* @ErrorBody("App\MyClass")
*/
public function example(): Call;
Adds values to a form encoded body.
This annotation sets the request content type to
application/x-www-form-urlencoded
. The value of this annotation
is both the name of the field and the name of the method parameter.
This can be overridden using the var
key in the annotation. The
provided argument will be converted to a string before getting applied
to the request. Passing in an array will apply each value to the field
name. The encoded
key will specify if the data is already encoded,
and therefore shouldn't be re-encoded. This value defaults to false.
/**
* @Field("field1")
* @Field("field2", encoded=true)
* @Field("field3[]", var="field3")
*/
public function example(int $field1, bool $field2, array $field3): Call;
This works much like @Field, except it must be provided an
iterable map. Each key/value pair will be treated as a @Field
with
the key acting as the field name. The value may be anything that
@Field
supports.
/**
* @FieldMap("fieldMap")
*/
public function example(Traversable $fieldMap): Call;
Performs a GET request to the provided path.
/**
* @GET("/foo?q=test")
*/
public function example(): Call;
Performs a HEAD request to the provided path.
/**
* @HEAD("/foo?q=test")
*/
public function example(): Call;
Add a single header to a request.
The value of this annotation represents both the name of the header and the parameter name. Header names are lower-cased before getting added to the request. Headers follow PSR-7 request format, so multiple values with the same name may be added to the request. Passing an array as the header value also allows multiple values to be added under the same header name. Headers will converted to a string before being applied to the request.
/**
* @Header("X-Foo", var="header1")
* @Header("X-Foo", var="header2")
* @Header("X-Foo", var="header3")
*/
public function example(string $header1, bool $header2, array $header3): Call;
The above example will add multiple different values to the x-foo
header.
Allows a way to add multiple headers to a request at once. The annotation acts much like FieldMap, and accepts the same values as Header.
/**
* @HeaderMap("headerMap")
*/
public function example(Traversable $headerMap): Call;
Adds headers statically supplied in the annotation value.
/**
* @Headers({
* "X-Foo: Bar",
* "X-Ping: Pong"
* })
*/
Performs an OPTIONS request to the provided path.
/**
* @OPTIONS("/foo?q=test")
*/
public function example(): Call;
Adds values to a multipart body.
This annotation set the request content type to multipart/form-data
.
This annotation can accept any value @Body can or a special
MultipartBody
class, which you can use to set additional properties
like headers or the filename. The annotation value specifies the part
name. If you're using MultipartBody
the part name will be pulled from
the object and the annotation value will be ignored.
/**
* @Part("part1")
* @Part("part2")
*/
public function example(MyBody $part1, MultipartBody $part2): Call;
This annotation works like previous map annotations. Keys represent part names, and values may be anything that a @Part can accept. The same rules apply.
/**
* @PartMap("partMap")
*/
public function example(Traversable $partMap): Call;
Performs a PATCH request to the provided path.
/**
* @PATCH("/foo?q=test")
*/
public function example(): Call;
This annotation allows you to create a dynamic url, and map path
parts to method parameters. By default, the annotation value will
be the same as the url placeholder and parameter name, but this is
overridable by using the var
annotation key. Path values will get
converted to strings before getting added to the url.
/**
* @GET("/foo/{user}/{foo-bar}"
* @Path("user")
* @Path("foo-bar", var="fooBar")
*/
public function example(int $user, string $fooBar): Call;
Performs a POST request to the provided path.
/**
* @POST("/foo?q=test")
*/
public function example(): Call;
Performs a PUT request to the provided path.
/**
* @PUT("/foo?q=test")
*/
public function example(): Call;
Add a query to the url.
The annotation value represents the query name. The value will be
converted to a string before being added to the url. Use the var
key if the parameter name doesn't match the query name and the encoded
key to specify if the query data is already encoded. This defaults to
false. Passing an array will apply each value to to the specified name.
/**
* @Query("query1")
* @Query("query2", encoded=true)
* @Query("query3[]", var="field3")
*/
public function example(int $query1, bool $query2, array $query3): Call;
Adds multiple queries to a url.
This annotation works the same as other map annotations and adds key/value pairs of queries to a url where keys represent the query name and the value may be anything that @Query allows.
/**
* @QueryMap("queryMap")
*/
public function example(Traversable $queryMap): Call;
Adds only the query name part of a query, excluding the =
and anything
after it. The annotation value represents the name (which can be changed
with the var
key), and you can specify that the data is already encoded
with the encoded
key. Data is converted to a string before getting
added to the url.
/**
* @QueryName("queryName1")
* @QueryName("queryName2", encoded=true)
*/
public function example(float $queryName1, string $queryName2): Call;
Performs a custom request method to the provided path.
Additionally, the method type and whether the request contains a body must be specified.
/**
* @REQUEST("/foo?q=test", type="FOO", body=false)
*/
public function example(): Call;
Defines the type the response body should be converted to on success.
Successful responses are defined as any http status code with 200-300.
By default, only StreamInterface
is supported, but a converter
will extend the supported types.
/**
* @ResponseBody("App\MyClass")
*/
public function example(): Call;
This annotation allows changing the base url of a request. This will
allow overriding whatever url is specified on the RetrofitBuilder
.
/**
* @Url("baseUrl")
*/
public function example(string $baseUrl): Call;