Как при помощи phpDoc описать сразу два варианта метода, перегруженных через __call и __callStatic?

Question

[Станислав]

В классе есть два магических метода __call и callStatic, с помощью которых перегружается условный метод read(). В случае обращения к данному методу как к статическому, ему передается id сущности для чтения. В случае обращения к нему, как к методу экземпляра класса, ему ничего не передается, id берется из свойства экземпляра.

В обоих случаях возвращается один и тот же либо вновь созданный, либо уже существующий экземпляр класса. Перед классом я пробую записать вот так вот оба варианта метода, статический и нет:

/**
 * Class Entity
 *
 * @package MyCompany\Contracts
 *
 * @property array  $data
 * @property int    $id
 * @property string $name
 *
 * @method Entity read()
 * @method static Entity read( $id )
 */

Но PhpStorm 2019.1 ругается на такую запись вот так:

Method with same name already defined in this class
Another definition with same name exists in this file

Кто прав, я или PhpStorm? Если я неправ, то как мне ублажить последнего?

Answer 1

[Александр]

Нет, такое поведение в IDE не заложенно, и подсказать ей никак нельзя.

Если вы попытаетесь внутри класса объявить 2 метода - с одинковым именем, то получите точно такую же ошибку. Method with same name already defined in this class. Собственно это и есть ожидаемое поведение, когда вы описываете методы в phpDoc.

class Test {

    public function test() {
    }

    public static function test() {
    }
}

Comments

[Станислав]

ожидаемое поведение

С этим сложно спорить, пока мы не прочитаем официальную документацию, где приводится вот такой код:

<?php
class MethodTest
{
    public function __call($name, $arguments)
    {
        // Note: value of $name is case sensitive.
        echo "Calling object method '$name' "
             . implode(', ', $arguments). "\n";
    }

    /**  As of PHP 5.3.0  */
    public static function __callStatic($name, $arguments)
    {
        // Note: value of $name is case sensitive.
        echo "Calling static method '$name' "
             . implode(', ', $arguments). "\n";
    }
}

$obj = new MethodTest;
$obj->runTest('in object context');

MethodTest::runTest('in static context');  // As of PHP 5.3.0
?>

После его прочтения становится очевидно, что поведение с перегрузкой методов в разных контекстах является ожидаемым поведением, по крайней мере, с точки зрения разработчиков самого PHP. Другое дело, что phpDoc, PhpStorm или кто угодно еще может не поддерживать это. Но ответ принят, хотя он и верен лишь формально (по крайней мере я сам также не смог найти вариант нотации в данном случае).

Answer 2

[Антон Шаманов]

ide не рассчитана на подобный говнокод

Comments

[Сергей Попов]

Антон Шаманов проблема в том, что подобное происходит, например в Laravel Eloquent и QueryBuilder, когда необходимые методы перегружаются и через __call, и через __callStatic. Беда-с)

[Станислав]

Вы уверены, что хорошо знаете PHP? Потому что методы __call и __callStatic существуют ровно для этого, для перегрузки методов в различных контекстах.

Почитайте документацию, возможно, откроете для себя что-нибудь новенькое.

[Антон Шаманов]

Сергей Попов, популярный не значит качественный. стараюсь по возможности избегать "магии" - такой код хуже читается, сложнее отлаживать, ну и проблемы документирования Вы сами видите.

[Станислав]

Антон Шаманов, перегрузка - это наитипичнейшая ситуация в языках программирования. Если вам это неизвестно, то проблема вашего уровня как программиста. Laravel, как и я, просто используем то, что доступно в языке, не придумывая своего. Более того, сама документация PHP содержит примеры перегрузки, см пример с runTest().

Так что не позорьтесь.

[Сергей Попов]

Антон Шаманов, Здесь-то я согласен. Даже в ларавелевских проектах, мы стараемся уходить от магии и писать максимально тупой код. Но от Eloquent можно сбежать только в Doctrine или новенький Cycle/ORM, к которому мы присматриваемся. А так - да. Магия - зло.

[Станислав]

Сергей Попов, сама по себе магия не зло, зло - отсутствие ее поддержки через всякие документоры или нативная в IDE.

[Сергей Попов]

Станислав, Про перегрузку слышали все, кто выходил за пределы PHP, например, в Java. В ней, например это можно сделать через Reflection API. Подобное поведение называется Dynamic Proxies и является антипаттерном. Зачастую, статически-перегруженные методы можно заменить фабриками или иными порождающими паттернами, что будет более правильно с точки зрения, как читаемости, так и архитектуры.

[Антон Шаманов]

Станислав, использование подобных методов должно быть обусловлено, они - своеобразный костыль на крайний случай.

[Станислав]

Сергей Попов, очевидно, что автор ответа, где мы переписываемся, не выходил, раз называет перегрузку говнокодом. Ваш пример и обсуждение того, антипаттерн это или нет - это совсем про другое, тут же совершенно классическая ситуация перегрузки метода в двух контекстах, которая то ли не поддерживается phpDoc, то ли поддерживается, но так, что я не могу найти примеры такой поддержки.

[Сергей Попов]

Станислав, Магия зло по той простой причине, что она ослабляет понимание кода. Я имею опыт работы со сложными системами, где была подмешана магия. Это всегда больно, по той причине, что такая магия сложно отлаживается и найти баги, возникающие по причине подобной магии - трудно. А самое плохое, что ты не можешь найти все места, где такая магия применяется. Кроме того, наличие в коде метода магии не позволяет провести нормальное тестирование, в частности, например, использовать моки объектов, которые должны вызываться. К примеру, я терпеть не могу использовать магические классы доступа к репозиторию данных. По той простой причине, что замокать подобное соединение невозможно. Вместо этого у нас в компании предпочитают передавать соединение явно в конструктор и использовать его. Таким образом мы избавляемся от лишних прослоек, упрощая понимание кода.
Помимо этого, магические методы всегда можно заменить немагическими.

[Сергей Попов]

Станислав, Нет. PHPDoc такое поведение не поддерживает.

[Антон Шаманов]

Сергей Попов, мне Doctrine2 нравится всем кроме крайне странного решения в виде маппинга с помощью тегов в комментах

[Александр]

Станислав, не поддерживает. И вопрос думаю можно закрыть.

[Сергей Попов]

Антон Шаманов, это очень хорошее очевидное решение, позволяющее напрямую из аннотаций восстановить состояние базы на определенной ветке. Это гораздо лучше, чем миграции лары, которые надо не забывать откатывать при переключении ветки.

[Сергей Попов]

Антон Шаманов, По поводу аннотаций, вся Java построена на них.

[Антон Шаманов]

Сергей Попов, насчет очевидности хз, как по мне использование свойств описывающих связи/поля - прозрачнее и удобнее.

[Станислав]

Сергей Попов,

Это всегда больно, по той причине, что такая магия сложно отлаживается и найти баги, возникающие по причине подобной магии - трудно.

Просто повторюсь еще раз: я не спорю с тем, что магия - зло, когда она мешает пониманию кода, его отладке и так далее. Но речь о том, чтобы как раз избавиться от такого, за счет документирования через phpDoc.

[Антон Шаманов]

Станислав, как документация поможет избавится от сложностей в отладке?

[Антон Шаманов]

Станислав, и нужно понимать что нет такого стандарта как phpDoc, это просто адаптация явы.

[Станислав]

Антон Шаманов, смотря какие сложности вы тут подразумеваете. Опишите пример, в котором может возникнуть проблема, мешающая отладить перегрузку метода в двух контекстах.

[Антон Шаманов]

Станислав, ide не может определить забыли ли добавить данный метод, ошиблись в его названии при вызове или все ок и это просто магия + вызов динамического контента вроде $this из статичного метода

[Станислав]

Антон Шаманов,

ide не может определить забыли ли добавить данный метод, ошиблись в его названии при вызове или все ок и это просто магия + вызов динамического контента вроде $this из статичного метода

не совсем понял, на что вы конкретно тут отвечаете.

[Антон Шаманов]

Станислав, на твой вопрос, он вроде один или я что-то упускаю? на мой ты кстати так и не ответил

[Станислав]

Антон Шаманов, в таком случае боюсь вы не понимаете, о чем пишете. Никакого вызова $this из статического метода тут не будет происходить. Будет два разных метода, вызываемые один внутри __call, а другой внутри __callStatic. Это могут быть даже не методы, а просто куски кода внутри перечисленных магических методов.

И эти методы, если будет оформлено все как 2 разных метода, будут иметь разное название, разную логику и вообще не будут как-либо связаны между собой, кроме как тем, что в итоге будет выполнен код либо одного метода, либо другого, в зависимости от контекста.

[Антон Шаманов]

Станислав, мы не обо мне говорим, а о ide

[Станислав]

Антон Шаманов, до свидания, Антон, разговор явно зашел в тупик.

[Антон Шаманов]

Станислав,

как документация поможет избавится от сложностей в отладке?

[Станислав]

Антон Шаманов, Антон, мы же с вами уже попрощались.

[Александр]

Станислав, интересно наблюдать за вашим холиваром, но тут такой вопрос, вы все еще ждете другого ответа? К слову, почему не закрываете вопрос.

[Станислав]

Александр, если вы про свой ответ, а точнее комментарий, который вы там выше оставили - я не могу закрыть на нем вопрос, так как это комментарий, а не ответ, который я могу пометить верным. Если вы про ответ Антона, то я не думаю, что Антон просто вообще понимает, о чем идет речь.

[Александр]

Станислав, Ок. Вынесу в отдельный комментарий. Хотя ответ по сути одинаковый.