1	<?php
2	/**
3	*
4	* This file is part of the phpBB Forum Software package.
5	*
6	* @copyright (c) phpBB Limited <https://www.phpbb.com>
7	* @license GNU General Public License, version 2 (GPL-2.0)
8	*
9	* For full copyright and license information, please see
10	* the docs/CREDITS.txt file.
11	*
12	*/
13
14	namespace phpbb\textformatter;
15
16	/**
17	* Used to manipulate a parsed text
18	*
19	* In this interface, "plain text" refers to regular text as it would be inputted by a user.
20	* "Parsed text" refers to whichever form is returned by the implementation after parsing, which
21	* should be suitable to be reinserted into the database.
22	*/
23	interface utils_interface
24	{
25	/**
26	* Replace BBCodes and other formatting elements with whitespace
27	*
28	* NOTE: preserves smilies as text
29	*
30	* @param  string $text Parsed text
31	* @return string       Plain text
32	*/
33	public function clean_formatting($text);
34
35	/**
36	* Create a quote block for given text
37	*
38	* Possible attributes:
39	*   - author:  author's name (usually a username)
40	*   - post_id: post_id of the post being quoted
41	*   - user_id: user_id of the user being quoted
42	*   - time:    timestamp of the original message
43	*
44	* @param  string $text       Quote's text
45	* @param  array  $attributes Quote's attributes
46	* @return string             Quote block to be used in a new post/text
47	*/
48	public function generate_quote($text, array $attributes = array());
49
50	/**
51	* Get a list of quote authors, limited to the outermost quotes
52	*
53	* @param  string   $text Parsed text
54	* @return string[]       List of authors
55	*/
56	public function get_outermost_quote_authors($text);
57
58	/**
59	* Remove given BBCode and its content, at given nesting depth
60	*
61	* @param  string  $text        Parsed text
62	* @param  string  $bbcode_name BBCode's name
63	* @param  integer $depth       Minimum nesting depth (number of parents of the same name)
64	* @return string               Parsed text
65	*/
66	public function remove_bbcode($text, $bbcode_name, $depth = 0);
67
68	/**
69	* Return a parsed text to its original form
70	*
71	* @param  string $text Parsed text
72	* @return string       Original plain text
73	*/
74	public function unparse($text);
75
76	/**
77	* Return whether or not a parsed text represent an empty text.
78	*
79	* @param  string $text Parsed text
80	* @return bool         True if the original text is empty
81	*/
82	public function is_empty($text);
83	}