====== PHP RFC: get_class() disallow null parameter ======
  * Version: 1.0
  * Date: 2016-08-12
  * Author: Danack
  * Status: Implemented (in PHP 7.2)
  * First Published at: https://wiki.php.net/rfc/get_class_disallow_null_parameter

===== Introduction =====

When null is passed as the parameter to get_class() inside a class context, the behaviour of the function can be highly surprising, 

<code php>
class Foo
{
    function bar($repository)
    {
        $result = $repository->find(100);

        echo get_class($result);
    }
}
</code>


If $result contains a valid object returned from the repository, the output will be of the class name of the type of $result.

If $result contains null, the output will be of the class context where get_class() was called from, in this case "Foo".


This feature violates the [[https://en.wikipedia.org/wiki/Principle_of_least_astonishment|Principle of least astonishment]]: "if a necessary feature has a high astonishment factor, it may be necessary to redesign the feature."


===== Proposal =====

Disallow null being passed to the function as a valid parameter. If get_class() is called with null as the parameter, a warning will be emitted:

<code>
Warning: get_class() expects parameter 1 to be object, null given in %s on line %d
</code>

I.e. the valid ways to call the function will be:

  * without any parameter.
  * with an object as the parameter.

Those two options will continue to have the same behaviour they currently have.


===== Backward Incompatible Changes =====

Most people won't see a BC break, as for the majority of people, passing null to this function is not a desired behaviour.

For people who do deliberately pass null to the function they will need to refactor their code from:

<code php>
$x = get_class($some_value_that_may_be_null);
</code>

to:

<code php>
if ($some_value_that_may_be_null === null) {
    $x = get_class();
}
else {
    $x = get_class($some_value_that_may_be_null);
}
</code>

===== Proposed PHP Version(s) =====
7.2

===== Voting =====

Should the get_class() function be changed to disallow null being passed as a parameter? As it is not a language or syntax change, the vote will pass if 50%+1 vote yes.

<doodle title="get_class() disallow null parameter" auth="Danack" voteType="single" closed="true">
   * Yes
   * No
</doodle>

Voting ended on the 8th October 2016 9pm UTC

===== null vs default param =====

When this topic was discussed before, it came as a surprise to some people that PHP can tell the difference between passing null and having a default value be null. This is perfectly possible in both internal code, as well as userland code:

<code php>
function get_class($item = null)
{
    if (func_num_args() == 0) {
        return get_current_scope_name();
    }
    if ($item === null) {
        trigger_error("get_class passed null, which is not an object.");
    }

    if (is_object($item) == false) {
        trigger_error("value is not an object");
        return false;
    }

    return gettype($item);
}
</code>


===== Patches and Tests =====

https://github.com/php/php-src/pull/2082

===== Implementation =====
After the project is implemented, this section should contain 
  - This was merged for PHP 7.2
  - https://github.com/php/php-src/pull/2082/commits/86aa1c784d3b584e6d0c235870a882c8fd169a74
  - https://secure.php.net/manual/en/function.get-class.php#refsect1-function.get-class-changelog