How to Contribute Changes to the PHP Driver grantc@php.net
Abstract
The first steps for those wanting to help any open source project can be quite difficult. From reporting bugs, submitting fixes or new functionality, this presentation outlines the requirements for someone looking to provide assistance with the Ingres PECL extension.
© Copyright Ingres Corporation 2008
Facets of a project
Answering questions Bug reporting/fixing Documentation Implementing features Writing tests
© Copyright Ingres Corporation 2008
Answering Questions
comp.databases.ingres – http://www.rationalcommerce.com/community.htm Ingres Community Forums – http://community.ingres.com/forums/viewforum.php?f=5 PECL-DEV – http://pecl.php.net/support.php
© Copyright Ingres Corporation 2008
Bug Reporting
Identifying Problems Report the bug – http://pecl.php.net/bugs/report.php?package=ingres Provide as much information as possible – A short script that reproduces the problem. – Ingres INI configuration settings – A stack dump – if possible
© Copyright Ingres Corporation 2008
Documentation
Docs maintained via CVS – cvs.php.net/phpdoc DocBook format – XSLTs used to generate HTML, PDF, CHM,... Working on the documentation – http://doc.php.net/php/dochowto/index.php Ingres docs under – en/reference/ingres-ii
© Copyright Ingres Corporation 2008
Documentation – Viewing Changes
make html – Completely regenerates all PHP documentation
• Even for a small change
– As used by http://php.net/manual/en Phd – http://doc.php.net/wiki/phd – Work in progress – Does not re-generate all the documentation
© Copyright Ingres Corporation 2008
Implementing Changes
Driver code is C based – plus some PHP, autoconf, XML and Jscript 2 programming APIs – PHP - http://php.net/zend – Ingres OpenAPI - http://docs.ingres.com/oapi Code is licensed under PHP License 3.0
© Copyright Ingres Corporation 2008
Concurrent Versions System
Source control system for PHP Windows – CVSNT - http://www.cvsnt.org – TortoiseCVS - http://www.tortoisecvs.org/ CVS package for UNIX/Linux OpenVMS – http://www.polarhome.com/vim/
© Copyright Ingres Corporation 2008
Downloading the Source
Define CVSROOT
CVSROOT=:pserver:cvsread@cvs.php.net/repository
Login – password phpfi
cvs login
Checkout extension source
cvs co pecl/ingres
Override directory using -d
cvs co -d php-ingres pecl/ingres
© Copyright Ingres Corporation 2008
Downloading the Source
Windows buildconf.bat uses the following layout
~/ ∟src/ ∟php/ ∟5.2.5/ ∟pecl/ ∟ingres/ ∟5.3/
Can be overridden buildconf.bat --with-modules-dir
© Copyright Ingres Corporation 2008
Checkout output
C:\src\php\>cvs co pecl/ingres cvs checkout: cwd=C:\src\php\ ,current=C:\src\php\ cvs checkout: Updating pecl/ingres U pecl/ingres/.cvsignore U pecl/ingres/BUILD.COM U pecl/ingres/CHANGELOG . . U pecl/ingres/tests/test_037.phpt U pecl/ingres/tests/test_038.phpt U pecl/ingres/tests/test_039.phpt
© Copyright Ingres Corporation 2008
Extension files
Extension code – ingres.c / ingres.h / php_ingres.h / php_ingres2.h – convertUTF.c / convertUTF.h Configuration files – config.m4 / config.w32 / INGRES.OPT Package specification – package.xml
© Copyright Ingres Corporation 2008
Adding a new function
PHP_FUNCTION(ingres_hello) – Macro for zif_ingres_hello() – Corresponding prototype required in php_ingres.h PHP_FE(ingres_hello) function_entry ingres_functions[] = { . PHP_FE(ingres_hello, NULL) {NULL, NULL, NULL} }
© Copyright Ingres Corporation 2008
Passing Parameters
zend_parse_parameters (ZEND_NUM_ARGS() TSRMLS_CC , type_string , variable [, variable...]) type_string contains sequence of expected types being passed from user land Parameter values stored in variables – optional parameters after “|”
• E.g. “a|s” = Array value with an optional STRING value
© Copyright Ingres Corporation 2008
Passing Parameter Types
Type Boolean Long Double String Resource Array Object zval Code b l d s r a o z Variable Type zend_bool long double char*, int zval* zval* zval* zval*
© Copyright Ingres Corporation 2008
Returning Values
Return a Resource – ZEND_REGISTER_RESOURCE( return_value, ii_result, le_ii_result ) Or singleton value – RETURN_STRING(var) – RETURN_LONG(var) – RETURN_TRUE / RETURN_FALSE – RETURN_NULL
© Copyright Ingres Corporation 2008
The PHP Resource Type
A PHP Resource is a wrapper for a C pointer – Internals are opaque to user code Stored using – ZEND_REGISTER_RESOURCE() Retrieved using – ZEND_FETCH_RESOURCE()
© Copyright Ingres Corporation 2008
Fetching Resources
ZEND_FETCH_RESOURCE(ii_result, II_RESULT *, &result, -1, "Ingres Result", le_ii_result); – ii_result – target pointer – II_RESULT * – data type for target pointer – result – resource_id passed by the user – “Ingres Result” - the resource type name – le_ii_result – the resource type
© Copyright Ingres Corporation 2008
PHP Globals
Thread Safe Global to the request Ingres has its own set of globals Defined in php_ingres.h
ZEND_BEGIN_MODULE_GLOBALS(ii) II_PTR *envHandle; /*environment handle*/ … … ZEND_END_MODULE_GLOBALS(ii) IIG(envHandle)
© Copyright Ingres Corporation 2008
New Function - ingres_hello()
PHP_FUNCTION(ingres_hello) { char *name; int name_len; char greeting[3]; char *message; sprintf (greeting,"Hi"); if (zend_parse_parameters(ZEND_NUM_ARGS() "s" , &name, &name_len) == FAILURE){ RETURN_FALSE; } /* allow for the space */ message=emalloc(name_len + 3 + 1); sprintf(message,"%s %s", greeting, name); RETURN_STRING(message,1); }
TSRMLS_CC ,
© Copyright Ingres Corporation 2008
Building - Windows
No separate build mechanism – Need working PHP core build environment Requires Visual C++ 6.0 – Newer compiler can be used but… – Compiler used on http://snaps.php.net Pre-requisites and set-up process detailed at – http://php.net/manual/en/install.windows.building.php
© Copyright Ingres Corporation 2008
Building - Windows
Include the extension in your build buildconf.bat –with-modules-dir=/path/to/parent/dir Generate the Makefile cscript /nologo configure.js --with-ingres=shared,%II_SYSTEM% --without-libxml --enable-isapi --enable-apache2handler --enable-debug-pack Compile nmake Ingres extension and debug symbols in .\Release_TS
© Copyright Ingres Corporation 2008
Building - UNIX/Linux
Standard PHP build environment – Linux distributions require a separate dev package – Novell SLES/openSUSE – php5-devel – RedHat ES/Fedora – php-devel – Debian/Ubuntu - php-dev Needs flex, bison, autoconf, automake, libtool Should build using the latest GCC compiler (4.x)
© Copyright Ingres Corporation 2008
Building - UNIX/Linux
Load Ingres environment source ~ingres/.ingIIcsh # csh, tcsh . ~ingres/.ingIIbash # sh, ksh, bash Generate configure script phpize Execute configure script ./configure –with-ingres Build make
© Copyright Ingres Corporation 2008
Installing - Windows
copy php_ingres.dll to extension_dir add to php.ini – extension=php_ingres.dll II_SYSTEM needs be defined at the system level Web server process owner must be a valid Ingres user – IIS 5.x - IUSR_ – Apache - SYSTEM or whoever the service runs as
© Copyright Ingres Corporation 2008
Installing - UNIX/Linux
Copy ingres.so to extension_dir Run make install – may need root access Add to php.ini – extension=ingres.so Web server process owner must be a valid Ingres user – Apache - Check User directive in httpd.conf
© Copyright Ingres Corporation 2008
Testing
PHP has its own Unit Test system – Extended PHP scripts – 'phpt' extension Invoked using 'run-tests.php' – Run one test – Directory of tests Ingres tests located under '/pecl/ingres/tests'
© Copyright Ingres Corporation 2008
Testing – Test Structure
--TEST-Test Title --SKIPIF-Initialization code --ENV-II_SYSTEM=/opt/Ingres/IngresR3 --FILE- --EXPECT-Expected output
© Copyright Ingres Corporation 2008
Testing - Example
--TEST-Ingres: test ingres_hello() --SKIPIF- --FILE- --EXPECT-Hi grant
© Copyright Ingres Corporation 2008
Testing – Running the test
Define TEST_PHP_EXECUTABLE – export TEST_PHP_EXECUTABLE=`which php` Execute a single test – php run-tests.php tests/test_xxxx.phpt Execute all tests – php run-tests.php tests
© Copyright Ingres Corporation 2008
Testing - Ouput
================================================================= CWD : /home/grant/src/php/pecl/ingres PHP : /usr/local/bin/php PHP_SAPI : cli PHP_VERSION : 5.2.5 ZEND_VERSION: 2.2.0 PHP_OS : Linux - Linux esva-suse 2.6.22.17-0.1-default #1 SMP INI actual : /home/grant/src/php/pecl/ingres More .INIs : /usr/local/lib/php/conf.d/ingres.ini Extra dirs : ===================================================================== Running selected tests. PASS Ingres: connect to a database as current user [tests/test_001.phpt] PASS Ingres: connect to a database with user+password [tests/test_002.phpt] PASS Ingres: execute a simple select against default link - no results returned. [tests/test_003.phpt] PASS Ingres: execute a simple select against default link - fetch object. [tests/test_004.phpt] . . FAIL Ingres: test support for INTEGER8 values [tests/test_038.phpt] FAIL Ingres: test freeing multiple resultsets in random order [tests/test_039.phpt]
© Copyright Ingres Corporation 2008
Testing – Failed Tests
Diagnostic files created – .php – the test that failed – .exp – expected output – .out – actual output – .log – expected and actual output – .diff – Difference from the above outputs
© Copyright Ingres Corporation 2008
Debugging
UNIX/Linux – Build with CFLAGS=-g ./configure Windows – add “--enable-debug-pack” Userland extensions are prefixed with “zif_” – ingres_connect -> zif_ingres_connect()
© Copyright Ingres Corporation 2008
Generating Patches
Changes should be presented as a unified diff – cvs diff -u [file(s)] > patchfile – diff -u BASEDIR NEWDIR > patchfile – diff -u OLDFILE NEWFILE > patchfile Patch file emailed to grantc@php.net or put in a bug report Coding standards – http://cvs.php.net/viewvc.cgi/phpsrc/CODING_STANDARDS?view=co
© Copyright Ingres Corporation 2008
Commit Access
Based on merit – No real definition – 3 good changes Requires a CVS account – http://pecl.php.net/account-request.php – Needs approval of existing maintainer
© Copyright Ingres Corporation 2008
Suggested Projects
Virtual Node Management – Create, Delete, Query Batch query support Ingres Events LOB Locators – Scrolling and LOBs at the same time Describe Input support – Automatic data type handling
© Copyright Ingres Corporation 2008
Useful Resources
Extending and Embedding PHP – # ISBN-10: 067232704X – # ISBN-13: 978-0672327049 Extension Writing – http://devzone.zend.com/node/view/id/1021 – http://devzone.zend.com/node/view/id/1022 – http://devzone.zend.com/node/view/id/1023 – http://devzone.zend.com/node/view/id/1024
© Copyright Ingres Corporation 2008
(More) Useful Resources
Mailing-Lists – PECL-DEV - http://marc.info/?l=pecl-dev – PHP Internals - http://marc.info/?l=php-internals IRC – #pecl-dev on EFnet – #ingres on Freenode Use the source – http://cvs.php.net/pecl - all PECL extensions – http://cvs.php.net/php-src - Main PHP source
© Copyright Ingres Corporation 2008
Summary
Facets of a project Working on the code Testing Bug Reporting Documentation Additional Information
© Copyright Ingres Corporation 2008