Introduction

This page provides some information that may be relevant to developers hoping to improve the Beautifier module.

Why this page is of no use

There is no ready to use script that define php_beautifier package to cleanup a code and just do it.

How Beautifier works

The Beautifier module uses a format preset to apply a list of changes to source code that is input via the textarea or file upload field. The format presets are basically config settings to allow compliance with such paradigms as Drupal coding standards or Zend framework coding standards (these two examples pertain specifically to PHP source code), and the idea is that you should be able to configure Beautifier to work however you want by choosing an appropriate preset which represents the coding standard or style guide for your organisation.
Each preset is configured by supplying a list of functions that the source code must be put through.

Adding more presets

Implement hook_beautifer_presets() to enable more presets in Beautifier. Your implementation will return an array where the keys are the type of code you wish to deal with (e.g. 'php', or 'css' etc...) and the value is an array of presets keyed by the computer-safe name of the preset. Each preset is an array with keys: '#title', '#url', and '#functions'.
#title - Display title of the preset.
#url - Url of webpage with more information.
#functions - An array of function identifiers (as given by hook_beautifier_functions()).

<?php
/**
 * Implementation of hook_beautifier_presets().
 */
function example_beautifier_presets() {
  return array(
    'php' => array(
      'example' => array(
        '#title' => t('Example coding standards'),
        '#url' => 'http://drupal.org/coding-standards',
        '#functions' => array(  // the order of these is significant
          'beautifier_line_breaks_win',
          'beautifier_line_breaks_mac',
          'beautifier_opening_php_full',
          'beautifier_switch_exit',
          array(
            'beautifier_php' => array(
              'beautifier_php_open_tag_indent_two_spaces',
              'beautifier_php_close_brace_pre_space',
              'beautifier_php_semi_break',
            ),
          ),
          'beautifier_cvs_id',
          'beautifier_multiple_vars',
          'beautifier_curly_braces',
          'beautifier_insert_cvs_id',
          'beautifier_remove_closing_php',
          'beautifier_trim',
          'beautifier_append_two_lines',
        ),
      ),
    ),
  );

}
?>

You can also manipulate presets created by other modules with hook_beautifier_presets_alter(&$presets).

Adding more functions

Implement hook_beautifier_functions() to enable more functions in Beautifier. Your implementation must return an array, where the keys are the names of functions, and the values are arrays of data describing the function. At the very least this data array must contain a #title parameter for display output. You may specify #arguments to append parameters to the default $code string parameter given to the function. #path and #file are used to load an include file before executing the function, and if you supply #function then the value will be used as the function to execute instead of the array key.
#subfunctions supplies a nested list of functions compatible with this function. The functions listed under #subfunctions do not require the #arguments attribute as beautifier.module does not directly use those functions - they are handled internally by the #process function.

<?php
/**
 * Implementation of hook_beautifier_functions().
 */
function example_beautifier_functions() {
  return array(
    'example_foo_to_bar' => array(
      '#title' => t('Convert every second foo to bar.'),
      '#arguments' => array('limit' => 0),  //optional
      '#function' => 'another_modules_foo_to_bar_converter', // optional, defaults to key name
    ),
    'beautifier_line_breaks_mac' => array(
      '#title' => t('Convert Macintosh line breaks to Unix format.'),
    ),
    'beautifier_php' => array(
      '#title' => t('Format code according to PHP rules.'),
      '#file' => 'beautifier.php.inc',
      '#path' => drupal_get_path('module', 'beautifier'),
      '#subfunctions' => array(  // here are the subroutines that this process supports.
        'beautifier_php_open_brace_pre_space' => array(
          '#title' => t('Add a space before "{".'),
        ),
        'beautifier_php_open_brace_post_space' => array(
          '#title' => t('Add a space after "{".'),
        ),
      ),
    ),
  );
}
?>

You can also manipulate presets created by other modules with hook_beautifier_presets_alter(&$functions).

Types of functions

There are a few different approaches to creating functions for use with Beautifier.

  • Simple function

    Function takes $code as input, and returns $code after some custom modification.

    <?php
    function beautifier_trim($code = '') {
      // Remove surrounding whitespace.
      $code = trim($code);
      return $code;
    }
    ?>
    
  • Search and replace function

    Create array with keys '#search' and '#replace' and values are regular expressions. Use beautifier_replace() to process the search/replace.

    <?php
    function beautifier_opening_php_full($code = '') {
      $task = array(
        '#search' => '@<\?(\s)@',
        '#replace' => "<?php$1",
      );
      return beautifier_replace($code, $task);
    }
    ?>
    
  • Search and 'replace callback' function

    Create array with keys '#search' and '#replace_callback'. '#search' value is regular expression, '#replace_callback' value is a function name. Use beautifier_replace() to process the search/replace. See beautifier_multiple_vars() for an example.

  • Process function

    A function that steps through the code tokens as a parser would, and makes calls to functions listed in #subfunctions to handle specific changes. Takes a list of #subfunctions as second parameter. See beautifier_php() for an example. In the PHP implementation of Beautifier there is only a single process function, as it is not required to tokenize the code more than once.

  • Subfunction

    This is a custom function that uses a main process function as a sort of API to handle changes to tokens in the code. See how beautifier_php() interacts with the other functions in beautifier.php.inc for an example. These functions usually make direct changes to the current token, the code directly before the token, or to some other data being tracked either by the parent process function or other subfunctions functions.

  • Message function

    A function doesn't have to change anything in the source code. It could just do something like this: <?php drupal_set_message(t("some output"), 'beautifier warning'); ?>. Note; the use of 'beautifier warning' instead of 'warning' or 'error' to ensure the message appears as part of Beautifier, you can also use 'beautifier status', and 'beautifier error' to take on the appropriate CSS style, or just 'beautifier' for the leading white messages. This could be useful for telling a user their style of syntax is incorrect in a situation where you don't have the algorithm to fix the user's source code, or to give some other feedback about your functions' status.

Apart from the #subfunctions (which can adhere to a custom specification set by your process function), all functions should take $code as the first parameter, and return $code at the end (whether modified or not).

beautifier_php()

This section refers to the default PHP process function in beautifier.php.inc: beautifier_php(). It may help in either creating more subfunctions for it, or help you model a new kind of beautifier such as beautifier_xml() or beautifier_css().

The function beautifier_php() takes $code and $functions as parameters, splits the $code into PHP tokens, and parses each token through the entire list of $functions (using helper function beautifier_php_token()). The $functions check for the correct incoming referenced data, and make changes to the data.
Specifically beautifier_php() tracks the following values:
$id - the latest token's ID (either a simple string character - or php constant)
$text - the actual text in the token
$result - string where beautifier_php_token() appends the latest token $text after feeding it through all the $functions.
$c - An array of internal control tracker variables for various purposes, a lot of very useful values here, feel free to add your own variables to track.
You can make changes to any of these with the subfunctions, but remember at the end of the process for that token, whatever is left in $text will be appended to $result and eventually returned as $code.
The function beautifier_php_token() also adds it's own subfunctions (a 'pre' and a 'post' function) to help in tracking the internal $c variables.