doc/transformations.rst

   1 .. _transformations:
   2
   3 Transformations
   4 ===============
   5
   6 .. note::
   7
   8     You need to have configured the :ref:`linked-tables` to use the transformations
   9     feature.
  10
  11 .. _transformationsintro:
  12
  13 Introduction
  14 ++++++++++++
  15
  16 To enable transformations, you have to set up the ``column_info``
  17 table and the proper directives. Please see the :ref:`config` on how to do so.
  18
  19 phpMyAdmin has two different types of transformations: browser display
  20 transformations, which affect only how the data is shown when browsing
  21 through phpMyAdmin; and input transformations, which affect a value
  22 prior to being inserted through phpMyAdmin.
  23 You can apply different transformations to the contents of each
  24 column. Each transformation has options to define how it will affect the
  25 stored data.
  26
  27 Say you have a column ``filename`` which contains a filename. Normally
  28 you would see in phpMyAdmin only this filename. Using display transformations
  29 you can transform that filename into a HTML link, so you can click
  30 inside of the phpMyAdmin structure on the column's link and will see
  31 the file displayed in a new browser window. Using transformation
  32 options you can also specify strings to append/prepend to a string or
  33 the format you want the output stored in.
  34
  35 For a general overview of all available transformations and their
  36 options, you can either go to the ``Change`` link for an existing column
  37 or from the dialog to create a new column, in either case there is a link
  38 on that column structure page for "Browser display transformation" and
  39 "Input transformation" which will show more information about each
  40 transformation that is available on your system.
  41
  42 For a tutorial on how to effectively use transformations, see our
  43 `Link section <https://www.phpmyadmin.net/docs/>`_ on the
  44 official phpMyAdmin homepage.
  45
  46 .. _transformationshowto:
  47
  48 Usage
  49 +++++
  50
  51 Go to the table structure page (reached by clicking on
  52 the 'Structure' link for a table). There click on "Change" (or the change
  53 icon) and there you will see the five transformation--related fields at the end of the line.
  54 They are called ':term:`Media type`', 'Browser transformation' and
  55 'Transformation options'.
  56
  57 * The field ':term:`Media type`' is a drop-down field. Select the :term:`Media type` that
  58   corresponds to the column's contents. Please note that many transformations
  59   are inactive until a :term:`Media type` is selected.
  60 * The field 'Browser display transformation' is a drop-down field. You can
  61   choose from a hopefully growing amount of pre-defined transformations.
  62   See below for information on how to build your own transformation.
  63   There are global transformations and mimetype-bound transformations.
  64   Global transformations can be used for any mimetype. They will take
  65   the mimetype, if necessary, into regard. Mimetype-bound
  66   transformations usually only operate on a certain mimetype. There are
  67   transformations which operate on the main mimetype (like 'image'),
  68   which will most likely take the subtype into regard, and those who
  69   only operate on a specific subtype (like 'image/jpeg'). You can use
  70   transformations on mimetypes for which the function was not defined
  71   for. There is no security check for you selected the right
  72   transformation, so take care of what the output will be like.
  73 * The field 'Browser display transformation options' is a free-type textfield. You have
  74   to enter transform-function specific options here. Usually the
  75   transforms can operate with default options, but it is generally a
  76   good idea to look up the overview to see which options are necessary.
  77   Much like the ENUM/SET-Fields, you have to split up several options
  78   using the format 'a','b','c',...(NOTE THE MISSING BLANKS). This is
  79   because internally the options will be parsed as an array, leaving the
  80   first value the first element in the array, and so forth. If you want
  81   to specify a MIME character set you can define it in the
  82   transformation\_options. You have to put that outside of the pre-
  83   defined options of the specific mime-transform, as the last value of
  84   the set. Use the format "'; charset=XXX'". If you use a transform, for
  85   which you can specify 2 options and you want to append a character
  86   set, enter "'first parameter','second parameter','charset=us-ascii'".
  87   You can, however use the defaults for the parameters: "'','','charset
  88   =us-ascii'". The default options can be configured using
  89   :config:option:`$cfg['DefaultTransformations']`.
  90 * 'Input transformation' is another drop-down menu that corresponds exactly
  91   with the instructions above for "Browser display transformation" except
  92   these these affect the data before insertion in to the database. These are
  93   most commonly used to either provide a specialized editor (for example, using
  94   the phpMyAdmin SQL editor interface) or selector (such as for uploading an image).
  95   It's also possible to manipulate the data such as converting an IPv4 address to binary
  96   or parsing it through a regular expression.
  97 * Finally, 'Input transformation options' is the equivalent of the "Browser display
  98   transformation options" section above and is where optional and required parameters are entered.
  99
 100 .. _transformationsfiles:
 101
 102 File structure
 103 ++++++++++++++
 104
 105 All specific transformations for mimetypes are defined through class
 106 files in the directory :file:`libraries/classes/Plugins/Transformations/`. Each of
 107 them extends a certain transformation abstract class declared in
 108 :file:`libraries/classes/Plugins/Transformations/Abs`.
 109
 110 They are stored in files to ease customization and to allow easy adding of
 111 new or custom transformations.
 112
 113 Because the user cannot enter their own mimetypes, it is kept certain that
 114 the transformations will always work. It makes no sense to apply a
 115 transformation to a mimetype the transform-function doesn't know to
 116 handle.
 117
 118 There is a file called :file:`libraries/classes/Plugins/Transformations.php` that provides some
 119 basic functions which can be included by any other transform function.
 120
 121 The file name convention is ``[Mimetype]_[Subtype]_[Transformation
 122 Name].php``, while the abstract class that it extends has the
 123 name ``[Transformation Name]TransformationsPlugin``. All of the
 124 methods that have to be implemented by a transformations plug-in are:
 125
 126 #. getMIMEType() and getMIMESubtype() in the main class;
 127 #. getName(), getInfo() and applyTransformation() in the abstract class
 128    it extends.
 129
 130 The getMIMEType(), getMIMESubtype() and getName() methods return the
 131 name of the MIME type, MIME Subtype and transformation accordingly.
 132 getInfo() returns the transformation's description and possible
 133 options it may receive and applyTransformation() is the method that
 134 does the actual work of the transformation plug-in.
 135
 136 Please see the :file:`libraries/classes/Plugins/Transformations/TEMPLATE` and
 137 :file:`libraries/classes/Plugins/Transformations/TEMPLATE\_ABSTRACT` files for adding
 138 your own transformation plug-in. You can also generate a new
 139 transformation plug-in (with or without the abstract transformation
 140 class), by using
 141 :file:`scripts/transformations_generator_plugin.sh` or
 142 :file:`scripts/transformations_generator_main_class.sh`.
 143
 144 The applyTransformation() method always gets passed three variables:
 145
 146 #. **$buffer** - Contains the text inside of the column. This is the
 147    text, you want to transform.
 148 #. **$options** - Contains any user-passed options to a transform
 149    function as an array.
 150 #. **$meta** - Contains an object with information about your column. The
 151    data is drawn from the output of the `mysql\_fetch\_field()
 152    <https://www.php.net/mysql_fetch_field>`_ function. This means, all
 153    object properties described on the `manual page
 154    <https://www.php.net/mysql_fetch_field>`_ are available in this
 155    variable and can be used to transform a column accordingly to
 156    unsigned/zerofill/not\_null/... properties. The $meta->mimetype
 157    variable contains the original :term:`Media type` of the column (i.e.
 158    'text/plain', 'image/jpeg' etc.)