Merge pull request #12460 from cakephp/3.next-email-viewbuilder-methods

3.next email viewbuilder methods

src/Mailer/Email.php

@@ -1260,6 +1260,10 @@ class Email implements JsonSerializable, Serializable
      */
     public function setTemplate($template)
     {
+        deprecationWarning(
+            'Email::setTemplate() is deprecated. Use $email->viewBuilder()->setTemplate() instead.'
+        );
+
         $this->viewBuilder()->setTemplate($template ?: '');
 
         return $this;
@@ -1272,6 +1276,10 @@ class Email implements JsonSerializable, Serializable
      */
     public function getTemplate()
     {
+        deprecationWarning(
+            'Email::getTemplate() is deprecated. Use $email->viewBuilder()->getTemplate() instead.'
+        );
+
         return $this->viewBuilder()->getTemplate();
     }
 
@@ -1283,6 +1291,10 @@ class Email implements JsonSerializable, Serializable
      */
     public function setLayout($layout)
     {
+        deprecationWarning(
+            'Email::setLayout() is deprecated. Use $email->viewBuilder()->setLayout() instead.'
+        );
+
         $this->viewBuilder()->setLayout($layout ?: false);
 
         return $this;
@@ -1295,6 +1307,10 @@ class Email implements JsonSerializable, Serializable
      */
     public function getLayout()
     {
+        deprecationWarning(
+            'Email::getLayout() is deprecated. Use $email->viewBuilder()->getLayout() instead.'
+        );
+
         return $this->viewBuilder()->getLayout();
     }
 
@@ -1308,7 +1324,11 @@ class Email implements JsonSerializable, Serializable
      */
     public function template($template = false, $layout = false)
     {
-        deprecationWarning('Email::template() is deprecated. Use Email::setTemplate() or Email::getTemplate() and Email::setLayout() or Email::getLayout() instead.');
+        deprecationWarning(
+            'Email::template() is deprecated. ' .
+            'Use $email->viewBuilder()->getTemplate()/setTemplate() ' .
+            'and $email->viewBuilder()->getLayout()/setLayout() instead.'
+        );
 
         if ($template === false) {
             return [
@@ -1415,6 +1435,10 @@ class Email implements JsonSerializable, Serializable
      */
     public function setTheme($theme)
     {
+        deprecationWarning(
+            'Email::setTheme() is deprecated. Use $email->viewBuilder()->setTheme() instead.'
+        );
+
         $this->viewBuilder()->setTheme($theme);
 
         return $this;
@@ -1427,6 +1451,10 @@ class Email implements JsonSerializable, Serializable
      */
     public function getTheme()
     {
+        deprecationWarning(
+            'Email::getTheme() is deprecated. Use $email->viewBuilder()->getTheme() instead.'
+        );
+
         return $this->viewBuilder()->getTheme();
     }
 
@@ -1439,7 +1467,9 @@ class Email implements JsonSerializable, Serializable
      */
     public function theme($theme = null)
     {
-        deprecationWarning('Email::theme() is deprecated. Use Email::setTheme() or Email::getTheme() instead.');
+        deprecationWarning(
+            'Email::theme() is deprecated. Use $email->viewBuilder()->getTheme()/setTheme() instead.'
+        );
 
         if ($theme === null) {
             return $this->getTheme();
@@ -1456,6 +1486,10 @@ class Email implements JsonSerializable, Serializable
      */
     public function setHelpers(array $helpers)
     {
+        deprecationWarning(
+            'Email::setHelpers() is deprecated. Use $email->viewBuilder()->setHelpers() instead.'
+        );
+
         $this->viewBuilder()->setHelpers($helpers, false);
 
         return $this;
@@ -1468,6 +1502,10 @@ class Email implements JsonSerializable, Serializable
      */
     public function getHelpers()
     {
+        deprecationWarning(
+            'Email::getHelpers() is deprecated. Use $email->viewBuilder()->getHelpers() instead.'
+        );
+
         return $this->viewBuilder()->getHelpers();
     }
 
@@ -1480,7 +1518,9 @@ class Email implements JsonSerializable, Serializable
      */
     public function helpers($helpers = null)
     {
-        deprecationWarning('Email::helpers() is deprecated. Use Email::setHelpers() or Email::getHelpers() instead.');
+        deprecationWarning(
+            'Email::helpers() is deprecated. Use $email->viewBuilder()->getHelpers()/setHelpers() instead.'
+        );
 
         if ($helpers === null) {
             return $this->getHelpers();

src/Mailer/Mailer.php

@@ -225,7 +225,9 @@ abstract class Mailer implements EventListenerInterface
      */
     public function layout($layout)
     {
-        deprecationWarning('Mailer::layout() is deprecated. Use setLayout() which sets the layout on the email class instead.');
+        deprecationWarning(
+            'Mailer::layout() is deprecated. Use $mailer->viewBuilder()->setLayout() instead.'
+        );
 
         $this->_email->viewBuilder()->setLayout($layout);
 

tests/TestCase/Mailer/EmailTest.php

@@ -809,8 +809,8 @@ class EmailTest extends TestCase
      */
     public function testTemplate()
     {
-        $this->Email->setTemplate('template');
-        $this->assertSame('template', $this->Email->getTemplate());
+        $this->Email->viewBuilder()->setTemplate('template');
+        $this->assertSame('template', $this->Email->viewBuilder()->getTemplate());
     }
 
     /**
@@ -820,8 +820,8 @@ class EmailTest extends TestCase
      */
     public function testLayout()
     {
-        $this->Email->setLayout('layout');
-        $this->assertSame('layout', $this->Email->getLayout());
+        $this->Email->viewBuilder()->setLayout('layout');
+        $this->assertSame('layout', $this->Email->viewBuilder()->getLayout());
     }
 
     /**
@@ -831,11 +831,11 @@ class EmailTest extends TestCase
      */
     public function testTheme()
     {
-        $this->assertNull($this->Email->getTheme());
+        $this->assertNull($this->Email->viewBuilder()->getTheme());
 
-        $this->Email->setTheme('default');
+        $this->Email->viewBuilder()->setTheme('default');
         $expected = 'default';
-        $this->assertSame($expected, $this->Email->getTheme());
+        $this->assertSame($expected, $this->Email->viewBuilder()->getTheme());
     }
 
     /**
@@ -1200,13 +1200,13 @@ class EmailTest extends TestCase
         $result = $this->Email->getSubject();
         $this->assertEquals($config['subject'], $result);
 
-        $result = $this->Email->getTheme();
+        $result = $this->Email->viewBuilder()->getTheme();
         $this->assertEquals($config['theme'], $result);
 
         $result = $this->Email->getTransport();
         $this->assertInstanceOf('Cake\Mailer\Transport\DebugTransport', $result);
 
-        $result = $this->Email->getHelpers();
+        $result = $this->Email->viewBuilder()->getHelpers();
         $this->assertEquals($config['helpers'], $result);
     }
 
@@ -1223,7 +1223,7 @@ class EmailTest extends TestCase
         $this->Email->setTo('you@cakephp.org');
         $this->Email->setSubject('My title');
         $this->Email->setEmailFormat('text');
-        $this->Email->setTemplate('default');
+        $this->Email->viewBuilder()->setTemplate('default');
         $this->Email->setViewVars([
             'content' => 'A message to you',
         ]);
@@ -1656,7 +1656,7 @@ class EmailTest extends TestCase
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
         $this->Email->setProfile(['empty']);
-        $this->Email->setTemplate('default', 'default');
+        $this->Email->viewBuilder()->setTemplate('default', 'default');
         $result = $this->Email->send();
 
         $this->assertContains('This email was sent using the CakePHP Framework', $result['message']);
@@ -1678,8 +1678,9 @@ class EmailTest extends TestCase
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
         $this->Email->setConfig(['empty']);
-        $this->Email->setTemplate('default');
-        $this->Email->setLayout(null);
+        $this->Email->viewBuilder()
+            ->setTemplate('default')
+            ->setLayout(false);
         $result = $this->Email->send('message body.');
 
         $this->assertContains('message body.', $result['message']);
@@ -1700,7 +1701,7 @@ class EmailTest extends TestCase
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
         $this->Email->setProfile(['empty']);
-        $this->Email->setTemplate('default', 'default');
+        $this->Email->viewBuilder()->setTemplate('default', 'default');
         $this->Email->setEmailFormat('both');
         $result = $this->Email->send();
 
@@ -1747,8 +1748,8 @@ class EmailTest extends TestCase
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
         $this->Email->setProfile(['empty']);
-        $this->Email->setTemplate('default');
-        $this->Email->setLayout('japanese');
+        $this->Email->viewBuilder()->setTemplate('default');
+        $this->Email->viewBuilder()->setLayout('japanese');
         $this->Email->charset = 'ISO-2022-JP';
         $result = $this->Email->send();
 
@@ -1773,8 +1774,8 @@ class EmailTest extends TestCase
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
         $this->Email->setProfile(['empty']);
-        $this->Email->setTheme('TestTheme');
-        $this->Email->setTemplate('themed', 'default');
+        $this->Email->viewBuilder()->setTheme('TestTheme');
+        $this->Email->viewBuilder()->setTemplate('themed', 'default');
         $result = $this->Email->send();
 
         $this->assertContains('In TestTheme', $result['message']);
@@ -1800,7 +1801,7 @@ class EmailTest extends TestCase
         $this->Email->setSubject('My title');
         $this->Email->setProfile(['empty']);
         $this->Email->setEmailFormat('html');
-        $this->Email->setTemplate('html', 'default');
+        $this->Email->viewBuilder()->setTemplate('html', 'default');
         $result = $this->Email->send();
 
         $this->assertTextContains('<h1>HTML Ipsum Presents</h1>', $result['message']);
@@ -1821,7 +1822,7 @@ class EmailTest extends TestCase
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
         $this->Email->setProfile(['empty']);
-        $this->Email->setTemplate('custom', 'default');
+        $this->Email->viewBuilder()->setTemplate('custom', 'default');
         $this->Email->setViewVars(['value' => 12345]);
         $result = $this->Email->send();
 
@@ -1842,7 +1843,7 @@ class EmailTest extends TestCase
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
         $this->Email->setProfile(['empty']);
-        $this->Email->setTemplate('japanese', 'default');
+        $this->Email->viewBuilder()->setTemplate('japanese', 'default');
         $this->Email->setViewVars(['value' => '日本語の差し込み123']);
         $this->Email->charset = 'ISO-2022-JP';
         $result = $this->Email->send();
@@ -1866,18 +1867,18 @@ class EmailTest extends TestCase
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
         $this->Email->setProfile(['empty']);
-        $this->Email->setTemplate('custom_helper', 'default');
+        $this->Email->viewBuilder()
+            ->setTemplate('custom_helper')
+            ->setLayout('default')
+            ->setHelpers(['Time'], false);
         $this->Email->setViewVars(['time' => $timestamp]);
 
-        $result = $this->Email->setHelpers(['Time']);
-        $this->assertInstanceOf('Cake\Mailer\Email', $result);
-
         $result = $this->Email->send();
         $dateTime = new \DateTime;
         $dateTime->setTimestamp($timestamp);
         $this->assertContains('Right now: ' . $dateTime->format($dateTime::ATOM), $result['message']);
 
-        $result = $this->Email->getHelpers();
+        $result = $this->Email->viewBuilder()->getHelpers();
         $this->assertEquals(['Time'], $result);
     }
 
@@ -1895,7 +1896,7 @@ class EmailTest extends TestCase
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
         $this->Email->setProfile(['empty']);
-        $this->Email->setTemplate('image');
+        $this->Email->viewBuilder()->setTemplate('image');
         $this->Email->setEmailFormat('html');
         $server = env('SERVER_NAME') ? env('SERVER_NAME') : 'localhost';
 
@@ -1924,30 +1925,45 @@ class EmailTest extends TestCase
         $this->Email->setSubject('My title');
         $this->Email->setProfile(['empty']);
 
-        $result = $this->Email->setTemplate('TestPlugin.test_plugin_tpl')->setLayout('default')->send();
+        $this->Email->viewBuilder()
+            ->setTemplate('TestPlugin.test_plugin_tpl')
+            ->setLayout('default');
+        $result = $this->Email->send();
         $this->assertContains('Into TestPlugin.', $result['message']);
         $this->assertContains('This email was sent using the CakePHP Framework', $result['message']);
 
-        $result = $this->Email->setTemplate('TestPlugin.test_plugin_tpl')->setLayout('TestPlugin.plug_default')->send();
+        $this->Email->viewBuilder()
+            ->setTemplate('TestPlugin.test_plugin_tpl')
+            ->setLayout('TestPlugin.plug_default');
+        $result = $this->Email->send();
         $this->assertContains('Into TestPlugin.', $result['message']);
         $this->assertContains('This email was sent using the TestPlugin.', $result['message']);
 
-        $result = $this->Email->setTemplate('TestPlugin.test_plugin_tpl')->setLayout('plug_default')->send();
+        $this->Email->viewBuilder()
+            ->setTemplate('TestPlugin.test_plugin_tpl')
+            ->setLayout('plug_default');
+        $result = $this->Email->send();
         $this->assertContains('Into TestPlugin.', $result['message']);
         $this->assertContains('This email was sent using the TestPlugin.', $result['message']);
 
-        $result = $this->Email->setTemplate('TestPlugin.test_plugin_tpl')->setLayout('TestPluginTwo.default')->send();
+        $this->Email->viewBuilder()
+            ->setTemplate('TestPlugin.test_plugin_tpl')
+            ->setLayout('TestPluginTwo.default');
+        $result = $this->Email->send();
         $this->assertContains('Into TestPlugin.', $result['message']);
         $this->assertContains('This email was sent using TestPluginTwo.', $result['message']);
 
         // test plugin template overridden by theme
-        $this->Email->setTheme('TestTheme');
+        $this->Email->viewBuilder()->setTheme('TestTheme');
         $result = $this->Email->send();
 
         $this->assertContains('Into TestPlugin. (themed)', $result['message']);
 
         $this->Email->setViewVars(['value' => 12345]);
-        $result = $this->Email->setTemplate('custom')->setLayout('TestPlugin.plug_default')->send();
+        $this->Email->viewBuilder()
+            ->setTemplate('custom')
+            ->setLayout('TestPlugin.plug_default');
+        $result = $this->Email->send();
         $this->assertContains('Here is your value: 12345', $result['message']);
         $this->assertContains('This email was sent using the TestPlugin.', $result['message']);
         Plugin::unload();
@@ -1966,7 +1982,8 @@ class EmailTest extends TestCase
         $this->Email->setFrom('cake@cakephp.org');
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
-        $this->Email->setTemplate('fooo')->send();
+        $this->Email->viewBuilder()->setTemplate('fooo');
+        $this->Email->send();
     }
 
     /**
@@ -1982,7 +1999,7 @@ class EmailTest extends TestCase
         $this->Email->setFrom('cake@cakephp.org');
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
-        $this->Email->setTemplate('custom', 'default');
+        $this->Email->viewBuilder()->setTemplate('custom', 'default');
         $this->Email->setProfile([]);
         $this->Email->setViewVars(['value' => 12345]);
         $this->Email->setEmailFormat('both');
@@ -2081,8 +2098,8 @@ class EmailTest extends TestCase
         $this->assertSame($instance->getFrom(), ['cake@cakephp.org' => 'cake@cakephp.org']);
         $this->assertSame($instance->getTo(), ['debug@cakephp.org' => 'debug@cakephp.org']);
         $this->assertSame($instance->getSubject(), 'Update ok');
-        $this->assertSame($instance->getTemplate(), 'custom');
-        $this->assertSame($instance->getLayout(), 'custom_layout');
+        $this->assertSame($instance->viewBuilder()->getTemplate(), 'custom');
+        $this->assertSame($instance->viewBuilder()->getLayout(), 'custom_layout');
         $this->assertEquals($instance->getViewVars(), ['value' => 123, 'name' => 'CakePHP']);
         $this->assertSame($instance->getCc(), ['cake@cakephp.org' => 'Myself']);
 
@@ -2105,7 +2122,7 @@ class EmailTest extends TestCase
         $this->Email->setTo(['you@cakephp.org' => 'You']);
         $this->Email->setSubject('My title');
         $this->Email->setProfile(['empty']);
-        $this->Email->setTemplate('default', 'default');
+        $this->Email->viewBuilder()->setTemplate('default', 'default');
         $this->Email->setEmailFormat('both');
         $this->Email->send();
 
@@ -2140,13 +2157,13 @@ class EmailTest extends TestCase
     public function testReset()
     {
         $this->Email->setTo('cake@cakephp.org');
-        $this->Email->setTheme('TestTheme');
+        $this->Email->viewBuilder()->setTheme('TestTheme');
         $this->Email->setEmailPattern('/.+@.+\..+/i');
         $this->assertSame(['cake@cakephp.org' => 'cake@cakephp.org'], $this->Email->getTo());
 
         $this->Email->reset();
         $this->assertSame([], $this->Email->getTo());
-        $this->assertFalse($this->Email->getTheme());
+        $this->assertFalse($this->Email->viewBuilder()->getTheme());
         $this->assertSame(Email::EMAIL_PATTERN, $this->Email->getEmailPattern());
     }
 
@@ -2239,7 +2256,7 @@ class EmailTest extends TestCase
     public function testRenderWithLayoutAndAttachment()
     {
         $this->Email->setEmailFormat('html');
-        $this->Email->setTemplate('html', 'default');
+        $this->Email->viewBuilder()->setTemplate('html', 'default');
         $this->Email->setAttachments([CAKE . 'basics.php']);
         $result = $this->Email->render([]);
         $this->assertNotEmpty($result);
@@ -2297,8 +2314,8 @@ class EmailTest extends TestCase
         ];
         $this->Email = new Email($configs);
 
-        $template = $this->Email->getTemplate();
-        $layout = $this->Email->getLayout();
+        $template = $this->Email->viewBuilder()->getTemplate();
+        $layout = $this->Email->viewBuilder()->getLayout();
         $this->assertEquals('', $template);
         $this->assertEquals($configs['layout'], $layout);
     }
@@ -3000,4 +3017,28 @@ XML;
             );
         }
     }
+
+    /**
+     * Test deprecated methods
+     *
+     * @return void
+     */
+    public function testDeprecatedMethods()
+    {
+        $this->deprecated(function () {
+            $this->Email
+                ->setTemplate('foo')
+                ->setLayout('bar')
+                ->setTheme('baz')
+                ->setHelpers(['A', 'B']);
+
+            $this->assertSame('foo', $this->Email->getTemplate());
+            $this->assertSame('bar', $this->Email->getLayout());
+            $this->assertSame('baz', $this->Email->getTheme());
+            $this->assertSame(['A', 'B'], $this->Email->getHelpers());
+
+            $this->Email->setLayout('');
+            $this->assertFalse($this->Email->getLayout());
+        });
+    }
 }

tests/TestCase/Mailer/MailerTest.php

@@ -84,7 +84,7 @@ class MailerTest extends TestCase
     public function testGetSetProxies()
     {
         $mailer = new TestMailer();
-        $result = $mailer->setLayout('custom')
+        $result = $mailer
             ->setTo('test@example.com')
             ->setCc('cc@example.com');
         $this->assertSame($result, $mailer);