Module function API naming conventions

Hi Christopher,

On Sat, Jan 25, 2014 at 7:35 AM, Christopher Jones <
christopher.jones@oracle.com> wrote:

Can you make it more explicit with an example to show what an "exposed
module API" would
look like? This doc will be read by people not familiar with PHP
internals.

Is there anything in ext/ext_skel or the manual that needs to be kept in
sync with your
changes?

Thank you for your comment. Good point!
I'll make it more explicit and check ext_skel and the manual.

Regards,

--
Yasuo Ohgaki
yohgaki@ohgaki.net

Hi all,

On Sat, Jan 25, 2014 at 7:35 AM, Christopher Jones <
christopher.jones@oracle.com> wrote:

Can you make it more explicit with an example to show what an "exposed
module API" would
look like? This doc will be read by people not familiar with PHP
internals.

Is there anything in ext/ext_skel or the manual that needs to be kept in
sync with your
changes?

I've modified/updated other files also.
Any comments?

[yohgaki@dev PHP-5.4]$ git diff
diff --git a/CODING_STANDARDS b/CODING_STANDARDS
index 7a0562e..fccc2b8 100644
--- a/CODING_STANDARDS
+++ b/CODING_STANDARDS
@@ -82,7 +82,7 @@ Exceptions:
library may need to control or free the memory, or when the memory in
question needs to survive between multiple requests.

-Naming Conventions
+User Functions/Methods Naming Conventions

1. Function names for user-level functions should be enclosed with in
   @@ -163,6 +163,25 @@ Naming Conventions
   'foobar'
   'foo_bar'

+Internal Function Naming Convensions
+----------------------

+1. Exposed module API must be named 'php_modulename_function()' to avoid

• symbol collision. They should be in lowercase, with words underscore
• delimited. Exposed API must be defined in 'php_modulename.h'.
• PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS);
• Unexposed module function should be static and should not be defined in
• 'php_modulename.h'.
• static int php_session_destroy(TSRMLS_D)

+2. Main module source file must be named 'modulename.c'.

+3. Header file that are used by other sources must be named
'php_modulename.h'.

Syntax and indentation

@@ -181,9 +200,9 @@ Syntax and indentation
of PHP or one of its standard modules, please maintain the K&R
style. This applies to just about everything, starting with
indentation and comment styles and up to function declaration

• syntax. Also see Indentstyle_.

• syntax. Also see Indentstyle.

-.. _Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html

• Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html

3. Be generous with whitespace and braces. Keep one empty line between
   the
   variable declaration section and the statements in a block, as well as
   diff --git a/README.EXTENSIONS b/README.EXTENSIONS
   index 06d6cdd..84aa5e7 100644
   --- a/README.EXTENSIONS
   +++ b/README.EXTENSIONS
   @@ -1,3 +1,11 @@
   +This file describes extension module API details. Refer to
   +README.EXT_SKEL to create extension skeleton files. Refer to
   +Hacker's Guide for PHP internals.

+http://www.php.net/manual/en/internals2.php

Between PHP 4.0.6 and 4.1.0, the Zend module struct changed in a way
that broke both source and binary compatibility. If you are
maintaining a third party extension, here's how to update it:
diff --git a/README.EXT_SKEL b/README.EXT_SKEL
index d44fcc5..22a6251 100644
--- a/README.EXT_SKEL
+++ b/README.EXT_SKEL
@@ -45,12 +45,29 @@ HOW TO USE IT

 --proto=filename.

+SOURCE AND HEADER FILE NAME

• ./ext_skel generates 'module_name.c' and 'php_module_name.h' as main
  source
• and header files. Keep these names.
• Module functions (User functions) must be named
• module_name_function()
• When you need to expose module functions to other modules, expose
  functions
• strictly needed by others. Exposed internal function must be named
• php_module_name_function()
• See also CODING_STANDARDS.

FORMAT OF FUNCTION DEFINITIONS FILE

All the definitions must be on one line. In it's simplest form, it's just
the function name, e.g.

• my_function

• module_name_function

but then you'll be left with an almost empty function body without any
argument handling.
@@ -72,8 +89,9 @@ FORMAT OF FUNCTION DEFINITIONS FILE

An example:

• my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) this is my
  1st

• module_name_function(int arg1, int arg2 [, int arg3 [, int arg4]])

• Arguments arg1 and arg2 is required.
  Arguments arg3 and arg4 are optional.

  If possible, the function definition should also contain it's return type
  @@ -133,15 +151,15 @@ EXAMPLE

  The following one line

• bool my_drawtext(resource image, string text, resource font, int x, int
  y [, int color])

• bool module_name_drawtext(resource image, string text, resource font,
  int x, int y [, int color])

  will create this function definition for you (note that there are a few
  question marks to be replaced by you, and you must of course add your own
  value definitions too):

-/* {{{ proto bool my_drawtext(resource image, string text, resource font,
int x, int y [, int color])
+/* {{{ proto bool module_name_drawtext(resource image, string text,
resource font, int x, int y [, int color])
*/
-PHP_FUNCTION(my_drawtext)
+PHP_FUNCTION(module_name_drawtext)
{
char *text = NULL;
int argc = ZEND_NUM_ARGS();
@@ -164,7 +182,7 @@ PHP_FUNCTION(my_drawtext)
ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id);
}

• php_error(E_WARNING, "my_drawtext: not yet implemented");

• php_error(E_WARNING, "module_name_drawtext: not yet implemented");
  }
  /* }}} */

diff --git a/README.SUBMITTING_PATCH b/README.SUBMITTING_PATCH
index 63b7156..a767046 100644
--- a/README.SUBMITTING_PATCH
+++ b/README.SUBMITTING_PATCH
@@ -50,6 +50,13 @@ Please make the mail subject prefix "[PATCH]". If
attaching a patch,
ensure it has a file extension of ".txt". This is because only MIME
attachments of type 'text/*' are accepted.

+Preferred way to propose PHP patch is sending pull request from github.

+https://github.com/php/php-src

+Fork official PHP repository and send pull request. It will be notified
+to pull request mailing list.

PHP Documentation Patches

--
Yasuo Ohgaki
yohgaki@ohgaki.net