MoodleDocs - User contributions [en]

Hackfest UK 2014/Email Logging

2014-04-29T11:54:53Z

Davidaylmer:

'''Message Logging and Reporting'''

*Contact Names: (please add name if interested)
*Larry Zoumas (larry(dot)zoumas@xtractor.se)
*Martin Sandberg (martin(dot)sandberg@xtractor.se)
*David Aylmer (david(d)aylmer(a)floream(d)com)
*Rob Hardy (r(dot)hardy(at)yorksj(dot)ac(dot)uk)
*Marcus Green (m(dot)green(at)yorksj(dot)ac(dot)uk)

'''Description'''
*This plugin will allow admins and teachers to search through messages sent to users. The purpose is to easily answer the question of whether or not a user was notified of an important event, such as a face-to-face session, quiz deadline, etc.

'''Notes:'''
*Not all emails go through the messaging system. This needs to be investigated and fixed.
*We might want to allow a place for developers to add hooks or decorate this functionality.
*We are not sure how this will work with email digests. We should probably log when the digest email goes out.

'''Email functions not using the messaging system'''
*Self Enrolment Enrolment plugin (core)
*moodle account being locked out after multiple invalid login attempts. (lockoutemailbody) (core)
*When a badge has been awarded (core)
*Emailing admins about failed login attempts (core)
*To alert support email if log table can not be written into (core)
*Welcome emails (core)
*Password reset (core)
*Confirmation email activation link (core)
*Confirmation two (emailpasswordconfirmation) (core)
*Password change is disabled email (core)
*When using the email message output plugin (core)
*When sending forum digests (forum cron - core)
*Journal mod (journal cron -core)
*When oublogs are moderated and require confirmation by the author (core)
*If user changes email address confirmation is required (core)
NOTE: Many third party (moodle partner) add-ons will use direct calls to email_to_user. This function should be better encapsulated in regards to information hiding design principles.

'''Capabilities''':
*Can view own messages
*Can view other messages
*Can view messages in your courses (teacher)
*Can view message body information

'''Options''':

*Optionally log body of message

'''Proposed Table Schema'''

'''messaging_log'''
*id
*from (user_id)
*from_address (email address or identifier when the message was sent)
*message_type (FK mdl_message_provider)
*moduleid
*courseid
*subject
*body_id
*time

'''messaging_log_user'''
*id
*message_log_id (FK to messaging log)
*userid
*to_address (email address or identifier when the message was sent)
*time
*status

'''messaging_log_body'''
*id
*body_text
*file_id (FK to mdl_files to see attachment size, etc)
*email_headers (if any)
*message_format (html or text)

[[Image:moodle_message_log.png|ER diagram of tables]]

'''Reporting'''
Output headings suggested order (left to right)
*Message type
*Course category (with link to category)
*Course (with link to course)
*Component/module (with link to mod e.g. forum post/discussion etc)
*Peview body link (html/text)
*Sender Fullname (link to profile)
*Recipient Fullname (with link to profile)
*Recipient email/jabberid/mobile phoine number/etc sent to
*subject
*time sent
*status (success)

'''filters'''
*Download as spreadsheet
*Paging number of users
*Filter by course
*Filter by activity
*Filter by user
*Filter by message_type
*Filter by sent datetime
*Filter by subject

'''Tracker issue'''

[https://tracker.moodle.org/browse/MDL-45160 Extend messaging system to log messages sent...]

Hackfest UK 2014/Email Logging

2014-04-17T12:15:22Z

Davidaylmer:

'''Message Logging and Reporting'''

*Contact Names: (please add name if interested)
*Larry Zoumas (larry(dot)zoumas@xtractor.se)
*Martin Sandberg (martin(dot)sandberg@xtractor.se)
*David Aylmer (david(d)aylmer(a)floream(d)com)
*Rob Hardy (r(dot)hardy(at)yorksj(dot)ac(dot)uk)
*Marcus Green (m(dot)green(at)yorksj(dot)ac(dot)uk)

'''Description'''
*This plugin will allow admins and teachers to search through messages sent to users. The purpose is to easily answer the question of whether or not a user was notified of an important event, such as a face-to-face session, quiz deadline, etc.

'''Notes:'''
*Not all emails go through the messaging system. This needs to be investigated and fixed.
*We might want to allow a place for developers to add hooks or decorate this functionality.
*We are not sure how this will work with email digests. We should probably log when the digest email goes out.

'''Capabilities''':
*Can view own messages
*Can view other messages
*Can view messages in your courses (teacher)
*Can view message body information

'''Options''':

*Optionally log body of message

'''Proposed Table Schema'''

'''messaging_log'''
*id
*from (user_id)
*from_address (email address or identifier when the message was sent)
*message_type (FK mdl_message_provider)
*moduleid
*courseid
*subject
*body_id
*time

'''messaging_log_user'''
*id
*message_log_id (FK to messaging log)
*userid
*to_address (email address or identifier when the message was sent)
*time
*status

'''messaging_log_body'''
*id
*body_text
*file_id (FK to mdl_files to see attachment size, etc)
*email_headers (if any)
*message_format (html or text)

[[Image:moodle_message_log.png|ER diagram of tables]]

'''Reporting'''
Output headings suggested order (left to right)
*Message type
*Course category (with link to category)
*Course (with link to course)
*Component/module (with link to mod e.g. forum post/discussion etc)
*Peview body link (html/text)
*Sender Fullname (link to profile)
*Recipient Fullname (with link to profile)
*Recipient email/jabberid/mobile phoine number/etc sent to
*subject
*time sent
*status (success)

'''filters'''
*Download as spreadsheet
*Paging number of users
*Filter by course
*Filter by activity
*Filter by user
*Filter by message_type
*Filter by sent datetime
*Filter by subject

'''Tracker issue'''

[https://tracker.moodle.org/browse/MDL-45160 Extend messaging system to log messages sent...]

Hackfest UK 2014/Email Logging

2014-04-17T12:13:14Z

Davidaylmer:

'''Message Logging and Reporting'''

*Contact Names: (please add name if interested)
*Larry Zoumas (larry(dot)zoumas@xtractor.se)
*Martin Sandberg (martin(dot)sandberg@xtractor.se)
*David Aylmer (davidaylmer(a)hotmail.com)
*Rob Hardy (r(dot)hardy(at)yorksj(dot)ac(dot)uk)
*Marcus Green (m(dot)green(at)yorksj(dot)ac(dot)uk)

'''Description'''
*This plugin will allow admins and teachers to search through messages sent to users. The purpose is to easily answer the question of whether or not a user was notified of an important event, such as a face-to-face session, quiz deadline, etc.

'''Notes:'''
*Not all emails go through the messaging system. This needs to be investigated and fixed.
*We might want to allow a place for developers to add hooks or decorate this functionality.
*We are not sure how this will work with email digests. We should probably log when the digest email goes out.

'''Capabilities''':
*Can view own messages
*Can view other messages
*Can view messages in your courses (teacher)
*Can view message body information

'''Options''':

*Optionally log body of message

'''Proposed Table Schema'''

'''messaging_log'''
*id
*from (user_id)
*from_address (email address or identifier when the message was sent)
*message_type (FK mdl_message_provider)
*moduleid
*courseid
*subject
*body_id
*time

'''messaging_log_user'''
*id
*message_log_id (FK to messaging log)
*userid
*to_address (email address or identifier when the message was sent)
*time
*status

'''messaging_log_body'''
*id
*body_text
*file_id (FK to mdl_files to see attachment size, etc)
*email_headers (if any)
*message_format (html or text)

[[Image:moodle_message_log.png|ER diagram of tables]]

'''Reporting'''
Output headings suggested order (left to right)
*Message type
*Course category (with link to category)
*Course (with link to course)
*Component/module (with link to mod e.g. forum post/discussion etc)
*Peview body link (html/text)
*Sender Fullname (link to profile)
*Recipient Fullname (with link to profile)
*Recipient email/jabberid/mobile phoine number/etc sent to
*subject
*time sent
*status (success)

'''filters'''
*Download as spreadsheet
*Paging number of users
*Filter by course
*Filter by activity
*Filter by user
*Filter by message_type
*Filter by sent datetime
*Filter by subject

'''Tracker issue'''

[https://tracker.moodle.org/browse/MDL-45160 Extend messaging system to log messages sent...]

Hackfest UK 2014/Email Logging

2014-04-17T11:46:17Z

Davidaylmer:

'''Message Logging and Reporting'''

*Contact Names: (please add name if interested)
*Larry Zoumas (larry.zoumas@xtractor.se)
*Martin Sandberg (martin.sandberg@xtractor.se)
*David Aylmer (davidaylmer(a)hotmail.com)
*

'''Description'''
*This plugin will allow admins and teachers to search through messages sent to users. The purpose is to easily answer the question of whether or not a user was notified of an important event, such as a face-to-face session, quiz deadline, etc.

'''Notes:'''
*Not all emails go through the messaging system. This needs to be investigated and fixed.
*We might want to allow a place for developers to add hooks or decorate this functionality.

'''Capabilities''':
*Can view own messages
*Can view other messages
*Can view messages in your courses (teacher)
*Can view message body

'''Options''':

*Optionally log body of message

'''Proposed Table Schema'''

'''messaging_log'''
*id
*from (user_id)
*from_address (email address or identifier when the message was sent)
*message_type (FK mdl_message_provider)
*moduleid
*courseid
*subject
*body_id
*time

'''messaging_log_user'''
*id
*message_log_id (FK to messaging log)
*userid
*to_address (email address or identifier when the message was sent)
*time
*status

'''messaging_log_body'''
*id
*body_text
*message_attachment_id (FK to file)
*email_headers (if any)
[[Image:moodle_message_log.png|ER diagram of tables]]

'''Reporting'''
*Filter by course
*Filter by activity
*Filter by user
*Filter by message_type
*Filter by sent datetime
*Filter by subject

Common unit test problems

2013-08-21T14:16:44Z

Davidaylmer: /* !!! Error reading from database !!!!! Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier. */

=== Unit tests are taking more than 10 mins to run ===
This problem is under investigation. We are hoping to find the soluton. On a typical system all tests complete in under 6 mins.--[[User:Dan Poltawski|Dan Poltawski]] 12:43, 15 May 2012 (WST)

You maybe find much better performance on psql as a workaround for now if not doing DB dependent tests.

If using linux on an EXT4 file system, disabling barriers by adding barrier=0 to the end of the options in /etc/fstab for the drive should offer HUGE speed improvements. Note that this is very dangerous for system stability and in the event of a power failure can cause permanent and irrecoverable data loss.

=== dml_testcase::test_unique_index_collation_trouble===
"Unique index is accent insensitive, this may cause problems for non-ascii languages. This is usually caused by accent insensitive default collation."
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_bin collation.

=== dml_testcase::test_sql_binary_equal ===
"SQL operator "=" is expected to be case sensitive Failed asserting that 1 matches expected 2."
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_bin collation.

=== moodlesimplepie_testcase::test_getfeed ===
"Failed to load the sample RSS file. Please check your proxy settings in Moodle. %s"
==== Solution ====
Your moodle needs network connectivity, please check proxy settings.

=== moodlesimplepie_testcase::test_redirect ===
Failed asserting that 'cURL Error: Operation timed out after 2000 milliseconds with 0 bytes received' is null.
==== Solution ====
Your moodle needs network connectivity, please check proxy settings

=== collatorlib_testcase::test_asort_objects_by_method ===
Collation aware sorting not supported, PHP extension "intl" is not available.
==== Solution ====
Install php intl extension.

Note that, on Windows, this extension does not seem to be included in the installer, but you can get it by downloading the zip, and copying the right DLLs across. If you Google, there are more detailed instructions on Stack Exchange.

=== grading_manager_testcase::test_tokenize===
A test using UTF-8 characters has failed. Consider updating PHP and PHP's PCRE or INTL extensions (MDL-30494) Failed asserting that false is true.
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_bin collation.

=== moodlelib_testcase::test_fix_utf8 ===
Failed asserting that false is identical to 'aaabbb'.
==== Solution ====
This problem indicates buggy iconv. See [http://tracker.moodle.org/browse/MDL-33007] for discussion. So this is a real problem, to be fixed in a future integration cycle

=== Segfaults on Oracle ===
When I was running tests on oracle I was getting phpunit sefaulting.. --[[User:Dan Poltawski|Dan Poltawski]] 00:29, 16 May 2012 (WST)
==== Solution ====
Set statement_cache_size in php.ini:
oci8.statement_cache_size = 0

=== filestoragelib_testcase::test_get_file_preview ===
Failed asserting that false is an instance of class "stored_file".
==== Solution ====
Unfortunately, the php GD extension is a requirement for this test (see MDL-36447).

Go to your Moodle directory and type 'php admin/tool/phpunit/cli/util.php --drop', then reinitialise PHPunit and run the test again.

=== PHP Warning: include_once(PHPUnit/Extensions/Database/Autoload.php): failed to open stream ===
This occurs on Mac installs from experience. The reason this occurs is because DBUnit was not installed during the PHPUnit installation via PEAR.
==== Solution ====
In terminal type: sudo pear install -f phpunit/DbUnit

=== !!! Error reading from database !!!!! Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier. ===
If running unit tests under FreeTDS, remember that without a valid FREETDS environment variable, PHP won't be able to find the freetds.conf file and will default to version 5.0 which has poor support for unicode collations.
==== Solution ====
Ensure a FREETDS environment variable is set prior to running the automated tests, which points to a valid path that contains a freetds.conf file. Also ensure the tds version element is set to a recent enough version (8.0)
Note: Another potential solution may be to set TDSVER (http://freetds.schemamania.org/userguide/freetdsconf.htm)
[[Category:Unit testing]]

Common unit test problems

2013-08-21T14:10:44Z

Davidaylmer:

=== Unit tests are taking more than 10 mins to run ===
This problem is under investigation. We are hoping to find the soluton. On a typical system all tests complete in under 6 mins.--[[User:Dan Poltawski|Dan Poltawski]] 12:43, 15 May 2012 (WST)

You maybe find much better performance on psql as a workaround for now if not doing DB dependent tests.

If using linux on an EXT4 file system, disabling barriers by adding barrier=0 to the end of the options in /etc/fstab for the drive should offer HUGE speed improvements. Note that this is very dangerous for system stability and in the event of a power failure can cause permanent and irrecoverable data loss.

=== dml_testcase::test_unique_index_collation_trouble===
"Unique index is accent insensitive, this may cause problems for non-ascii languages. This is usually caused by accent insensitive default collation."
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_bin collation.

=== dml_testcase::test_sql_binary_equal ===
"SQL operator "=" is expected to be case sensitive Failed asserting that 1 matches expected 2."
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_bin collation.

=== moodlesimplepie_testcase::test_getfeed ===
"Failed to load the sample RSS file. Please check your proxy settings in Moodle. %s"
==== Solution ====
Your moodle needs network connectivity, please check proxy settings.

=== moodlesimplepie_testcase::test_redirect ===
Failed asserting that 'cURL Error: Operation timed out after 2000 milliseconds with 0 bytes received' is null.
==== Solution ====
Your moodle needs network connectivity, please check proxy settings

=== collatorlib_testcase::test_asort_objects_by_method ===
Collation aware sorting not supported, PHP extension "intl" is not available.
==== Solution ====
Install php intl extension.

Note that, on Windows, this extension does not seem to be included in the installer, but you can get it by downloading the zip, and copying the right DLLs across. If you Google, there are more detailed instructions on Stack Exchange.

=== grading_manager_testcase::test_tokenize===
A test using UTF-8 characters has failed. Consider updating PHP and PHP's PCRE or INTL extensions (MDL-30494) Failed asserting that false is true.
==== Solution ====
Your Database is incorrectly configured. You probably are running MySQL and need to switch to utf8_bin collation.

=== moodlelib_testcase::test_fix_utf8 ===
Failed asserting that false is identical to 'aaabbb'.
==== Solution ====
This problem indicates buggy iconv. See [http://tracker.moodle.org/browse/MDL-33007] for discussion. So this is a real problem, to be fixed in a future integration cycle

=== Segfaults on Oracle ===
When I was running tests on oracle I was getting phpunit sefaulting.. --[[User:Dan Poltawski|Dan Poltawski]] 00:29, 16 May 2012 (WST)
==== Solution ====
Set statement_cache_size in php.ini:
oci8.statement_cache_size = 0

=== filestoragelib_testcase::test_get_file_preview ===
Failed asserting that false is an instance of class "stored_file".
==== Solution ====
Unfortunately, the php GD extension is a requirement for this test (see MDL-36447).

Go to your Moodle directory and type 'php admin/tool/phpunit/cli/util.php --drop', then reinitialise PHPunit and run the test again.

=== PHP Warning: include_once(PHPUnit/Extensions/Database/Autoload.php): failed to open stream ===
This occurs on Mac installs from experience. The reason this occurs is because DBUnit was not installed during the PHPUnit installation via PEAR.
==== Solution ====
In terminal type: sudo pear install -f phpunit/DbUnit

=== !!! Error reading from database !!!!! Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier. ===
If running unit tests under FreeTDS, remember that without a valid FREETDS environment variable, PHP won't be able to find the freetds.conf file and will default to version 3.7 which has poor support for unicode collations.
==== Solution ====
Ensure a FREETDS environment variable is set prior to running the automated tests, which points to a valid path that contains a freetds.conf file. Also ensure the tds version element is set to a recent enough version (8.0)

[[Category:Unit testing]]

Acceptance testing

2013-07-30T19:43:52Z

Davidaylmer: /* Links */

== Introduction ==
This page describes how we describe Moodle's functionalities and how we automatically test all of them.

Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate users interactions.

For technical info: [[Behat integration]]

=== How it works ===
Behat parses and executes features files which describes Moodle's features (for example ''Post in a forum''), each feature file is composed by many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed by steps (for example ''I press "Post to Forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into an PHP method and is executed.

This features are executed nightly in the HQ servers with all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and test new functionalities.

=== Examples ===

* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:
@auth
'''Feature''': Login
In order to login
As a moodle user
I need to be able to validate the username and password against moodle

'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

'''Scenario''': Login as an unexisting user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.

These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:

@mod @mod_forum
'''Feature''': Add forum activities and discussions
In order to discuss topics with other users
As a moodle teacher
I need to add forum activities to moodle courses

'''Scenario''': Add a forum and a discussion
'''Given''' the following "users" exists:
| username | firstname | lastname | email |
| teacher1 | Teacher | 1 | teacher1@asd.com |
'''And''' the following "courses" exists:
| fullname | shortname | category |
| Course 1 | C1 | 0 |
'''And''' the following "course enrolments" exists:
| user | course | role |
| teacher1 | C1 | editingteacher |
'''And''' I log in as "teacher1"
'''And''' I follow "Course 1"
'''And''' I turn editing mode on
'''And''' I add a "Forum" to section "1" and I fill the form with:
| Forum name | Test forum name |
| Forum type | Standard forum for general use |
| Description | Test forum description |
'''When''' I add a new discussion to "Test forum name" forum with:
| Subject | Forum post subject |
| Message | This is the body |
'''Then''' I should see "Test forum name"

Note that:

* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.

== Quick start ==

This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.

To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.

# Open a command line interface
# '''cd /to/your/moodle/dirroot'''
# Edit config.php adding the following lines before the lib/setup.php include
#: <code language="text">$CFG->behat_prefix = 'b_';
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';
$CFG->behat_switchcompletely = true;
</code>
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)
# '''php admin/tool/behat/cli/init.php'''
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example
# Browse to your $CFG->wwwroot, this is an empty test site and it is reset before each test (called scenario)
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)
# To 'add a blog entry' we need to:
## Log in the system as a valid user
## Expand 'My profile' node of the navigation block
## Expand the 'Blogs' node of the navigation block
## Follow he 'Add a new entry' link
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'
## Press the 'Save changes' button
## Verify you see the values you entered in the form and verify you are not in the form page
# This translated to steps is:
#: <code language="text">Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "Blog entries"
And I should see "I'm the description"
And I should not see "Required"
</code>
# We need to wrap this steps following the behaviour driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)
#: <code language="text">
@core @core_blog
Feature: Add a blog entry
In order to let the world know about me
As a user
I need to write blog entries

@javascript
Scenario: Add a blog entry with valid data
Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "View all of my entries"
And I should see "I'm a description"
And I should not see "Required"
</code>
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed

You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.

For detailed steps and/or troubleshooting:
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features

== Requirements ==
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)
* Other dependencies are managed by the composer installer

== Installation ==
* Edit config.php
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''
* Download composer
** '''cd /your/moodle/dirroot'''
** '''curl http://getcomposer.org/installer | php'''
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':
**** Download '''http://getcomposer.org/installer'''
**** Store it in /your/moodle/dirroot/composerinstaller.php for example
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')
* Install behat dependencies and enable the test environment
** '''cd /your/moodle/dirroot'''
** '''php admin/tool/behat/cli/init.php'''
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"

== Running tests ==
# Start the PHP built-in web server
#* Open a command line interface and '''cd /to/your/moodle/dirroot'''
#* '''php -S localhost:8000''' (This is the default address, if you want to use another one you can override it in config.php with $CFG->behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage)
# (Optional) Start the Selenium server (in case you want to run tests that involves Javascript)
#* Open another command line interface and '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# Run Behat
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''
# (Optional) If you are adding new tests or steps definitions update the tests list:
#* '''php admin/tool/behat/cli/util.php --enable'''
# (Optional) Disable test environment (in case you want to use the PHP built-in web server for regular moodle environment)
#* '''php admin/tool/behat/cli/util.php --disable'''

=== Tests filters ===
With the '''--tags''' or the '''-name''' Behat options you can filter which tests are going to run or which ones are going to be skipped. There are few tags that you might be interested in:
* '''@javascript''': All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.
* '''@_only_local''': All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.
* '''@_cross_browser''': All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.
* '''@componentname''': Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.

== Advanced usage ==
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.

* '''Different test server URL''', by default the test web server only can be accessed in localhost. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers...
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.
<code language="text">
$CFG->behat_config = array(
'default' => array(
'extensions' => array(
'Behat\MinkExtension\Extension' => array(
'selenium2' => array(
'browser' => 'chrome'
)
)
)
)
);
</code>
:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.
* '''Switch completely to test environment''', DON'T USE THIS SETTING IN PRODUCTION SITES! all the site users would be using the test environment instead of the regular one with your courses and all your data and they wouldn't be able to login in your site; this setting should only be used in development/testing installations. It's purpose is to ease the integration with cloud-based continuous integration systems, another possible use is to allow acceptance testing in a development environment without PHP 5.4.
** Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.

== Writing features ==

All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.

Once you decided which functionality you want to specify as a feature you should:
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:
#: <code lang="text">@plugintype @plugintype_pluginname
Feature: FEATURENAME
In order to ... // Why this feature is useful
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'
I need to ... // The feature we want</code>
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected
# For each scenario you thought:
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work. Remember to use ''Given'', ''When'' and ''Then'' in a way that reflects what the scenario is testing
## Copy the list of steps to the .feature file with the Scenario header:
##: <code lang="text">Scenario: Short description of the scenario
Given step 1
And step 2
And step 3
When step 4
And step 5
Then step 6</code>
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline
##: <code lang="text">@javascript
Scenario: Short description of the scenario
...
...</code>
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.
# Add extra tags to the scenario or the feature if required
#* If there are scenarios that includes files uploads they should be tagged as @_only_local
#* If there are scenarios that are likely to fail in some browser-OS combinations they can be tagged as @_cross_browser, they will be tested in different OS / browser combinations by Moodle HQ continuous integration servers

=== Available steps ===

Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:
* Processes to set up the environment
* Actions that provokes an event
* Checkings to ensure the outcomes are the expected ones

[[File:Acceptance_testing_UI_2.5.png]]

=== Tips ===
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)
* You can use '''Scenario outlines''' if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary

=== Providing values to steps ===
Most of the steps requires values, there are four methods to provide values to steps, the method depends on the step specification, you can know when a steps requires a value because you will see a drop down menu with a closed list of options that the step accepts as argument or an upper case string between double quotes, something like '''I press "BUTTON_STRING"''' or it ends with a ''':''' . The three methods are:
* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, in the 'Acceptance testing' interface you can see a dropdown menu to select one of these options:
** field - for searching a field by its id, name, value or label
** fieldset - for searching a fieldset by it's id or legend
** link - for searching a link by its href, id, title, img alt or value
** button - for searching a button by its name, id, value, img alt or title
** link_or_button - for searching for both, links and buttons
** select - for searching a select field by its id, name or label
** checkbox - for searching a checkbox by its id, name, or label
** radio - for searching a radio button by its id, name, or label
** file - for searching a file input by its id, name, or label
** optgroup - for searching optgroup by its label
** option - for searching an option by its content
** table - for searching a table by its id or caption
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath

==== Uploading files ====
Note than some tests requires files to be uploaded, in this case
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example)
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.
* The scenarios that includes files uploading should be tagged using the '''@_only_local''' tag

=== Fixtures ===

As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.

==== Available elements ====
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings.

The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.

* Course categories
** The required field is idnumber
** References between parent/children by their idnumber, using the "category" field
Given the following "categories" exists:
| name | category | idnumber |
| Category 1 | 0 | CAT1 |
| Category 2 | CAT1 | CAT2 |

* Courses
** The required field is shortname
** Uses the category idnumber as category reference
Given the following "courses" exists:
| fullname | shortname | category | format |
| Course 1 | COURSE1 | CAT1 | topics |
| Course 2 | COURSE2 | CAT2 | |

* Groups
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groups" exists:
| name | description | course | idnumber |
| Group 1 | Anything | COURSE1 | GROUP1 |

* Groupings
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groupings" exists:
| name | course | idnumber |
| Grouping 1 | COURSE1 | GROUPING1 |
| Grouping 2 | COURSE1 | GROUPING2 |

* Users
** The required field is username (if password is not set username value will be used as password too)
Given the following "users" exists:
| username | email | firstname | lastname |
| testuser | asd@asd.com | Test | User |

* Course enrolments
** The required fields are user, course and role
** Uses the course shortname as course reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses the enrolment name as enrol reference
Given the following "course enrolments" exists:
| user | course | role | enrol |
| testuser | COURSE1 | editingteacher | manual |

* System role assigns
** The required fields are user and role
** Uses the user username as user reference
** Uses the role shortname as role reference
Given the following "system role assigns" exists:
| user | role |
| testuser | manager |

* Group members
** The required fields are user and group
** Uses the group idnumber as group reference
** Uses the user username as user reference
Given the following "group members" exists:
| user | group |
| testuser | GROUP1 |

* Grouping groups
** The required fields are grouping and group
** Uses the group idnumber as group reference
** Uses the grouping idnumber as grouping reference
Given the following "grouping groups" exists:
| grouping | group |
| GROUPING1 | GROUP1 |

* Cohorts
** The required field is idnumber
Given the following "cohorts" exists:
| name | idnumber |
| Cohort 1 | COHORT1 |

=== Features check list ===
* It's a new feature or a new scenario of an existing feature
* Is using the '''Background''' section or '''Scenario Outlines''' instead of duplicating steps (only when applicable)
* Are using the appropriate Moodle component tag and includes @_only_local or @_cross_browser when required
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features
* Covers both JS and non-JS environments

== Adding steps definitions ==

Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.

=== Example ===

You can use this example below or any of the existing steps definitions as a template.

* auth/tests/behat/behat_auth.php
class behat_auth extends behat_base {
/**
* Logs in the user. There should exist a user with the same value as username and password
*
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/
*/
public function i_log_in_as($username) {
return array(new Given('I am on homepage'),
new Given('I follow "Login"'),
new Given('I fill in "Username" with "'.$username.'"'),
new Given('I fill in "Password" with "'.$username.'"'),
new Given('I press "Login"'),
new Given('I should see "You are logged in as"'));
}
}

=== Tips ===

If you are creating a completely new step definition there are also a few things to consider:
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this->running_javascript() to deal with both
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)

If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''

=== Check list ===

New steps should be/have:
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem
* Describe the regular expression with the most appropriate tag inside the method doc comment:
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')
* Depending on the inputs your definition expects you must use a different regular expression:
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)

== Links ==
* Technical info: [[Behat integration]]
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors
* See Also [https://tracker.moodle.org/browse/MDL-37046 MDL37046] for clear instruction
[[Category:Behat]][[Category:Quality Assurance]]

[[es:Prueba de aceptación]]

Compiling FreeTDS under Windows

2013-07-25T13:40:11Z

Davidaylmer: /* Building FreeTDS for PHP 5.5.x (VC11) */

==Requirements==

* MSVC 6.0 (Microsoft Visual C++ 6.0) with Service Packs installed.
* February 2003 Platform SDK (must be February 2003, last supported platform SDK for VC6) [see [[FebruaryPlatformSDK]]]
* FreeTDS (tested with [http://ibiblio.org/pub/Linux/ALPHA/freetds/old/0.82/freetds-patched.tgz version 0.82+official patchset] - updated 2011-09-06).
* PHP source files (tested with [http://www.php.net/get/php-5.3.5.tar.gz/from/a/mirror version 5.3.5])
* These packages (non-debug):
** From http://pecl2.php.net/downloads/php-windows-builds/php-libs/ :
*** binary-tools.zip
** From http://pecl2.php.net/downloads/php-windows-builds/php-libs/VC6/x86/ :
*** bindlib
*** libiconv
*** libxml
*** libxslt
*** zlib

==Build Steps==

* Create c:\dev
* Create c:\dev\php-build
* Uncompress all the packages listed in requirements and PHP into c:\dev\php-build (replacing all when uncompressing). Make sure to extract the bin, lib, include folders without any top level directory contained within the archive.
* Copy uncompressed [http://ibiblio.org/pub/Linux/ALPHA/freetds/stable/freetds-patched.tgz freetds] folder to C:\dev\php-build (rename it to, simply, "freetds").
* Open the C:\dev\php-build\freetds\win32\msvc6\FreeTDS.dsw Project Workspace (it's really important to get this Workspace and not any of the individual projects!).
* In the "Build" menu, set the "Active Configuration" to "dblib - Win32 Release" and then, in the same menu, "Rebuild All". This should end with one dblib.lib library into C:\dev\php-build\freetd\win32\msvc6\db_Release
* Copy dblib.lib to C:\dev\php-build\lib
* Start CMD
* Create one C:\dev\prepare4php.bat file with contents below and execute it:
::@set PATH=C:\dev\php-build\bin;%PATH%
::@set INCLUDE=C:\dev\php-build\include;%INCLUDE%
::@set LIB=C:\dev\php-build\lib;%LIB%
::@set BISON_SIMPLE=C:\dev\php-build\bin\bison.simple
* Continue in CMD and change dir to C:\dev\php-build\php-x-x-x
* Execute this:
** buildconf
** cscript /nologo configure.js --disable-all --disable-ipv6 --enable-cli --enable-zts (--disable-zts) --with-dblib=shared --enable-object-out-dir=c:\dev --with-extra-includes=c:\dev\php-build\freetds\include;c:\dev\php-build\freetds\win32
** nmake
* You should end with one C:\dev\Release_TS for the --enable-zts (or C:\dev\Release for the --disable-zts alternative) dir, with your compiled FreeTDS PHP module ready at the root level of that dir. CLI was passed as a build option above because as of PHP v5.3.x you must specify one SAPI modile to get a build.

==Notes==
* By using --enable-zts or --disable-zts you'll end with different thread safe/no safe versions of the extension. Use them depending of your environment thread safety.
* If you one use PHP 5.2 version to build the lib, the extensions generated are expected to work against any PHP 5.2.x version (but not against other releases of PHP, like 5.1 or 5.3).
* MSVC 6.0 is required because it's the official tool used to build PHP binary distributions. It seems that, with PHP 5.3 they will start using MSVC 9 or so... corresponding extensions should use the same.
* Feel free to fix and improve this document. TIA!
* For any comment related to this, please use MDL-14725 in the Moodle Tracker.
* And MDL-11810 has a related discussion.

==Building FreeTDS for PHP 5.5.x (VC11)==
Build process
Building PHP 5.5.1 with FreeTDS 0.91.89 for moodle 2.5.1 under x86 vc11

Requirements:
* Visual C 11 (Visual Studio 2012) (Free-to-download Express version OK) (Windows SDK not required)
* Current stable PHP source (http://php.net/downloads.php)
* Current stable FreeTDS source (ftp://ftp.freetds.org/pub/freetds/stable/)
* Most recent binary tools (http://windows.php.net/downloads/php-sdk/)
* PHP dependencies (http://windows.php.net/downloads/php-sdk/)

(At time of writing... the binary tools haven't been updated since 2011... but its OK)

Setup PHP environment by following guide: (follow the steps carefully)
https://wiki.php.net/internals/windows/stepbystepbuild
- In step 8, bin\phpsdk_buildtree.bat may not create a vc11 folder so I just copy the vc9 and rename.

Ensure you can build PHP under this created environment using:
buildconf
configure --disable-all --enable-cli
nmake

Building FreeTDS
Discussion with FreeTDS source maintainers [http://permalink.gmane.org/gmane.comp.db.tds.freetds/11009 here] suggests that the visual studio project/solution/workspace files are not maintained. You may get mixed results from these files. Visual Studio 2012 is very good at upgrading solution files from previous versions.

One method:
* If you have used the suggested paths then put the freetds source files here: C:\php-sdk\phpdev\vc11\x86\php-5.5.1-src\freetds
* Open the freetds\win32\msvc6\FreeTDS.dsw Project Workspace. Allow visual studio to upgrade.
* In the configuration manager, set the "Active Solution Configuration" to Release and platform to Win32
(you may not need to build all of the projects in the solution)
This should end with a dblib.lib library in one of the Release folders of freetds\win32\msvc6\
* Copy dblib.lib and libTDS.lib to C:\php-sdk\phpdev\vc11\x86\deps\lib

If when attempting to build php_dblib.lib from source you get linking errors, it is probably because you are missing some source files in the projects/solutions. Doing a file search in the src folder for the symbol (without the preceding underscore) should highlight where the function definition comes from. Add the file to the project that won’t compile. Rinse and Repeat.
freetds\src\tds and freetds\src\replacements are good places to look.

When php_dblib.lib is compilied and in the php lib folder in your build environment, the last thing is to configure the makefile appropriately. (You may also need to compile libTDS.lib from FreeTDS - I had to.).

I used a number of different configurations while testing. This one worked:
configure --disable-all --disable-zts --enable-cli --with-dblib=shared
--with-extra-includes=C:\php-sdk\phpdev\vc11\x86\php-5.5.1-src\freetds\include;C:\php-sdk\phpdev\vc11\x86\php-5.5.1-src\freetds\win32

Check the output from the configure call in case there any skipped dependencies. (like dblib!)

“--with-dblib=shared” is the key line for actually telling make to create an external dll file and not just compile the functionality directly into PHP core.

If while using nmake an unresolved external symbol linker error is reported: e.g. “error LNK2019: unresolved external symbol _tdsdump_log referenced in function _dblib_add_connection” you may need to add libTDS.lib to the libs statement in makefile and rerun make. http://enyby.blogspot.co.uk/2013/01/eliminate-errors-compile-freetds-on.html. I had to do this.
Sample LIBS declaration:
LIBS=libTDS.lib kernel32.lib ole32.lib user32.lib advapi32.lib shell32.lib ws2_32.lib Dnsapi.lib

Use “--enable-zts” or --disable-zts” for thread safety as mentioned.

Then when php_dblib.dll is created put it in the ext folder in your run time environment and enable the extension in your php.ini and you’re good to go!

[[Category:Installation]]

[[Category:XMLDB]]
[[Category:DB]]

Compiling FreeTDS under Windows

2013-07-25T13:11:41Z

Davidaylmer:

==Requirements==

* MSVC 6.0 (Microsoft Visual C++ 6.0) with Service Packs installed.
* February 2003 Platform SDK (must be February 2003, last supported platform SDK for VC6) [see [[FebruaryPlatformSDK]]]
* FreeTDS (tested with [http://ibiblio.org/pub/Linux/ALPHA/freetds/old/0.82/freetds-patched.tgz version 0.82+official patchset] - updated 2011-09-06).
* PHP source files (tested with [http://www.php.net/get/php-5.3.5.tar.gz/from/a/mirror version 5.3.5])
* These packages (non-debug):
** From http://pecl2.php.net/downloads/php-windows-builds/php-libs/ :
*** binary-tools.zip
** From http://pecl2.php.net/downloads/php-windows-builds/php-libs/VC6/x86/ :
*** bindlib
*** libiconv
*** libxml
*** libxslt
*** zlib

==Build Steps==

* Create c:\dev
* Create c:\dev\php-build
* Uncompress all the packages listed in requirements and PHP into c:\dev\php-build (replacing all when uncompressing). Make sure to extract the bin, lib, include folders without any top level directory contained within the archive.
* Copy uncompressed [http://ibiblio.org/pub/Linux/ALPHA/freetds/stable/freetds-patched.tgz freetds] folder to C:\dev\php-build (rename it to, simply, "freetds").
* Open the C:\dev\php-build\freetds\win32\msvc6\FreeTDS.dsw Project Workspace (it's really important to get this Workspace and not any of the individual projects!).
* In the "Build" menu, set the "Active Configuration" to "dblib - Win32 Release" and then, in the same menu, "Rebuild All". This should end with one dblib.lib library into C:\dev\php-build\freetd\win32\msvc6\db_Release
* Copy dblib.lib to C:\dev\php-build\lib
* Start CMD
* Create one C:\dev\prepare4php.bat file with contents below and execute it:
::@set PATH=C:\dev\php-build\bin;%PATH%
::@set INCLUDE=C:\dev\php-build\include;%INCLUDE%
::@set LIB=C:\dev\php-build\lib;%LIB%
::@set BISON_SIMPLE=C:\dev\php-build\bin\bison.simple
* Continue in CMD and change dir to C:\dev\php-build\php-x-x-x
* Execute this:
** buildconf
** cscript /nologo configure.js --disable-all --disable-ipv6 --enable-cli --enable-zts (--disable-zts) --with-dblib=shared --enable-object-out-dir=c:\dev --with-extra-includes=c:\dev\php-build\freetds\include;c:\dev\php-build\freetds\win32
** nmake
* You should end with one C:\dev\Release_TS for the --enable-zts (or C:\dev\Release for the --disable-zts alternative) dir, with your compiled FreeTDS PHP module ready at the root level of that dir. CLI was passed as a build option above because as of PHP v5.3.x you must specify one SAPI modile to get a build.

==Notes==
* By using --enable-zts or --disable-zts you'll end with different thread safe/no safe versions of the extension. Use them depending of your environment thread safety.
* If you one use PHP 5.2 version to build the lib, the extensions generated are expected to work against any PHP 5.2.x version (but not against other releases of PHP, like 5.1 or 5.3).
* MSVC 6.0 is required because it's the official tool used to build PHP binary distributions. It seems that, with PHP 5.3 they will start using MSVC 9 or so... corresponding extensions should use the same.
* Feel free to fix and improve this document. TIA!
* For any comment related to this, please use MDL-14725 in the Moodle Tracker.
* And MDL-11810 has a related discussion.

==Building FreeTDS for PHP 5.5.x (VC11)==
Build process
Building PHP 5.5.1 with FreeTDS 0.91.89 for moodle 2.5.1 under x86 vc11

Requirements:
* Visual C 11 (Visual Studio 2012) (Free-to-download Express version OK) (Windows SDK not required)
* Current stable PHP source (http://php.net/downloads.php)
* Current stable FreeTDS source (ftp://ftp.freetds.org/pub/freetds/stable/)
* Most recent binary tools (http://windows.php.net/downloads/php-sdk/)
* PHP dependencies (http://windows.php.net/downloads/php-sdk/)

(At time of writing... the binary tools haven't been updated since 2011... but its OK)

Setup PHP environment by following guide: (follow the steps carefully)
https://wiki.php.net/internals/windows/stepbystepbuild
- In step 8, bin\phpsdk_buildtree.bat may not create a vc11 folder so I just copy the vc9 and rename.

Ensure you can build PHP under this created environment using:
::buildconf
::configure --disable-all --enable-cli
::nmake

Building FreeTDS
Discussion with FreeTDS source maintainers [http://permalink.gmane.org/gmane.comp.db.tds.freetds/11009 here] suggests that the visual studio project/solution/workspace files are not maintained. You may get mixed results from these files. Visual Studio 2012 is very good at upgrading solution files from previous versions.

One method:
* If you have used the suggested paths then put the freetds source files here: C:\php-sdk\phpdev\vc11\x86\php-5.5.1-src\freetds
* Open the freetds\win32\msvc6\FreeTDS.dsw Project Workspace. Allow visual studio to upgrade.
* In the configuration manager, set the "Active Solution Configuration" to Release and platform to Win32
(you may not need to build all of the projects in the solution)
This should end with a dblib.lib library in one of the Release folders of freetds\win32\msvc6\
* Copy dblib.lib and libTDS.lib to C:\php-sdk\phpdev\vc11\x86\deps\lib

If when attempting to build php_dblib.lib from source you get linking errors, it is probably because you are missing some source files in the projects/solutions. Doing a file search in the src folder for the symbol (without the preceding underscore) should highlight where the function definition comes from. Add the file to the project that won’t compile. Rinse and Repeat.
freetds\src\tds and freetds\src\replacements are good places to look.

When php_dblib.lib is compilied and in the php lib folder in your build environment, the last thing is to configure the makefile appropriately. (You may also need to compile libTDS.lib from FreeTDS - I had to.).

I used a number of different configurations while testing. This one worked:
::* configure --disable-all --disable-zts --enable-cli --with-dblib=shared --with-extra-includes=C:\php-sdk\phpdev\vc11\x86\php-5.5.1-src\freetds\include;C:\php-sdk\phpdev\vc11\x86\php-5.5.1-src\freetds\win32

Check the output from the configure call in case there any skipped dependencies. (like dblib!)

“--with-dblib=shared” is the key line for actually telling make to create an external dll file and not just compile the functionality directly into PHP core.

If while using nmake an unresolved external symbol linker error is reported: e.g. “error LNK2019: unresolved external symbol _tdsdump_log referenced in function _dblib_add_connection” you may need to add libTDS.lib to the libs statement in makefile and rerun make. http://enyby.blogspot.co.uk/2013/01/eliminate-errors-compile-freetds-on.html. I had to do this.
Sample LIBS declaration:
::* LIBS=libTDS.lib kernel32.lib ole32.lib user32.lib advapi32.lib shell32.lib ws2_32.lib Dnsapi.lib

Use “--enable-zts” or --disable-zts” for thread safety as mentioned.

Then when php_dblib.dll is created put it in the ext folder in your run time environment and enable the extension in your php.ini and you’re good to go!

[[Category:Installation]]

[[Category:XMLDB]]
[[Category:DB]]