Зачем объявлять тип переменной PHP в комментарии?

Я довольно новичок в PHP, и я начал использовать NetBeans для разработки своего PHP-кода.

Внезапно, когда я ввел переменную в запрос, появилось диалоговое окно и попросило заполнить комментарий для хранения типа переменной. Я провел некоторое расследование и обнаружил, что это, по-видимому, популярная функция NetBeans, но я не мог найти никакой информации, чтобы объяснить мне, почему это было так.

Почему кто-то хочет поместить тип переменной PHP в комментарий? Используется ли это для разработки или действительно ли это полезно для самого кода? Является ли он интегральным или необязательным?

Добавление типа в теге @var внутри комментария вашего метода позволит NetBeans показать вам завершение кода. Это, конечно, необязательно, но всегда полезно полностью документировать свой код.

Изменить: отзыв для NetBeans для автоматического создания комментариев для вас – это использовать расширение /** . Для этого просто поместите курсор над свойством или методом, который вы хотите документировать, и введите /** а затем нажмите ENTER . Это расширит комментарий к стилю phpDoc и добавит соответствующие теги.

Изменить 2: Вы можете использовать тег @var для свойства, и вы можете использовать тег @param для метода, чтобы добиться того же эффекта с параметрами, переданными в метод.

Использование тега @var для свойства даст вам подсказки кода при использовании свойства в любом месте, где оно видно:

 /** * * @var My_Type */ private $_myProperty; 

Использование тега @param для метода даст вам подсказки кода при использовании параметра внутри метода:

 /** * * @param My_Type $obj */ public function myMethod($obj) { } 

Другим способом достижения аналогичного эффекта, а также для обеспечения безопасности типа является использование механизма подсказок типа PHP:

 public function myMethod(My_Type $obj) { } 

Обратите внимание, что этот метод имеет тип, указанный в сигнатуре метода. Теперь NetBeans предоставит такое же завершение кода внутри метода, который доступен с @param тега @param и PHP создаст E_RECOVERABLE_ERROR если тип, переданный в метод, не является тем же типом, который был указан. См . Документацию PHP относительно ошибок и способы их обработки, если вы хотите узнать больше об этой ошибке.

Я думаю, вы говорите о чем-то подобном:

 /** * @var SimpleXMLElement $xml */ private $xml; 

Это так называемый комментарий phpDoc . Это позволяет вам создавать документацию по API ( например, такую, например, такую ). Кроме того, большинство IDE, включая Eclipse и NetBeans, также поддерживают этот синтаксис и обеспечивают динамическое завершение кода и т. Д.

Если вы хотите объявить тип переменной в том случае, когда переменная не является свойством класса, а просто переменной, которая содержит некоторое возвращаемое значение, используйте комментарии одиночной звезды, за которыми следует @var, за которым следует ваше имя переменной, и, наконец, следует тип этой переменной . Например:

 /* @var $errorMessage NotificationMessage */ $errorMessage= $allMessages->rewind()->current(); 

сообщит NetBeans или PhpStorm, что $ errorMessage является экземпляром NotificationMessage, и вы должны получить завершение кода для этой переменной.

Несмотря на то, что netbeans используют его для автозаполнения, это часто полезно для документирования вашего кода:

В этом случае вы знаете, что этот метод получает и что он возвращает, но внутри кода вы не представляете, что происходит

 /** * Returns some stuff * @param string $someObj * @return array */ public function someMethod($someObj) { $factoredObj = getObject($someObj); //you are not sure what type it returns $resultArray = $factoredObj->toArray(); return $resultArray; } 

Вы можете прокомментировать это с /* @var $variable type */ внутри кода

 /** * Returns some stuff * @param string $someObj * @return array */ public function someMethod($someObj) { /* @var $factoredObj someType */ $factoredObj = getObject($someObj); $resultArray = $factoredObj->toArray(); return $resultArray; } 

или

 $factoredObj = getObject($someObj); /* @var $factoredObj someType */ 

Поскольку PHP – это язык с отложенным / утиным языком, когда вы создаете большую программу, эти подсказки типов могут помочь вам или другим понять, что происходит, если возникнет проблема. Например, ожидая смешанного типа и отправляя целое число.