Updated April 6, 2023
Introduction to PHP Annotations
PHP annotations are basically metadata which can be included in the source code and also in between classes, functions, properties and methods. They are to be started with the prefix @ wherever they are declared and they indicate something specific. This information they provide is very useful to coders, helpful for documentation purposes and also an IDE may use this to display certain popup hint kind of things. The same annotation can also be used for other purposes besides validation such as to determine what kind of input needs to be given in a form and also for automation purposes. There are various kinds of annotations like the @var and @int types which can be used for specific uses as their name itself suggests.
Syntax
PHP annotations are used by giving @ prefix and its syntax is as follows:
class Example
{
// @var integer
public $new;
}
Annotation is @var here and whenever it is encountered just before the piece of any code (public $new here for example) it indicates that the $new is to have a value of type integer as told by the annotation.
class Example
{
// @var integer
// @range(0, 51)
// @label('Count of shops')
public $shop;
}
Annotations can also be used for specifying the range where it displays the maximum and the minimum values that are to be accepted as integer values for the function and the label gives the purpose of this function.
Types of PHP Annotations
Given below are the types:
1. Built-in Annotations
There are 2 built-in functions in annotations which are as follows:
a. Compiled: This annotation indicates that if the method/function should be JIT compiled or not. It is also a function scope type of annotation.
b. SuppressWarnings: This is another built-in annotation which means that any warnings thrown as part of the execution of the succeeding code below it must be suppressed.
2. Meta Annotations
These are those type of annotations which can be used to apply for other annotations. They are used for configuration of annotations.
a. @Annotations
There is a kind of annotation classes which will contain @annotation.
Code:
[@Annotation]
class MyAnnoExample {
// piece of code
}
b. @Target
As the name suggests, this annotation indicates those types of class elements or a method upon which the annotation will be applicable.
Upon this we can describe one or many targets:
- Property annotation is just before the property class declaration.
- Class which is allowed before the declaration of class.
- Function is declared before the function declaration.
- Method annotation allows proceeding the method declaration.
- Annotation is allowed for proceeding to declaration of annotation class.
c. @Repeatable
This annotation means that it may be repeated any number of times when being used.
d. @Inherited
This can also be used on the other user defined annotation classes as a meta-annotation. These inherited annotations are automatically inherited to the respective sub-classes when they are used upon a superclass.
3. Custom Annotations
These are very similar to declarations of the normal class. Each element of the annotation type is defined by each of the property declarations.
Examples of PHP Annotations
Given below are the examples mentioned:
Example #1
Code:
// namespace declaration here
[@Annotation]
[@Target("class")]
class MyAnnoEx {
[@Required]
public string $prop;
public array $arrayProp = [];
public embedAnno $embed;
}
[@Annotation]
// code for embedded annotation goes here
[@Target(["class", "annotation"])]
class embedAnno {
}
[@Annotation]
// example for target annotation
[@Target("property")]
class propAnno {
}
@Annotation
// code for method annotation goes here
@Target("method")
class methodAnno {
public string $val;
public function __construct(string $val) {
$this->val = $val;
}
}
This is just a basic example showing the usage of all the different types of annotations which are shown above. All the ones in the example like embed annotation, property annotation, method annotation are custom annotations.
Example #2
Code:
<!DOCTYPE html>
<html>
<body>
<?php
/**
* @Replace("exmaple", "for", "annotation")
*/
class MyNamedComponent
{
}
echo str_replace("First", "Second", "First Example");
?>
</body>
</html>
Output:
In this example we are naming the annotation as replace since the below code represents the usage of string replace function which is str_replace, an inbuilt function of PHP. Using this function, the first parameter passed in the function is replaced by the second one.
Example #3
Code:
<!DOCTYPE html>
<html>
<head>
<title>Simple Form Processing</title>
</head>
<body>
<h1>Form Processing using PHP</h1>
<fieldset>
<form id="formex1" method="post" action="formexample.php">
<!--Declaring First name for the form
@Annotation text first_name-->
First_Name:
<input type="text" name="First_Name"/>
<!--@var style color-->
<span style="color:blue;">*</span>
<br>
<br>
<!--Declaring Last_Name for the form
@Annotation text last_name-->
Last_Name:
<input type="text" name="last_name"/>
<span style="color:blue;">*</span>
<br>
<br>
<!--Declaring Location for the form
@Annotation text location-->
Stay location:
<input type="text" name="location"/>
<span style="color:blue;">*</span>
<br>
<br>
<!--Declaring EMAILID for the form
@Annotation text email-->
EmailID:
<input type="email" name="emailID"/>
<span style="color:blue;">*</span>
<br>
<br>
<!--Declaring Password for the form
@Annotation password-->
Password:
<input type="password" name="password"/>
<span style="color:blue;">*</span>
<br>
<br>
<!--Declaring Password for the form
@Radio button password-->
Gender:
<!-- Gender to be selected as either male or female -->
<input type="radio"
value="Male"
name="gender"> Male
<input type="radio"
value="Female"
name="gender">Female
<br>
<br>
<input type="confirm" value="confirm" name="confirm" />
</form>
</fieldset>
<?php
if(example($_POST['confirm']))
{
if(!example($error))
{
echo"<h1>DETAILS RECEIVED</h1><br>";
echo "<table border='2'>";
echo "<thead>";
echo "<th>Argument</th>";
echo "<th>Value</th>";
echo "</thead>";
echo "<tr>";
echo "<td>First Name</td>";
echo "<td>".$First_Name."</td>";
echo "</tr>";
echo "<tr>";
echo "<td>Last_Name</td>";
echo "<td>".$last_name."</td>";
echo "</tr>";
echo "<tr>";
echo "<td>Stay location</td>";
echo "<td>".$location."</td>";
echo "</tr>";
echo "<tr>";
echo "<td>Email Stay location</td>";
echo "<td>" .$emailID."</td>";
echo "</tr>";
echo "<tr>";
echo "<td>Password</td>";
echo "<td>".$password."</td>";
echo "</tr>";
echo "<tr>";
echo "<td>Gender</td>";
echo "<td>".$gender."</td>";
echo "</tr>";
echo "</table>";
}
}
?>
</body>
</html>
Output:
In this example, we are showing annotations in combination with the form validation in PHP. Using annotations we are labeling all the parameters which are required as input parameters to the form such as first and last name, email, location and password.
Conclusion
With the above examples we have noticed how annotations are a powerful tool to use and express metadata about our methods, classes or properties. We have also seen how to combine different kinds of annotations to declare workers who will perform certain tasks by writing some metadata about them. This makes them easy to find and gives actual information on whether or not they can be used.
Recommended Articles
This is a guide to PHP Annotations. Here we discuss the introduction to PHP annotations with types of annotations and respective examples. You may also have a look at the following articles to learn more –