====== Request for Comments: E_USER_DEPRECATED ======
  * Version: 1.0
  * Date: 2008-07-18
  * Author: Lars Strojny <lstrojny@php.net>
  * Status: Implemented in PHP 5.3
  * First Published at: http://wiki.php.net/rfc/e-user-deprecated-warning

===== Introduction =====

In 5.3 we introduced E_DEPRECATED to mark internal functions/classes/syntax elements as deprecated with a separate error level.
The same deprecation process applies for user level code. That's why we should introduce E_USER_DEPRECATED similar to the already present user space levels E_USER_WARNING, E_USER_NOTICE and E_USER_ERROR.

===== Proposal and Patch =====

  * 5_3: http://lars.schokokeks.org/php/E_USER_DEPRECATED.diff
  * HEAD: http://lars.schokokeks.org/php/E_USER_DEPRECATED-HEAD.diff

===== Use cases =====
==== UC 1: Deprecation warning in a constructor ====
<code php>
<?php
class Foo
{
    public function __construct()
    {
        trigger_error('Use Bar instead', E_USER_DEPRECATED);
    }
}
</code>
==== UC 2: Deprecation warning at function call ====
<code php>
<?php
function do_something()
{
    trigger_error('Use do_something_else() instead', E_USER_DEPRECATED);
}
</code>

==== UC 3: Deprecation warning when a file is included ====
<code php>
<?php
// MY_FUNKY_LIBRARY
trigger_error('Use non-funky library', E_USER_DEPRECATED);

...
</code>