IEMailTemplate.php 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * @copyright 2017, Morris Jobke <hey@morrisjobke.de>
  5. *
  6. * @author Joas Schilling <coding@schilljs.com>
  7. * @author Leon Klingele <leon@struktur.de>
  8. * @author Lukas Reschke <lukas@statuscode.ch>
  9. * @author Morris Jobke <hey@morrisjobke.de>
  10. *
  11. * @license GNU AGPL version 3 or any later version
  12. *
  13. * This program is free software: you can redistribute it and/or modify
  14. * it under the terms of the GNU Affero General Public License as
  15. * published by the Free Software Foundation, either version 3 of the
  16. * License, or (at your option) any later version.
  17. *
  18. * This program is distributed in the hope that it will be useful,
  19. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  21. * GNU Affero General Public License for more details.
  22. *
  23. * You should have received a copy of the GNU Affero General Public License
  24. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  25. *
  26. */
  27. namespace OCP\Mail;
  28. /**
  29. * Interface IEMailTemplate
  30. *
  31. * Interface to a class that allows to build HTML emails
  32. *
  33. * Example:
  34. *
  35. * <?php
  36. *
  37. * $emailTemplate = new EMailTemplate($this->defaults, $this->urlGenerator, $this->l10n);
  38. *
  39. * $emailTemplate->addHeader();
  40. * $emailTemplate->addHeading('Welcome aboard');
  41. * $emailTemplate->addBodyText('Welcome to your Nextcloud account, you can add, protect, and share your data.');
  42. *
  43. * $emailTemplate->addBodyButtonGroup(
  44. * 'Set your password', 'https://example.org/resetPassword/q1234567890qwertz',
  45. * 'Install Client', 'https://nextcloud.com/install/#install-clients'
  46. * );
  47. *
  48. * $emailTemplate->addFooter('Optional footer text');
  49. *
  50. * $htmlContent = $emailTemplate->renderHtml();
  51. * $plainContent = $emailTemplate->renderText();
  52. *
  53. * @since 12.0.0
  54. */
  55. interface IEMailTemplate {
  56. /**
  57. * Sets the subject of the email
  58. *
  59. * @param string $subject
  60. *
  61. * @since 13.0.0
  62. */
  63. public function setSubject(string $subject);
  64. /**
  65. * Adds a header to the email
  66. *
  67. * @since 12.0.0
  68. */
  69. public function addHeader();
  70. /**
  71. * Adds a heading to the email
  72. *
  73. * @param string $title
  74. * @param string|bool $plainTitle Title that is used in the plain text email
  75. * if empty the $title is used, if false none will be used
  76. *
  77. * @since 12.0.0
  78. */
  79. public function addHeading(string $title, $plainTitle = '');
  80. /**
  81. * Adds a paragraph to the body of the email
  82. *
  83. * @param string $text; Note: When $plainText falls back to this, HTML is automatically escaped in the HTML email
  84. * @param string|bool $plainText Text that is used in the plain text email
  85. * if empty the $text is used, if false none will be used
  86. *
  87. * @since 12.0.0
  88. */
  89. public function addBodyText(string $text, $plainText = '');
  90. /**
  91. * Adds a list item to the body of the email
  92. *
  93. * @param string $text; Note: When $plainText falls back to this, HTML is automatically escaped in the HTML email
  94. * @param string $metaInfo; Note: When $plainMetaInfo falls back to this, HTML is automatically escaped in the HTML email
  95. * @param string $icon Absolute path, must be 16*16 pixels
  96. * @param string|bool $plainText Text that is used in the plain text email
  97. * if empty the $text is used, if false none will be used
  98. * @param string|bool $plainMetaInfo Meta info that is used in the plain text email
  99. * if empty the $metaInfo is used, if false none will be used
  100. * @since 12.0.0
  101. */
  102. public function addBodyListItem(string $text, string $metaInfo = '', string $icon = '', $plainText = '', $plainMetaInfo = '');
  103. /**
  104. * Adds a button group of two buttons to the body of the email
  105. *
  106. * @param string $textLeft Text of left button; Note: When $plainTextLeft falls back to this, HTML is automatically escaped in the HTML email
  107. * @param string $urlLeft URL of left button
  108. * @param string $textRight Text of right button; Note: When $plainTextRight falls back to this, HTML is automatically escaped in the HTML email
  109. * @param string $urlRight URL of right button
  110. * @param string $plainTextLeft Text of left button that is used in the plain text version - if empty the $textLeft is used
  111. * @param string $plainTextRight Text of right button that is used in the plain text version - if empty the $textRight is used
  112. *
  113. * @since 12.0.0
  114. */
  115. public function addBodyButtonGroup(string $textLeft, string $urlLeft, string $textRight, string $urlRight, string $plainTextLeft = '', string $plainTextRight = '');
  116. /**
  117. * Adds a button to the body of the email
  118. *
  119. * @param string $text Text of button; Note: When $plainText falls back to this, HTML is automatically escaped in the HTML email
  120. * @param string $url URL of button
  121. * @param string $plainText Text of button in plain text version
  122. * if empty the $text is used, if false none will be used
  123. *
  124. * @since 12.0.0
  125. */
  126. public function addBodyButton(string $text, string $url, $plainText = '');
  127. /**
  128. * Adds a logo and a text to the footer. <br> in the text will be replaced by new lines in the plain text email
  129. *
  130. * @param string $text If the text is empty the default "Name - Slogan<br>This is an automatically sent email" will be used
  131. *
  132. * @since 12.0.0
  133. */
  134. public function addFooter(string $text = '');
  135. /**
  136. * Returns the rendered email subject as string
  137. *
  138. * @return string
  139. *
  140. * @since 13.0.0
  141. */
  142. public function renderSubject(): string;
  143. /**
  144. * Returns the rendered HTML email as string
  145. *
  146. * @return string
  147. *
  148. * @since 12.0.0
  149. */
  150. public function renderHtml(): string;
  151. /**
  152. * Returns the rendered plain text email as string
  153. *
  154. * @return string
  155. *
  156. * @since 12.0.0
  157. */
  158. public function renderText(): string;
  159. }