%TOC%

---++ Analyzing a file
After you have [[http://www.program-transformation.org/PHP/PhpSatDocumentation#Installation][installed]] php-sat you can run it by typing:
<verbatim>
  php-sat -h
</verbatim>
If this command does not produce a list of all the options that are available for php-sat you should check your installation.

We will start with a simple file, _foo.php_ that contains an example of the bug-pattern [[%SVNROOT%/psat/php-sat/trunk/doc/correctness/C002_to-many-parameters.txt][C002]]:
<verbatim>
$ cat foo.php
<?php
  function foo($bar){
	  echo $bar;
  }

  foo("param1", "param2");
?>
</verbatim>

We can feed this to php-sat by using the =-i= option (we also use the =--extended-output= option to show the complete file again):
<verbatim>
$ php-sat -i foo.php --extended-output
<?php
  function foo($bar){
	 echo $bar;
  }
  /**
	* PHP-SAT check (Correctness)
	* Pattern ID : C002
	* Description: Too many parameters in function call
	*/
  foo("param1", "param2");
?>
</verbatim>

The output can also be saved into a file by giving the filename to the =-o= option:
<verbatim>
$ ls
foo.php
$ php-sat -i foo.php -o foo.php.php-sat --extended-output
$ ls
foo.php  foo.php.php-sat
$ cat foo.php.php-sat 
<?php
  function foo($bar){
	 echo $bar;
  }
  /**
	* PHP-SAT check (Correctness)
	* Pattern ID : C002
	* Description: Too many parameters in function call
	*/
  foo("param1", "param2");
?>

</verbatim>

---++ Analyzing multiple files
But what if we have this _foo-simple.php_:
<verbatim>
$ cat foo-simple.php
<?php
  include 'foo.inc';
 
  foo("param1", "param2");
?>
</verbatim>
this _foo-complex_.php:
<verbatim>
$ cat foo-complex.php
<?php
  $postfix = 'inc';
  include 'foo.'.$postfix;
 
  foo("param1", "param2");
?>
</verbatim>
and this _foo.inc_:
<verbatim>
$ cat foo.inc 
<?php
  function foo($bar){
	  echo $bar;
  }
?>
</verbatim>

The output of php-sat on _foo-simple.php_ would then be:
<verbatim>
$ php-sat -i foo-simple.php --extended-output
<?php
  include 'foo.inc';
  foo("param1", "param2");
?>
</verbatim>
and on _foo-complex.php_:
<verbatim>
$ php-sat -i foo-complex.php --extended-output
<?php
  $postfix = 'inc';
  include 'foo.' . $postfix;
  foo("param1", "param2");
?>
</verbatim>
which is still correct, php-sat only reports things it finds, so reporting nothing is still correct, but we would want php-sat to include the files that are included. There are two modes in which php-sat can include files, _simple_ and _complex_.

---+++ Simple inclusion
Simple inclusion means that php-sat will try to include _every_ file that is included by a _literal_ name. Every include/require/include_once/require_once statement that is followed by a literal string will be included if the file can be found. This mode does not respect the *_once-semantics, nor will it take into account concatenated names.

So the _php-simple.php_-problem can be solved by passing the =--simple-inclusion= flag to php-sat.
<verbatim>
$ php-sat -i foo-simple.php --simple-inclusion --extended-output
<?php
  include 'foo.inc';
  /**
	* PHP-SAT check (Correctness)
	* Pattern ID : C002
	* Description: Too many parameters in function call
	*/
  foo("param1", "param2");
?>
</verbatim>
This the same output as before, we could even use the =-o= option is we wanted. 

The output for _foo-complex.php_ is still not informative:
<verbatim>
$ php-sat -i foo-complex.php --simple-inclusion --extended-output
<?php
  $postfix = 'inc';
  include 'foo.' . $postfix;
  foo("param1", "param2");
?>
</verbatim>

---+++ Complex inclusion
Complex inclusions is not complex for the user, just for php-sat itself. This mode will trigger [[http://en.wikipedia.org/wiki/Constant_propagation][constant-propogation]] which will, as the name implies, propagate constant information through the scripts. This causes the complex mode to use more resources, but enables a larger set of analysis's.

This mode does respect the semantics of the *_once-statements, so files will only be included the first time they are encountered. 

The complex mode can be seen as an extension to the simple mode, every file that is included in the simple mode will also be included by the complex mode.

So the output for _foo-simple.php_ with the =--complex-inclusion= flag will be:
<verbatim>
$ php-sat -i foo-simple.php --complex-inclusion --extended-output
<?php
  include 'foo.inc';
  /**
	* PHP-SAT check (Correctness)
	* Pattern ID : C002
	* Description: Too many parameters in function call
	*/
  foo("param1", "param2");
?>
</verbatim>
and for _foo-complex.php_:
<verbatim>
$ php-sat -i foo-complex.php --complex-inclusion --extended-output
<?php
  $postfix = 'inc';
  include 'foo.' . $postfix;
  /**
	* PHP-SAT check (Correctness)
	* Pattern ID : C002
	* Description: Too many parameters in function call
	*/
  foo("param1", "param2");
?>
</verbatim>

---+++ Printing included files
In real world situation the included files could also contain bug-patterns. These patterns can either be static, always available in the source file, or dynamic, available under certain inclusion-conditions. It is useful to examine the included files after they are included to check for these patterns. <br />
The default behavior for included files is that they are discarded from the memory after the analysis. This behavior can be altered by passing the =--print-included-files= flag. This flag will print _all_ included files to the same location as the original files, giving them a =php-sat=-postfix.

Here is a little example with simple inclusion. We have the same files as before:
<verbatim>
$ ls
foo-simple.php foo-complex.php foo.php foo.inc
</verbatim>

When we use php-sat with a target we get one extra file with a result:
<verbatim>
$ php-sat -i foo-simple.php -o foo-simple.php.php-sat --simple-inclusion --extended-output
$ ls
foo-simple.php foo-complex.php foo.php foo.inc foo-simple.php.php-sat
</verbatim>

Passing =--print-included-files= will give yet another extra file with a result:
<verbatim>
$ php-sat -i foo-simple.php -o foo-simple.php.php-sat --simple-inclusion --print-included-files --extended-output
$ ls
foo-simple.php foo-complex.php foo.php foo.inc foo-simple.php.php-sat foo.inc.php-sat
</verbatim>

---++ Interpreting the output
Please take a look at the [[PhpSatBugPatterns][bug-patterns section]] to find out how the results should be interpreted.