CONTENTS OF THIS FILE
---------------------
* Introduction
* Prerequisites
* Installation
* Usage
* Modules
	- Hash Module
	- Database Module
	- Standard Module
	- String Module
	- Time Module


INTRODUCTION
-----------
		PHP PGO Training scripts were created as a representative execution
	pattern for real life PHP applications like WordPress, MediaWiki or Drupal.
	When executed during the training phase of a PGO (Profile Guided
	Optimization) build process these scripts will provide similar statistics
	as if the PGO training was performed with the real life application.
		The advantage of using these scripts instead of real applications
	is that they are easily portable and they don't need complex installation
	steps as for real live use cases. The only one dependency is on MySQL. In
	consequencei, the scripts can be easily integrated directly in source
	ditribution packages of Zend PHP or HHVM in order to offer transparent
	support for PGO builds.
		The current version tries to reproduce Wordpress execution behavior.
	Tested for PGO builds of PHP7 using GCC 5.0, it delivered half of the
	performance speedups obtained during PGO builds trained with the real
	applications. It was tested for:
	- Wordpress 4.2.2: ~3.5% speedup
	- Drupal 7.36: ~2% speedup
	- MediaWiki 1.23.9: ~1.5% speedup


PREREQUISITES
-------------
		PHP PGO Training Scripts assume you want to build optimized PHP/HHVM
	binaries from scratch following the Profile Guided Optimization build process.
	Here is the list of prerequisites:
	- prerequisites of building PHP7/HHVM binaries from scratch (see build
	  documentation on PHP7/HHVM for more details)
	- a C/C++ compiler supporting profile guided optimized builds. We used GCC 5.0
	- a MySQL server installed, if database operations are targeted for training


INSTALLATION
------------
		Copying the PHP PGO training scripts in a folder is enough if you are
	not interested in training database accesses. Otherwise, you shall also:
	1. Configure access credentials to MySQL server. Edit 'constants.php' file
	   and document the following fields:
	   - DB_USER: name of a valid database user
	   - DB_PASSWORD: password of the database user
	   - DB_HOST: the datatabse host to be used for training
	   - DB_NAME: name of the database to be created and used for training
	2. Install the training database on the MySQL server; you can rerun this
	   script whenever you want to bring the database to it's initial state:
	     $ php /path/to/php_pgo_training_scripts/init.php

USAGE:
------
		The entry point for executing the entire bunch of scripts is 'index.php'.
	For reproducing closely a real live execution scenario where we assume a HTTP
	server is loading and compiling once the PHP scripts and executes them many
	times, we need to reduce the weight of the compilation phase during the training
	execution. The following command was good enough for this purpose:
	     $ php-cgi -T100 /path/to/php_pgo_training_scripts/index.php
	Of course, we assumed 'opcache' enabled in case of PHP7.

		The following steps are an example on how to perform a PGO build on
	PHP7 using these training scripts:
	     $ cd /path/to/php-src
	     $ ./configure ...  # see PHP installation details for more info
	     $ make prof-gen    # builds instrumented binaries for execution statistcs
	                        # gathering
	     $ ./sapi/cgi/php-cgi -T100 /path/to/php_pgo_training_scripts/index.php
	     $ make prof-clean  # cleans up the project but preserves
	                        # gathered statistics
	     $ make prof-use    # rebuilds binaries based on gathered statistics
	     $ sudo make install

		For executiong all training scenarios the following PHP extensions
	shall be enabled in PHP during the initial configuration phase:
	  - standard
	  - mysqli
	  - mbstring
	  - pcre
	  - date
	If one of the above extensions is not found at runtime the scripts will
	 skip the associated trainings and will issue a warning message.


Modules
-------

    +--------+     +----------+     +----------+     +----------+     +------+
    +  HASH  +<--->+ DATABASE +<--->+ STANDARD +<--->+  STRING  +<--->+ TIME +
    +--------+     +----------+     +----------+     +----------+     +------+                     

		At top level of each module you can find constants that controls
	the number of iterations for each basic training. These constants were
	empirically set based on observations on Wordpress execution pattern.
	If you need to change the relative weight between different kind of loads,
	they can be adjusted depending on needs.

	1. Hash Module(dictionary.php): A set of 50 keys is used to store and increment
	values in an array.

	2. Database Module(db.php): A database connection is created and a series of
	queries are done(from simple select * from table to updates and select
	with joins). The database is created using init.php and its content is
	some random generated data. The tables format is similar to WordPress
	tables format.

	3. Standard Module(standard_calls.php): The following functions are called
	inside this module:
		error_reporting(E_ERROR | E_WARNING | E_PARSE);
		array_walk($test_array, 'do_nothing');
		krsort($test_array);
		ksort($test_array);
		parse_str($var1);
		end($test_array);
		reset($test_array);
		array_shift($test_array);
		array_pop($test_array);
		array_diff($test_array1, $test_array);
		extract($test_array, EXTR_PREFIX_SAME, "wddx");
		version_compare(phpversion(), '5.5', '>=');
		fread($file,"1024");
		fclose($file);

	4. String Module(string.php): All common string operations are done on an
	array containing 6 strings:
		preg_replace
		preg_replace_callback
		str_replace
		str_split
		md5
		trim
		implode
		mb_check_encoding

	5. Time Module(time.php): Calls strtotime and date using different formats.