Определяемые пользователем магические методы: что такое «документированная магическая функциональность»?

Question

Мой вопрос довольно прост, вот контекст:

http://php.net/manual/en/language.oop5.magic.php

Магические методы

Имена функций __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __sleep(), __wakeup(), __toString (), __invoke (), __set_state () и __clone () магические в классах PHP. Вы не можете иметь функции с этими именами в любой из ваших классов, если вы не хотите магическую функциональность, связанную с ними.

PHP резервирует все имена функций, начинающиеся с __, как магические. Рекомендуется не использовать имена функций с __ в PHP, если вы не хотите документировать некоторые магические функции.

Я понимаю, для чего эти методы и как их использовать. Что я не понимаю, так это:

... если вам не нужны некоторые документированные магические функции.

Что это вообще значит? Существуют ли реальные причины для создания определенного пользователем __magicMethods()?

Answer 1

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

РЕДАКТИРОВАТЬ - чтобы быть еще яснее: допустим, вы реализуете для своей собственной бизнес-логики метод, называемый __toNumber(). В будущей версии PHP они решат, что всякий раз, когда объект используется в качестве числа (возможно, когда вы делаете $result = 3 * $yourObject), будет вызываться магический метод __toNumber() ... ваш объект будет иметь некоторую документированную «магическую» функциональность, даже если Вы специально не добавили его

Answer 2

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