Sök…
Syntax
- @api
- @author [namn] [<e-postadress>]
- @copyright <beskrivning>
- @deprecated [<"Semantisk version">] [: <"Semantisk version">] [<beskrivning>]
- @exempel [URI] [<beskrivning>]
- {@exempel [URI] [: <start> .. <end>]}
- @inheritDoc
- @inre
- {@intern [beskrivning]}}
- @license [<SPDX-identifier> | URI] [namn]
- @method [return "Type"] [name] (["Type"] [parameter], [...]) [beskrivning]
- @ paket [nivå 1] \ [nivå 2] \ [etc.]
- @param ["Type"] [namn] [<beskrivning>]
- @property ["Type"] [namn] [<beskrivning>]
- @return <"Type"> [beskrivning]
- @see [URI | "FQSEN"] [<beskrivning>]
- @since [<"Semantisk version">] [<beskrivning>]
- @ kastar ["Skriv"] [<beskrivning>]
- @todo [beskrivning]
- @uses [fil | "FQSEN"] [<beskrivning>]
- @var ["Type"] [element_name] [<beskrivning>]
- @version ["Semantisk version"] [<beskrivning>]
- @filesource - Inkluderar aktuell fil i phpDocumentor-analys av resultat
- @link [URI] [<beskrivning>] - Länktagg hjälper till att definiera relation eller länk mellan strukturella element .
Anmärkningar
"PHPDoc" är ett avsnitt av dokumentation som ger information om aspekter av ett "strukturellt element" - PSR-5
PHPDoc-kommentarer är kommentarer som ger metadata om alla typer av strukturer i PHP. Många populära IDE: er är som standard konfigurerade för att använda PHPDoc-kommentarer för att ge kodinsikter och identifiera möjliga problem innan de uppstår.
Medan PHPDoc-kommentarer inte är en del av PHP-kärnan har de för närvarande utkaststatus med PHP-FIG som PSR-5 .
Alla PHPDoc-anteckningar finns i DocBlocks som visas med en flerstrad med två asterisker:
/**
*
*/
Det fullständiga PHP-FIG- standardutkastet är tillgängligt på GitHub .
Lägga till metadata till funktioner
Anteckningar på funktionsnivå hjälper IDE: er att identifiera returvärden eller potentiellt farlig kod
/**
* Adds two numbers together.
*
* @param Int $a First parameter to add
* @param Int $b Second parameter to add
* @return Int
*/
function sum($a, $b)
{
return (int) $a + $b;
}
/**
* Don't run me! I will always raise an exception.
*
* @throws Exception Always
*/
function dangerousCode()
{
throw new Exception('Ouch, that was dangerous!');
}
/**
* Old structures should be deprecated so people know not to use them.
*
* @deprecated
*/
function oldCode()
{
mysql_connect(/* ... */);
}
Lägga till metadata till filer
Metadata på filnivå gäller alla koder i filen och bör placeras högst upp i filen:
<?php
/**
* @author John Doe ([email protected])
* @copyright MIT
*/
Ärva metadata från förälderstrukturer
Om en klass utökar en annan klass och skulle använda samma metadata, är @inheritDoc ett enkelt sätt att använda samma dokumentation. Om flera klasser ärver från en bas, behöver bara basen ändras för att barnen ska drabbas.
abstract class FooBase
{
/**
* @param Int $a First parameter to add
* @param Int $b Second parameter to add
* @return Int
*/
public function sum($a, $b) {}
}
class ConcreteFoo extends FooBase
{
/**
* @inheritDoc
*/
public function sum($a, $b)
{
return $a + $b;
}
}
Beskriver en variabel
Nyckelordet @var kan användas för att beskriva typen och användningen av:
- en klassegendom
- en lokal eller global variabel
- en klass eller en global konstant
class Example {
/** @var string This is something that stays the same */
const UNCHANGING = "Untouchable";
/** @var string $some_str This is some string */
public $some_str;
/**
* @var array $stuff This is a collection of stuff
* @var array $nonsense These are nonsense
*/
private $stuff, $nonsense;
...
}
Typen kan vara en av de inbyggda PHP-typerna, eller en användardefinierad klass, inklusive namnutrymmen.
Namnet på variabeln ska inkluderas, men kan utelämnas om docblocken bara gäller ett objekt.
Beskrivning av parametrar
/**
* Parameters
*
* @param int $int
* @param string $string
* @param array $array
* @param bool $bool
*/
function demo_param($int, $string, $array, $bool)
{
}
/**
* Parameters - Optional / Defaults
*
* @param int $int
* @param string $string
* @param array $array
* @param bool $bool
*/
function demo_param_optional($int = 5, $string = 'foo', $array = [], $bool = false)
{
}
/**
* Parameters - Arrays
*
* @param array $mixed
* @param int[] $integers
* @param string[] $strings
* @param bool[] $bools
* @param string[]|int[] $strings_or_integers
*/
function demo_param_arrays($mixed,$integers, $strings, $bools, $strings_or_integers)
{
}
/**
* Parameters - Complex
* @param array $config
* <pre>
* $params = [
* 'hostname' => (string) DB hostname. Required.
* 'database' => (string) DB name. Required.
* 'username' => (string) DB username. Required.
* ]
* </pre>
*/
function demo_param_complex($config)
{
}
samlingar
PSR-5 föreslår en form av Generics-notation för samlingar.
Generics Syntax
Type[]
Type<Type>
Type<Type[, Type]...>
Type<Type[|Type]...>
Värden i en samling KAN till och med vara en annan grupp och till och med en annan samling.
Type<Type<Type>>
Type<Type<Type[, Type]...>>
Type<Type<Type[|Type]...>>
exempel
<?php
/**
* @var ArrayObject<string> $name
*/
$name = new ArrayObject(['a', 'b']);
/**
* @var ArrayObject<int> $name
*/
$name = new ArrayObject([1, 2]);
/**
* @var ArrayObject<stdClass> $name
*/
$name = new ArrayObject([
new stdClass(),
new stdClass()
]);
/**
* @var ArrayObject<string|int|stdClass|bool> $name
*/
$name = new ArrayObject([
'a',
true,
1,
'b',
new stdClass(),
'c',
2
]);
/**
* @var ArrayObject<ArrayObject<int>> $name
*/
$name = new ArrayObject([
new ArrayObject([1, 2]),
new ArrayObject([1, 2])
]);
/**
* @var ArrayObject<int, string> $name
*/
$name = new ArrayObject([
1 => 'a',
2 => 'b'
]);
/**
* @var ArrayObject<string, int> $name
*/
$name = new ArrayObject([
'a' => 1,
'b' => 2
]);
/**
* @var ArrayObject<string, stdClass> $name
*/
$name = new ArrayObject([
'a' => new stdClass(),
'b' => new stdClass()
]);