Merge branch '3.next' of github.com:cakephp/cakephp into 3.next

src/Core/functions.php

@@ -248,3 +248,35 @@ if (!function_exists('env')) {
     }
 
 }
+
+if (!function_exists('deprecationWarning')) {
+    /**
+     * Helper method for outputting deprecation warnings
+     *
+     * @param string $message The message to output as a deprecation warning.
+     * @param int $stackFrame The stack frame to include in the error. Defaults to 2
+     *   as that should point to application/plugin code.
+     * @return void
+     */
+    function deprecationWarning($message, $stackFrame = 2)
+    {
+        if (!(error_reporting() & E_USER_DEPRECATED)) {
+            return;
+        }
+
+        $trace = debug_backtrace();
+        if (isset($trace[$stackFrame])) {
+            $frame = $trace[$stackFrame];
+            $frame += ['file' => '[internal]', 'line' => '??'];
+
+            $message = sprintf(
+                '%s - %s, line: %s',
+                $message,
+                $frame['file'],
+                $frame['line']
+            );
+        }
+
+        trigger_error($message, E_USER_DEPRECATED);
+    }
+}

tests/TestCase/Core/FunctionsTest.php

@@ -42,4 +42,39 @@ class FunctionsTest extends TestCase
         $this->assertEquals('0', env('ZERO'));
         $this->assertEquals('0', env('ZERO', '1'));
     }
+
+    /**
+     * Test error messages coming out when debug is on, manually setting the stack frame
+     *
+     * @expectedException PHPUnit\Framework\Error\Deprecated
+     * @expectedExceptionMessage This is going away - [internal], line: ??
+     */
+    public function testDeprecationWarningEnabled()
+    {
+        error_reporting(E_ALL);
+        deprecationWarning('This is going away', 1);
+    }
+
+    /**
+     * Test error messages coming out when debug is on, not setting the stack frame manually
+     *
+     * @expectedException PHPUnit\Framework\Error\Deprecated
+     * @expectedExceptionMessageRegExp /This is going away - (.*?)[\/\\]TestCase.php, line\: \d+/
+     */
+    public function testDeprecationWarningEnabledDefaultFrame()
+    {
+        error_reporting(E_ALL);
+        deprecationWarning('This is going away');
+    }
+
+    /**
+     * Test no error when debug is off.
+     *
+     * @return void
+     */
+    public function testDeprecationWarningLevelDisabled()
+    {
+        error_reporting(E_ALL ^ E_USER_DEPRECATED);
+        $this->assertNull(deprecationWarning('This is going away'));
+    }
 }

tests/phpunit_aliases.php

@@ -7,4 +7,5 @@ if (class_exists('PHPUnit_Runner_Version')) {
     class_alias('PHPUnit_Framework_Test', 'PHPUnit\Framework\Test');
     class_alias('PHPUnit_Framework_AssertionFailedError', 'PHPUnit\Framework\AssertionFailedError');
     class_alias('PHPUnit_Framework_TestSuite', 'PHPUnit\Framework\TestSuite');
+    class_alias('PHPUnit_Framework_Error_Deprecated', 'PHPUnit\Framework\Error\Deprecated');
 }