transformations.html 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260
  1. <!DOCTYPE html>
  2. <html lang="en">
  3. <head>
  4. <meta charset="utf-8" />
  5. <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
  6. <title>Transformations &#8212; phpMyAdmin 5.2.2 documentation</title>
  7. <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
  8. <link rel="stylesheet" type="text/css" href="_static/classic.css" />
  9. <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
  10. <script src="_static/jquery.js"></script>
  11. <script src="_static/underscore.js"></script>
  12. <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
  13. <script src="_static/doctools.js"></script>
  14. <script src="_static/sphinx_highlight.js"></script>
  15. <link rel="index" title="Index" href="genindex.html" />
  16. <link rel="search" title="Search" href="search.html" />
  17. <link rel="copyright" title="Copyright" href="copyright.html" />
  18. <link rel="next" title="Bookmarks" href="bookmarks.html" />
  19. <link rel="prev" title="Two-factor authentication" href="two_factor.html" />
  20. </head><body>
  21. <div class="related" role="navigation" aria-label="related navigation">
  22. <h3>Navigation</h3>
  23. <ul>
  24. <li class="right" style="margin-right: 10px">
  25. <a href="genindex.html" title="General Index"
  26. accesskey="I">index</a></li>
  27. <li class="right" >
  28. <a href="bookmarks.html" title="Bookmarks"
  29. accesskey="N">next</a> |</li>
  30. <li class="right" >
  31. <a href="two_factor.html" title="Two-factor authentication"
  32. accesskey="P">previous</a> |</li>
  33. <li class="nav-item nav-item-0"><a href="index.html">phpMyAdmin 5.2.2 documentation</a> &#187;</li>
  34. <li class="nav-item nav-item-1"><a href="user.html" accesskey="U">User Guide</a> &#187;</li>
  35. <li class="nav-item nav-item-this"><a href="">Transformations</a></li>
  36. </ul>
  37. </div>
  38. <div class="document">
  39. <div class="documentwrapper">
  40. <div class="bodywrapper">
  41. <div class="body" role="main">
  42. <section id="transformations">
  43. <span id="id1"></span><h1>Transformations<a class="headerlink" href="#transformations" title="Permalink to this heading">¶</a></h1>
  44. <div class="admonition note">
  45. <p class="admonition-title">Note</p>
  46. <p>You need to have configured the <a class="reference internal" href="setup.html#linked-tables"><span class="std std-ref">phpMyAdmin configuration storage</span></a> to use the transformations
  47. feature.</p>
  48. </div>
  49. <section id="introduction">
  50. <span id="transformationsintro"></span><h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this heading">¶</a></h2>
  51. <p>To enable transformations, you have to set up the <code class="docutils literal notranslate"><span class="pre">column_info</span></code>
  52. table and the proper directives. Please see the <a class="reference internal" href="config.html#config"><span class="std std-ref">Configuration</span></a> on how to do so.</p>
  53. <p>phpMyAdmin has two different types of transformations: browser display
  54. transformations, which affect only how the data is shown when browsing
  55. through phpMyAdmin; and input transformations, which affect a value
  56. prior to being inserted through phpMyAdmin.
  57. You can apply different transformations to the contents of each
  58. column. Each transformation has options to define how it will affect the
  59. stored data.</p>
  60. <p>Say you have a column <code class="docutils literal notranslate"><span class="pre">filename</span></code> which contains a filename. Normally
  61. you would see in phpMyAdmin only this filename. Using display transformations
  62. you can transform that filename into a HTML link, so you can click
  63. inside of the phpMyAdmin structure on the column’s link and will see
  64. the file displayed in a new browser window. Using transformation
  65. options you can also specify strings to append/prepend to a string or
  66. the format you want the output stored in.</p>
  67. <p>For a general overview of all available transformations and their
  68. options, you can either go to the <code class="docutils literal notranslate"><span class="pre">Change</span></code> link for an existing column
  69. or from the dialog to create a new column, in either case there is a link
  70. on that column structure page for “Browser display transformation” and
  71. “Input transformation” which will show more information about each
  72. transformation that is available on your system.</p>
  73. <p>For a tutorial on how to effectively use transformations, see our
  74. <a class="reference external" href="https://www.phpmyadmin.net/docs/">Link section</a> on the
  75. official phpMyAdmin homepage.</p>
  76. </section>
  77. <section id="usage">
  78. <span id="transformationshowto"></span><h2>Usage<a class="headerlink" href="#usage" title="Permalink to this heading">¶</a></h2>
  79. <p>Go to the table structure page (reached by clicking on
  80. the ‘Structure’ link for a table). There click on “Change” (or the change
  81. icon) and there you will see the five transformation–related fields at the end of the line.
  82. They are called ‘<a class="reference internal" href="glossary.html#term-Media-type"><span class="xref std std-term">Media type</span></a>’, ‘Browser transformation’ and
  83. ‘Transformation options’.</p>
  84. <ul class="simple">
  85. <li><p>The field ‘<a class="reference internal" href="glossary.html#term-Media-type"><span class="xref std std-term">Media type</span></a>’ is a drop-down field. Select the <a class="reference internal" href="glossary.html#term-Media-type"><span class="xref std std-term">Media type</span></a> that
  86. corresponds to the column’s contents. Please note that many transformations
  87. are inactive until a <a class="reference internal" href="glossary.html#term-Media-type"><span class="xref std std-term">Media type</span></a> is selected.</p></li>
  88. <li><p>The field ‘Browser display transformation’ is a drop-down field. You can
  89. choose from a hopefully growing amount of pre-defined transformations.
  90. See below for information on how to build your own transformation.
  91. There are global transformations and mimetype-bound transformations.
  92. Global transformations can be used for any mimetype. They will take
  93. the mimetype, if necessary, into regard. Mimetype-bound
  94. transformations usually only operate on a certain mimetype. There are
  95. transformations which operate on the main mimetype (like ‘image’),
  96. which will most likely take the subtype into regard, and those who
  97. only operate on a specific subtype (like ‘image/jpeg’). You can use
  98. transformations on mimetypes for which the function was not defined
  99. for. There is no security check for you selected the right
  100. transformation, so take care of what the output will be like.</p></li>
  101. <li><p>The field ‘Browser display transformation options’ is a free-type textfield. You have
  102. to enter transform-function specific options here. Usually the
  103. transforms can operate with default options, but it is generally a
  104. good idea to look up the overview to see which options are necessary.
  105. Much like the ENUM/SET-Fields, you have to split up several options
  106. using the format ‘a’,’b’,’c’,…(NOTE THE MISSING BLANKS). This is
  107. because internally the options will be parsed as an array, leaving the
  108. first value the first element in the array, and so forth. If you want
  109. to specify a MIME character set you can define it in the
  110. transformation_options. You have to put that outside of the pre-
  111. defined options of the specific mime-transform, as the last value of
  112. the set. Use the format “’; charset=XXX’”. If you use a transform, for
  113. which you can specify 2 options and you want to append a character
  114. set, enter “‘first parameter’,’second parameter’,’charset=us-ascii’”.
  115. You can, however use the defaults for the parameters: “’’,’’,’charset
  116. =us-ascii’”. The default options can be configured using
  117. <span class="target" id="index-0"></span><a class="reference internal" href="config.html#cfg_DefaultTransformations"><code class="xref config config-option docutils literal notranslate"><span class="pre">$cfg['DefaultTransformations']</span></code></a>.</p></li>
  118. <li><p>‘Input transformation’ is another drop-down menu that corresponds exactly
  119. with the instructions above for “Browser display transformation” except
  120. these these affect the data before insertion in to the database. These are
  121. most commonly used to either provide a specialized editor (for example, using
  122. the phpMyAdmin SQL editor interface) or selector (such as for uploading an image).
  123. It’s also possible to manipulate the data such as converting an IPv4 address to binary
  124. or parsing it through a regular expression.</p></li>
  125. <li><p>Finally, ‘Input transformation options’ is the equivalent of the “Browser display
  126. transformation options” section above and is where optional and required parameters are entered.</p></li>
  127. </ul>
  128. </section>
  129. <section id="file-structure">
  130. <span id="transformationsfiles"></span><h2>File structure<a class="headerlink" href="#file-structure" title="Permalink to this heading">¶</a></h2>
  131. <p>All specific transformations for mimetypes are defined through class
  132. files in the directory <code class="file docutils literal notranslate"><span class="pre">libraries/classes/Plugins/Transformations/</span></code>. Each of
  133. them extends a certain transformation abstract class declared in
  134. <code class="file docutils literal notranslate"><span class="pre">libraries/classes/Plugins/Transformations/Abs</span></code>.</p>
  135. <p>They are stored in files to ease customization and to allow easy adding of
  136. new or custom transformations.</p>
  137. <p>Because the user cannot enter their own mimetypes, it is kept certain that
  138. the transformations will always work. It makes no sense to apply a
  139. transformation to a mimetype the transform-function doesn’t know to
  140. handle.</p>
  141. <p>There is a file called <code class="file docutils literal notranslate"><span class="pre">libraries/classes/Plugins/Transformations.php</span></code> that provides some
  142. basic functions which can be included by any other transform function.</p>
  143. <p>The file name convention is <code class="docutils literal notranslate"><span class="pre">[Mimetype]_[Subtype]_[Transformation</span>
  144. <span class="pre">Name].php</span></code>, while the abstract class that it extends has the
  145. name <code class="docutils literal notranslate"><span class="pre">[Transformation</span> <span class="pre">Name]TransformationsPlugin</span></code>. All of the
  146. methods that have to be implemented by a transformations plug-in are:</p>
  147. <ol class="arabic simple">
  148. <li><p>getMIMEType() and getMIMESubtype() in the main class;</p></li>
  149. <li><p>getName(), getInfo() and applyTransformation() in the abstract class
  150. it extends.</p></li>
  151. </ol>
  152. <p>The getMIMEType(), getMIMESubtype() and getName() methods return the
  153. name of the MIME type, MIME Subtype and transformation accordingly.
  154. getInfo() returns the transformation’s description and possible
  155. options it may receive and applyTransformation() is the method that
  156. does the actual work of the transformation plug-in.</p>
  157. <p>Please see the <code class="file docutils literal notranslate"><span class="pre">libraries/classes/Plugins/Transformations/TEMPLATE</span></code> and
  158. <code class="file docutils literal notranslate"><span class="pre">libraries/classes/Plugins/Transformations/TEMPLATE_ABSTRACT</span></code> files for adding
  159. your own transformation plug-in. You can also generate a new
  160. transformation plug-in (with or without the abstract transformation
  161. class), by using
  162. <code class="file docutils literal notranslate"><span class="pre">scripts/transformations_generator_plugin.sh</span></code> or
  163. <code class="file docutils literal notranslate"><span class="pre">scripts/transformations_generator_main_class.sh</span></code>.</p>
  164. <p>The applyTransformation() method always gets passed three variables:</p>
  165. <ol class="arabic simple">
  166. <li><p><strong>$buffer</strong> - Contains the text inside of the column. This is the
  167. text, you want to transform.</p></li>
  168. <li><p><strong>$options</strong> - Contains any user-passed options to a transform
  169. function as an array.</p></li>
  170. <li><p><strong>$meta</strong> - Contains an object with information about your column. The
  171. data is drawn from the output of the <a class="reference external" href="https://www.php.net/mysql_fetch_field">mysql_fetch_field()</a> function. This means, all
  172. object properties described on the <a class="reference external" href="https://www.php.net/mysql_fetch_field">manual page</a> are available in this
  173. variable and can be used to transform a column accordingly to
  174. unsigned/zerofill/not_null/… properties. The $meta-&gt;mimetype
  175. variable contains the original <a class="reference internal" href="glossary.html#term-Media-type"><span class="xref std std-term">Media type</span></a> of the column (i.e.
  176. ‘text/plain’, ‘image/jpeg’ etc.)</p></li>
  177. </ol>
  178. </section>
  179. </section>
  180. <div class="clearer"></div>
  181. </div>
  182. </div>
  183. </div>
  184. <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
  185. <div class="sphinxsidebarwrapper">
  186. <div>
  187. <h3><a href="index.html">Table of Contents</a></h3>
  188. <ul>
  189. <li><a class="reference internal" href="#">Transformations</a><ul>
  190. <li><a class="reference internal" href="#introduction">Introduction</a></li>
  191. <li><a class="reference internal" href="#usage">Usage</a></li>
  192. <li><a class="reference internal" href="#file-structure">File structure</a></li>
  193. </ul>
  194. </li>
  195. </ul>
  196. </div>
  197. <div>
  198. <h4>Previous topic</h4>
  199. <p class="topless"><a href="two_factor.html"
  200. title="previous chapter">Two-factor authentication</a></p>
  201. </div>
  202. <div>
  203. <h4>Next topic</h4>
  204. <p class="topless"><a href="bookmarks.html"
  205. title="next chapter">Bookmarks</a></p>
  206. </div>
  207. <div role="note" aria-label="source link">
  208. <h3>This Page</h3>
  209. <ul class="this-page-menu">
  210. <li><a href="_sources/transformations.rst.txt"
  211. rel="nofollow">Show Source</a></li>
  212. </ul>
  213. </div>
  214. <div id="searchbox" style="display: none" role="search">
  215. <h3 id="searchlabel">Quick search</h3>
  216. <div class="searchformwrapper">
  217. <form class="search" action="search.html" method="get">
  218. <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
  219. <input type="submit" value="Go" />
  220. </form>
  221. </div>
  222. </div>
  223. <script>document.getElementById('searchbox').style.display = "block"</script>
  224. </div>
  225. </div>
  226. <div class="clearer"></div>
  227. </div>
  228. <div class="related" role="navigation" aria-label="related navigation">
  229. <h3>Navigation</h3>
  230. <ul>
  231. <li class="right" style="margin-right: 10px">
  232. <a href="genindex.html" title="General Index"
  233. >index</a></li>
  234. <li class="right" >
  235. <a href="bookmarks.html" title="Bookmarks"
  236. >next</a> |</li>
  237. <li class="right" >
  238. <a href="two_factor.html" title="Two-factor authentication"
  239. >previous</a> |</li>
  240. <li class="nav-item nav-item-0"><a href="index.html">phpMyAdmin 5.2.2 documentation</a> &#187;</li>
  241. <li class="nav-item nav-item-1"><a href="user.html" >User Guide</a> &#187;</li>
  242. <li class="nav-item nav-item-this"><a href="">Transformations</a></li>
  243. </ul>
  244. </div>
  245. <div class="footer" role="contentinfo">
  246. &#169; <a href="copyright.html">Copyright</a> 2012 - 2024, The phpMyAdmin devel team.
  247. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
  248. </div>
  249. </body>
  250. </html>