Text Iterator: Iterate over a text string for external processing

 Brute Force Search Class
 General Information - Documentation File


--- ABOUT THE CLASS ---

This class performs a brute force search and invokes the callback function for every single string which is generated by the class.

--- USING THE CLASS ---

In order to use the class, you need to do as the following:

1. Include the main class's file:
   [code]
        require_once("brute_force.class.php");
   [/code]

2. Create a new class:
   [code]
        $brute_force = new brute_force($callback, $min, $max[, $chars="all"]);
   [/code]

   Here is a small description about constructor's arguments:

   $callback:
   Is the name of callback function which will be invoked whenever a new string generated. You may use array("classname", "methodname") to invoke a class method (see http://de.php.net/call_user_func for more information)

   $min:
   Minimum characters to be used (*)

   $max:
   Maximum characters to be used (*)

   * - setting one value for both $min and $max arguments will cause the class to generate strings with the exact desired length. (See example1.php)

   $chars:
   Characters to be used in the search. Pre-defined values are:
        lower: lowercase characters
        upper: uppercase characters
        num: numbers (There is a great substitute for this! you may use "for" loops instead)
        alnum: lowercase characters, uppercase characters and numbers
        lalnum: lowercase characters and numbers
        ualnum: uppercase characters and numbers

    You may also want to define your desired characters. you should use array("l", "o", "r", "e", "m", ...); as the value of $chars.
    In this example we will see how we can pick 5 characters:
    [code]
        $chars = array("l", "o", "r", "e", "m");
        $brute_force = new brute_force($callback, $min, $max, $chars);
    [/code]

    $chars is case-insensitive.

    -- ! IMPORTANT ! --
        Remember that if you use array("lo", "rem", "ips", ...) as $chars value,
        class will behave them as they are single characters and output's length might vary depending on the maximum length of input characters.
        Even notice "" in here: array("n", ""); It will be behaved as a single character!

3. Starting the search
    [code]
        $brute_force->search();
    [/code]


--- USEFUL INFORMATION ---

a. callback_break option

   This is one of the most important options in this class;

   As purposes of searching might vary, sometimes you need only one string, and when it's found, searching process should be terminated;
   For example if you are searching for a md5 string,
   It's probably obvious that you need only one string!
   So, if you find the string, you do not need the rest of strings which are generated by the class, hence, you may terminate the search.
   Another example would be when you want to recover a password of a zip/rar archive, etc...
   In these situations, you should set callback_break to true
   And tell the callback function to return true, whenever the md5 string or the password found valid, to terminate the process.

   And sometimes, you need all of the strings;
   For example imagine you want to send emails to all Gmail users which their username is 6-length lowercase alphanumerical
   ------ [(*_*) Of course you do not want to do such a fictional thing :-D] ------
   Or when you want to find out how many md5 strings of your search result start with "n"!
   In these situations, you should set callback_break to false and let the class to finish the process.

   In order to change this option, do this when you created the class:
   [code]
       $brute_force->callback_break = true; //or false
   [/code]
   Default value for callback_break is false.

b. Callback invoking

   As you have understood, callback function acts the main role.
   When a string got generated, callback function will be invoked.
   So, you should know what is passing between the class and the callback function.
   Actually there are two things which are passed to the callback:
   1. Generated string as the first argument
       And
   2. Iteration; the number of current string. It indicates how many strings been generated since now!
   
c. Error handling

    Sometimes errors can happen, but you can handle them kindly, refer to the examples to find out how!
    
--- We're Done! ---