Méthodes magiques définies par l'utilisateur : Qu'est-ce qu'une "fonctionnalité magique documentée" ?

Question

Ma question est assez simple, voici le contexte :

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

Méthodes magiques

Les noms des fonctions __construct() , __destruct() , __call() , __callStatic() , __get() , __set() , __isset() , __unset() , __sleep() , __wakeup() , __toString(), __invoke(), __set_state() et __clone() sont magiques dans les classes PHP. Vous ne pouvez pas avoir de fonctions avec ces noms dans dans aucune de vos classes, à moins que vous ne vouliez la fonctionnalité magique qui leur sont associées.

PHP réserve tous les noms de fonctions commençant par __ comme magiques. Il est recommandé de ne pas utiliser les noms de fonctions avec __ en PHP, à moins que vous ne vouliez une fonctionnalité magique documentée.

Je comprends à quoi servent ces méthodes et comment les utiliser. Ce que je ne comprends pas, c'est ceci :

...à moins que vous ne vouliez une fonctionnalité magique documentée.

Qu'est-ce que ça veut dire ? Existe-t-il des raisons réelles de créer des __magicMethods() ?

Answer 1

Je pense qu'ils veulent seulement dire qu'il est préférable de ne pas utiliser __ comme nom de départ pour vos méthodes, car PHP a réservé cette convention pour ses méthodes magiques et si vous utilisez cette convention pour une méthode, elle pourrait être remplacée dans le futur et avoir des fonctionnalités magiques. Du moins, c'est ce que j'ai compris.

EDIT - pour être encore plus clair : Disons que vous implémentez pour votre propre logique commerciale une méthode appelée __toNumber() . Dans une future version de PHP, ils ont décidé que lorsqu'un objet est utilisé comme un nombre (peut-être lorsque vous faites $result = 3 * $yourObject ) la méthode magique __toNumber() sera invoquée... votre objet aura une fonctionnalité "magique" documentée, même si vous ne l'avez pas spécifiquement ajoutée.

Answer 2

Cela signifie ne jamais utiliser de noms qui commencent par __ pour les fonctions, à moins que vous ne souhaitiez bénéficier de la fonctionnalité magique documentée dans le manuel PHP.