Squiz Labs Blog - The latest news from the R&D division of Squiz®

Subscribe to our RSS feeds

Squiz Matrix Newsletter #465

This week we have two new features to report, including a brand new Regular Expression keyword replacement. Continue reading below for more information on all this week's developments.

New Regular Expression Asset and Keyword Modifiers

Due for release in version 4.18.4 (March 3rd 2014)

This feature introduces the brand new Regular Expression asset to Squiz Matrix. The Regular Expression asset can be used to define a regular expression and replacement string pair, and can be used in conjunction with new regex keyword modifiers.

The Regular Expression asset 

The Details screen of the Regular Expression asset allows you to set the regular expression. If you want to create a replacement, this screen allow allows you to set a replacement string pair and a replacement limit.

The Details screen of the Regular Expression

The Regular Expression asset can be used in conjunction with the following new keyword modifiers:

  • preg_replace: replaces the regular expression value with the replacement set on the Regular Expression asset. This is the same functionality as the preg_replace() PHP function.
    %asset_contents^preg_replace:[REGEX_ASSETID]%
  • preg_match: returns a success/failure value if the regular expression matches the returned keyword value. This is the same functionality as the preg_match_all() PHP function.
    %asset_contents^preg_match:[REGEX_ASSETID]%
    In the above example, this keyword will return if no match is found in the contents of the asset. If a match is found, this keyword will return the number of matches, e.g. 2 for two matches.
    %asset_contents^preg_match:[REGEX_ASSETID]:Yes:No%
    In this example, the keyword will return No if no match is found, and Yes if any number of matches are found.
  • preg_match_result: returns regular expression matches on the returned keyword value as an array. This is the same functionality as the preg_match_all() PHP function, and should be used in conjunction with the array keyword modifiers.
    %asset_contents^preg_match_result:[REGEX_ASSETID]^as_json%
    The above example will return the matches array in the json format.

JS API: editMetadataSchema() and getMetadataSchema() Enhancements

Due for release in version 4.18.4 (March 3rd 2014)

The editMetadataSchema() and getMetadataSchema() functions on the JS API both take the assetid argument, where the asset ID of the Metadata Schema can be defined. This argument, however, is inconsistent with the majority of function on the JS API which take a similar asset_id parameter.

This minor enhancement modifies these functions to also accept the asset_id parameter, making them consistent with the rest of the JS API's functions. The previous assetid parameter will also continue to be supported to retain any existing functionality on your Squiz Matrix systems. 


Squiz Matrix Newsletter #464

Earlier this week, we released versions 4.16.7 and 4.18.3 of Squiz Matrix. Some of the great new features introduced in these releases included a new Input Type field for text type form questions; new keyword condition rules for checking visited pages, user entry pages and page referrers; enhancements to the Recreate Link Tree system script; and a new notification if the parse file of a design contains no design area tags

For more information, check out the release post her on the Squiz Labs blog.

---

This week we have three new enhancements to report, including a new parameter to sort select drop-down lists in the Squiz Matrix Administration interface. Continue reading below for more information on all this week's developments.

New sort_options Parameter for Select Drop-Down Lists in Admin Interface

Due for release in version 4.18.4 (March 3rd 2014)

This minor enhancement introduces a new sort_options parameter for selection attributes, to define whether the options available on select drop-down lists within the Squiz Matrix Administration interface should be sorted alphabetically.

Custom Form Select Drop-Down Sorted 

This parameter can be set in *_management.inc files of your system, where the selection attribute is defined, as follows:

'sort_options' => 1 

Currently, the sort_options parameter is only available for Custom Form assets, as defined in the form_management.inc file. It will soon be extended to other select attributes within Squiz Matrix.

JS File Folder and CSS File Folder Enhancements

Due for release in version 4.18.4 (March 3rd 2014)

Version 4.18.1 of Squiz Matrix saw the addition of two new assets: the JS File Folder and the CSS File Folder. These assets provided users with a platform for serving multiple JS and CSS files as single, packaged files. Very handy.  

This minor enhancement adds two new additions to these assets:

  • The ability to sort the linked JS/CSS files, using new navigation buttons in the Linked Files field. This is similar to question sorting in a Custom Form.
  • If linked files are merged without minification, then the individual file contents will now be separated by a new line in the merged file. This has been added so that, if one file ends with a comment, it will not comment out the statement in the next file, which was previously a potential issue.

The navigation buttons in the Linked Files field 

TRIM Saved Search: New Update on Empty Response Field

Due for release in version 4.18.4 (March 3rd 2014)

A new field has been added to the TRIM Saved Search asset to allow you to stipulate whether or not local TRIM records on your Squiz Matrix system should be updated and cleared if an empty response, or no response at all, is returned from the TRIM server.

The Update on Empty Response field can be configured on the Details screen of the TRIM Saved Search.

The Update on Empty Response field 

When this option is enabled, the TRIM Saved Search will clear any current local TRIM records if an empty response is returned. By default, this option is disabled, meaning that if an empty response is returned, any existing TRIM records will be retained.

This enhancement has been added in response to bug #6356, where when no records were found to sync, the previously synced records would still be retained, despite downloaded files no longer being available.


PHP_CodeSniffer 2.0.0 alpha1 released

I've just released the first alpha of PHP_CodeSniffer version 2.0.0. This update brings an often requested feature; the ability for PHP_CodeSniffer to automatically fix the problems that it finds. It also contains a complete rewrite of the comment parsing sniffs, finally removing what I feel is the poorest code in PHP_CodeSniffer; the comment parsing classes.

Fixing Errors Automatically with PHPCBF

PHP_CodeSniffer now comes with a second script; phpcbf, the PHP Code Beautifier and Fixer. This script piggy-backs off PHP_CodeSniffer to provide fixes for a lot of common errors. It will never fix 100% of the errors PHP_CodeSniffer finds as many require a developer to make a decision (e.g., can you use === here?) or may cause the code to execute differently if changed (e.g., uppercasing a constant name). But there are still a lot of errors that can be corrected without causing issues. Out of the 566 unique error messages that PHP_CodeSniffer can currently produce, version 2.0.0a1 is able to correct 202 of them automatically, which is about 35%. When you run PHP_CodeSniffer and get a report of the errors found, you will now be able to see which of those errors can be automatically corrected.

Along with this new script, PHP_CodeSniffer adds a new report type; the diff report. If you don't like the idea of PHP_CodeSniffer fixing errors automatically, you can instead ask it to output a diff of the fixes that it would make using the command line argument --report=diff. If you like what you see, you can simply change the phpcs command to phpcbf, leave all the command line options the same, and let PHP_CodeSniffer patch your files.

All this new functionality is documented on the wiki, and includes sample output, so please take a read: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Fixing-Errors-Automatically

Plugin for Sublime Text

I use Sublime Text 2 for development, as do some of the other developers at Squiz Labs. I've been working with one of these developers to build a plugin for Sublime Text that will run PHP_CodeSniffer on the current file, show which errors can be fixed automatically, fix the errors for you if you decide to have them fixed, and show a diff of what it did. I've added quite a few features to PHP_CodeSniffer to make this plugin feel as integrated as possible and I find it incredibly useful for tidying up my code before committing.

The plugin is still being documented, and made to work with Sublime Text 3 due to some issues with the diff library, but it will be released through Package Control as soon as they are worked out (or sooner, for ST2 only if needed). In the meantime, you can clone the repository yourself or just watch it for activity if you are interested in knowing when it is ready: https://github.com/squizlabs/sublime-PHP_CodeSniffer

Adding Fixes to Custom Sniffs

If you have your own custom sniffs and want to correct errors automatically, you need to make a couple of changes. The first thing you need to do is call the addFixableError() or addFixableWarning() methods instead of addErorr() and addWarning(), to let PHP_CodeSniffer know the error can be fixed. You can then make use of the new PHP_CodeSniffer_Fixer class to replace token values and add content to tokens, modifying the token stack as you go.

Here is a simple example, to ensure that comments don't appear at the end of a code line ($stackPtr is the comment token):

$error = 'Comments may not appear after statements';
$phpcsFile->addError($error, $stackPtr, 'Found');

The fix this, we just need to add a newline before the comment. Other sniffs will do things like fix alignment and spacing of the comment for us. It is also important we check if the fixer is enabled and if we are supposed to be fixing this specific error message. We end up with code like this:

$error = 'Comments may not appear after statements';
$fix   = $phpcsFile->addFixableError($error, $stackPtr, 'Found');
if ($fix === true && $phpcsFile->fixer->enabled === true) {
    $phpcsFile->fixer->addNewlineBefore($stackPtr);
}

If you are changing multiple tokens in a single fix, using a changeset will ensure that they are either all applied at once, or not applied at all. This is important if a partial change would lead to a parse error, or another equally bad outcome. In the following example, a changeset is used to ensure that all content between the array braces is removed, even if the content spans multiple lines. If one of the tokens to be removed has already been modified by another sniff, the whole changeset will be ignored and PHP_CodeSniffer will attempt to apply this changeset on a second run through the file.

$error = 'Empty declaration must have no space between parentheses';
$fix   = $phpcsFile->addFixableError($error, $stackPtr, 'SpaceFound');
if ($fix === true && $phpcsFile->fixer->enabled === true) {
    $phpcsFile->fixer->beginChangeset();
    for ($i = ($arrayStart + 1); $i < $arrayEnd; $i++) {
        $phpcsFile->fixer->replaceToken($i, '');
    }

    $phpcsFile->fixer->endChangeset();
}

Take a look at the PHP_CodeSniffer_Fixer class for all the methods you can use: https://github.com/squizlabs/PHP_CodeSniffer/blob/phpcs-fixer/CodeSniffer/Fixer.php

Removal of the Comment Parser

The other major change is the removal of the comment parsing classes. If you have written custom sniffs that either use the comment parsing classes or extend sniffs that do, you are going to need to review your sniffs and possibly rewrite them. This has already been done for all included sniffs, so there are quite a few examples to help you get started.

The best way to explain the change is to show an example of how PHP_CodeSniffer has changed the way it handles doc comments internally. If PHP_CodeSniffer is processing the following comment:

/**
 * PHP_CodeSniffer tokenises PHP code.
 *
 * @author    Greg Sherwood <gsherwood@squiz.net>
 * @copyright 2006-2012 Squiz Pty Ltd
 */

It would have previously tokenized it like this (spaces have been replaced by periods):

T_DOC_COMMENT => /**\n
T_DOC_COMMENT =>  * PHP_CodeSniffer.tokenises.PHP.code.\n
T_DOC_COMMENT =>  *\n
T_DOC_COMMENT =>  * @author....Greg.Sherwood.<gsherwood@squiz.net>\n
T_DOC_COMMENT =>  * @copyright.2006-2012.Squiz.Pty.Ltd\n
T_DOC_COMMENT =>  */

This format makes it very hard to look for specific things like a comment tag name, and makes it very hard to make fixes to the comment automatically. So PHP_CodeSniffer will now tokenize the comment like this:

T_DOC_COMMENT_OPEN_TAG => /**
T_DOC_COMMENT_WHITESPACE => \n
T_DOC_COMMENT_WHITESPACE => .
T_DOC_COMMENT_STAR => *
T_DOC_COMMENT_WHITESPACE => .
T_DOC_COMMENT_STRING => PHP_CodeSniffer.tokenises.PHP.code.
T_DOC_COMMENT_WHITESPACE => \n
T_DOC_COMMENT_WHITESPACE => .
T_DOC_COMMENT_STAR => *
T_DOC_COMMENT_WHITESPACE => \n
T_DOC_COMMENT_WHITESPACE => .
T_DOC_COMMENT_STAR => *
T_DOC_COMMENT_WHITESPACE => .
T_DOC_COMMENT_TAG => @author
T_DOC_COMMENT_WHITESPACE => ....
T_DOC_COMMENT_STRING => Greg.Sherwood <gsherwood@squiz.net>
T_DOC_COMMENT_WHITESPACE => \n
T_DOC_COMMENT_WHITESPACE => .
T_DOC_COMMENT_STAR => *
T_DOC_COMMENT_WHITESPACE => .
T_DOC_COMMENT_TAG => @copyright
T_DOC_COMMENT_WHITESPACE => .
T_DOC_COMMENT_STRING => 2006-2012.Squiz.Pty.Ltd
T_DOC_COMMENT_WHITESPACE => \n
T_DOC_COMMENT_WHITESPACE => .
T_DOC_COMMENT_CLOSE_TAG => */

As you can see, this is a significant number of extra tokens, but allows for much finer control over how a comment is processed. The T_DOC_COMMENT token has also been removed, replaced instead by T_DOC_COMMENT_OPEN_TAG. If you have a sniff listening for T_DOC_COMMENT, make sure you change it in your register() method and anywhere else it is used throughout your sniffs.

Here is a fairly complex example of a sniff rewrite; the Squiz FunctionComment sniff:

old: https://github.com/squizlabs/PHP_CodeSniffer/blob/master/...
new: https://github.com/squizlabs/PHP_CodeSniffer/blob/phpcs-fixer/...

And here is the commit of the changes required for the new comment tokenizer: https://github.com/squizlabs/PHP_CodeSniffer/commit/...

Essentially, instead of using the comment parser functions to get at tag values, you can use the standard PHP_CodeSniffer functions to navigate the token stack and look for what you need. This allows you to get a precise location of each piece of the comment and make fixes to it if you need to. You can also report more accurately on where an error has occurred.

Everything Else

Besides these major changes, there are a few important new features that have made it into version 2.0.0a1, including the ability to write your own custom report classes, the ability to set default command line argument values in ruleset XML files, and an easier way for custom sniff developers to skip through the token tree.

View the full 2.0.0a1 changelog at PEAR or Github

Stay up to date on all PHP_CodeSniffer changes, including new features and releases, by subscribing to the RSS feed or following me on Twitter.


Squiz Matrix Versions 4.16.7 and 4.18.3 Released

Our February releases of Squiz Matrix are available today. Squiz Matrix versions 4.16.7 and 4.18.3 each contain an array of great new features and enhancements.

Version 4.16.7 of Squiz Matrix is the latest release of our 4.16.x branch, launched mid last year. This release contains a new enhancement and twenty bug fixes.

Squiz Matrix 4.18.3 is the latest release of our 4.18.x branch, launched in October, last year. This release contains twelve new features and enhancements, as well as twenty-five bug fixes.  

Some of the functionality introduced in our 4.18.3 release include a new Input Type field for text type form questions; new keyword condition rules for checking visited pages, user entry pages and page referrers; enhancements to the Recreate Link Tree system script; and a new notification if the parse file of a design contains no design area tags

Please be sure to follow the relevant user guides when updating or installing your system. 


Squiz Matrix Newsletter #463

This week we have one new feature to report, a new Input Type field for the Custom Form's Text question type. Continue reading below for more information on all this week's developments.

New Input Type Field for Text Type Form Questions

Due for release in version 4.18.3 (February 1st 2014)

The Custom Form's Text question type allows users to enter a text response to the question via an input field. This field can be configured as a single line field, or a multiple line box.

Previously, the Text question type would print an input type of "text" within the source of a form.

This feature introduces a new option for Text question types, allowing you to apply HTML5 input elements within your forms.

The Input Type field can be configured in the Question Options section on the Details screen of a Text question type.

The new Input Type field

Users can select an input type in this field, to use on the form question. The options available include:

  • Color
  • Date
  • Datetime
  • Datetime-local
  • Email
  • Hidden
  • Month
  • Number
  • Range
  • Search
  • Text
  • Tel
  • Time
  • Url
  • Week

By default, the Text input type will be used for Text questions. Selecting an alternative input type in this field will print this within the source of the page.

<input-type="email">

This feature also extends to Text questions on other form types within Squiz Matrix, such as the E-Commerce Form Page and Default Delivery Method assets. 

View the Squizmap idea for this feature at https://squizmap.squiz.net/matrix/2545.


Squiz Labs

R & D division of Squiz Pty Ltd

Open source web experience management solutions

Squiz Labs is the research and development division of Squiz, the company behind the Squiz Suite of web experience management and development tools.

Our PHP and JavaScript developers are responsible for producing innovative enterprise-quality software while our interface designers and testing team ensure our products both look great and are easy to use.