Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:71570
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.215.52 as permitted sender)
MIME-Version: 1.0
Sender: yohgaki@gmail.com
In-Reply-To: <52E2EA9B.8020206@oracle.com>
References: <CAGa2bXbV-mWpDWWSFbsrMSBffp9=fdAbMrJ33f8KHuJiTAzi8w@mail.gmail.com>
 <CAGa2bXap2YyxdrgGk8ckUyEO=wVG3+qN+gKDz_ZcbMB2QqpWVA@mail.gmail.com> <52E2EA9B.8020206@oracle.com>
Date: Sun, 26 Jan 2014 07:46:13 +0900
Message-ID: <CAGa2bXZv1dnYR8r=L3dBoKKSZjmO_4mkmVyji7PKXUDqQ=MRrA@mail.gmail.com>
To: "internals@lists.php.net" <internals@lists.php.net>
Content-Type: multipart/alternative; boundary=089e011823f647992804f0d340a9
Subject: Re: [PHP-DEV] Re: Module function API naming conventions
From: yohgaki@ohgaki.net (Yasuo Ohgaki)

--089e011823f647992804f0d340a9
Content-Type: text/plain; charset=UTF-8

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

--089e011823f647992804f0d340a9--