diff options
| -rw-r--r-- | Examples/CppClassesInPhp/Makefile | 149 | ||||
| -rw-r--r-- | Examples/CppClassesInPhp/cppclassinphp.cpp | 2 | ||||
| -rw-r--r-- | Examples/EmptyExtension/main.cpp | 4 | ||||
| -rw-r--r-- | documentation/compile-extensions.html | 167 | ||||
| -rw-r--r-- | documentation/install.html | 8 | ||||
| -rw-r--r-- | documentation/your-first-extension.html | 228 |
6 files changed, 361 insertions, 197 deletions
diff --git a/Examples/CppClassesInPhp/Makefile b/Examples/CppClassesInPhp/Makefile index 872cce3..581a50e 100644 --- a/Examples/CppClassesInPhp/Makefile +++ b/Examples/CppClassesInPhp/Makefile @@ -1,32 +1,135 @@ -CPP = g++ -RM = rm -f -CPP_FLAGS = -Wall -c -I. -g -std=c++11 +# +# Makefile template +# +# This is an example Makefile that can be used by anyone who is building +# his or her own PHP extensions using the PHP-CPP library. +# +# In the top part of this file we have included variables that can be +# altered to fit your configuration, near the bottom the instructions and +# dependencies for the compiler are defined. The deeper you get into this +# file, the less likely it is that you will have to change anything in it. +# -PREFIX = /usr -#Edit these lines to correspond with your own directories -LIBRARY_DIR = ${PREFIX}/lib/php5/20090626 -PHP_CONFIG_DIR = /etc/php5/cli/conf.d +# +# Name of your extension +# +# This is the name of your extension. Based on this extension name, the +# name of the library file (name.so) and the name of the config file (name.ini) +# are automatically generated +# -LD = g++ -LD_FLAGS = -Wall -shared -O2 -RESULT = cppclassinphp.so +NAME = cppclassinphp -PHPINIFILE = 30-cppclassinphp.ini -SOURCES = $(wildcard *.cpp) -OBJECTS = $(SOURCES:%.cpp=%.o) +# +# Php.ini directories +# +# In the past, PHP used a single php.ini configuration file. Today, most +# PHP installations use a conf.d directory that holds a set of config files, +# one for each extension. Use this variable to specify this directory. +# -all: ${OBJECTS} ${RESULT} +INI_DIR = /etc/php5/conf.d -${RESULT}: ${OBJECTS} - ${LD} ${LD_FLAGS} -o $@ ${OBJECTS} -lphpcpp -clean: - ${RM} *.obj *~* ${OBJECTS} ${RESULT} +# +# The extension dirs +# +# This is normally a directory like /usr/lib/php5/20121221 (based on the +# PHP version that you use. We make use of the command line 'php-config' +# instruction to find out what the extension directory is, you can override +# this with a different fixed directory +# + +EXTENSION_DIR = $(shell php-config --extension-dir) + + +# +# The name of the extension and the name of the .ini file +# +# These two variables are based on the name of the extension. We simply add +# a certain extension to them (.so or .ini) +# + +EXTENSION = ${NAME}.so +INI = ${NAME}.ini + + +# +# Compiler +# +# By default, the GNU C++ compiler is used. If you want to use a different +# compiler, you can change that here. You can change this for both the +# compiler (the program that turns the c++ files into object files) and for +# the linker (the program that links all object files into the single .so +# library file. By default, g++ (the GNU C++ compiler) is used for both. +# + +COMPILER = g++ +LINKER = g++ + + +# +# Compiler and linker flags +# +# This variable holds the flags that are passed to the compiler. By default, +# we include the -O2 flag. This flag tells the compiler to optimize the code, +# but it makes debugging more difficult. So if you're debugging your application, +# you probably want to remove this -O2 flag. At the same time, you can then +# add the -g flag to instruct the compiler to include debug information in +# the library (but this will make the final libphpcpp.so file much bigger, so +# you want to leave that flag out on production servers). +# +# If your extension depends on other libraries (and it does at least depend on +# one: the PHP-CPP library), you should update the LINKER_DEPENDENCIES variable +# with a list of all flags that should be passed to the linker. +# + +COMPILER_FLAGS = -Wall -c -O2 -std=c++11 -fpic -o +LINKER_FLAGS = -shared +LINKER_DEPENDENCIES = -lphpcpp + -${OBJECTS}: - ${CPP} ${CPP_FLAGS} -fpic -o $@ ${@:%.o=%.cpp} +# +# Command to remove files, copy files and create directories. +# +# I've never encountered a *nix environment in which these commands do not work. +# So you can probably leave this as it is +# + +RM = rm -f +CP = cp -f +MKDIR = mkdir -p + + +# +# All source files are simply all *.cpp files found in the current directory +# +# A builtin Makefile macro is used to scan the current directory and find +# all source files. The object files are all compiled versions of the source +# file, with the .cpp extension being replaced by .o. +# + +SOURCES = $(wildcard *.cpp) +OBJECTS = $(SOURCES:%.cpp=%.o) + + +# +# From here the build instructions start +# + +all: ${OBJECTS} ${EXTENSION} + +${EXTENSION}: ${OBJECTS} + ${LINKER} ${LINKER_FLAGS} -o $@ ${OBJECTS} ${LINKER_DEPENDENCIES} + +${OBJECTS}: + ${COMPILER} ${COMPILER_FLAGS} $@ ${@:%.o=%.cpp} + +install: + ${CP} ${EXTENSION} ${EXTENSION_DIR} + ${CP} ${INI} ${INI_DIR} + +clean: + ${RM} ${EXTENSION} ${OBJECTS} -install: - cp -f ${RESULT} ${LIBRARY_DIR} - cp -f ${PHPINIFILE} ${PHP_CONFIG_DIR} diff --git a/Examples/CppClassesInPhp/cppclassinphp.cpp b/Examples/CppClassesInPhp/cppclassinphp.cpp index b3f2bac..400d942 100644 --- a/Examples/CppClassesInPhp/cppclassinphp.cpp +++ b/Examples/CppClassesInPhp/cppclassinphp.cpp @@ -129,6 +129,6 @@ extern "C" extension.add(customClass); // return the extension module - return extension.module(); + return extension; } } diff --git a/Examples/EmptyExtension/main.cpp b/Examples/EmptyExtension/main.cpp index 22aba90..b4c4426 100644 --- a/Examples/EmptyExtension/main.cpp +++ b/Examples/EmptyExtension/main.cpp @@ -16,11 +16,11 @@ extern "C" { { // static(!) Php::Extension object that should stay in memory // for the entire duration of the process (that's why it's static) - static Php::Extension myExtension("my_extension", "1.0"); + static Php::Extension extension("yourextension", "1.0"); // @todo add your own functions, classes, namespaces to the extension // return the extension - return myExtension; + return extension; } } diff --git a/documentation/compile-extensions.html b/documentation/compile-extensions.html deleted file mode 100644 index eae0076..0000000 --- a/documentation/compile-extensions.html +++ /dev/null @@ -1,167 +0,0 @@ -<h1>Compile your own extensions</h1> -<p> - When you build your own PHP-CPP extensions, you also have to compile and - deploy them. A normal PHP script only has to be placed on a web server to be - deployed, but it takes a little more effort to deploy an extension. -</p> -<p> - To help your users, customers, and/or operations department with deploying - your native extensions, you best create a Makefile with settings and - instructions for the compiler. All that is then left for someone to install - your extension, is run "make" and "make install". And because it is PHP-CPP's - objective to make life easy, we give you already an example Makefile that - works on most Linux platforms. -</p> -<p> - <code><pre> - # - # Makefile template - # - # This is an example Makefile that can be used by anyone who is building - # his or her own PHP extensions using the PHP-CPP library. - # - # In the top part of this file we have included variables that can be - # altered to fit your configuration, near the bottom the instructions and - # dependencies for the compiler are defined. The deeper you get into this - # file, the less likely it is that you will have to change anything in it. - # - - # - # Name of your extension - # - # This is the name of your extension. Based on this extension name, the - # name of the library file (name.so) and the name of the config file (name.ini) - # are automatically generated - # - - NAME = yourextension - - - # - # Php.ini directories - # - # In the past, PHP used a single php.ini configuration file. Today, most - # PHP installations use a conf.d directory that holds a set of config files, - # one for each extension. Use this variable to specify this directory. - # - - INI_DIR = /etc/php5/conf.d - - - # - # The extension dirs - # - # This is normally a directory like /usr/lib/php5/20121221 (based on the - # PHP version that you use. We make use of the command line 'php-config' - # instruction to find out what the extension directory is, you can override - # this with a different fixed directory - # - - EXTENSION_DIR = $(shell php-config --extension-dir) - - - # - # The name of the extension and the name of the .ini file - # - # These two variables are based on the name of the extension. We simply add - # a certain extension to them (.so or .ini) - # - - EXTENSION = ${NAME}.so - INI = ${NAME}.ini - - - # - # Compiler - # - # By default, the GNU C++ compiler is used. If you want to use a different - # compiler, you can change that here. You can change this for both the - # compiler (the program that turns the c++ files into object files) and for - # the linker (the program that links all object files into the single .so - # library file. By default, g++ (the GNU C++ compiler) is used for both. - # - - COMPILER = g++ - LINKER = g++ - - - # - # Compiler and linker flags - # - # This variable holds the flags that are passed to the compiler. By default, - # we include the -O2 flag. This flag tells the compiler to optimize the code, - # but it makes debugging more difficult. So if you're debugging your application, - # you probably want to remove this -O2 flag. At the same time, you can then - # add the -g flag to instruct the compiler to include debug information in - # the library (but this will make the final libphpcpp.so file much bigger, so - # you want to leave that flag out on production servers). - # - # If your extension depends on other libraries (and it does at least depend on - # one: the PHP-CPP library), you should update the LINKER_DEPENDENCIES variable - # with a list of all flags that should be passed to the linker. - # - - COMPILER_FLAGS = -Wall -c -O2 -std=c++11 -fpic -o - LINKER_FLAGS = -shared - LINKER_DEPENDENCIES = -lphpcpp - - - # - # Command to remove files, copy files and create directories. - # - # I've never encountered a *nix environment in which these commands do not work. - # So you can probably leave this as it is - # - - RM = rm -f - CP = cp -f - MKDIR = mkdir -p - - - # - # All source files are simply all *.cpp files found in the current directory - # - # A builtin Makefile macro is used to scan the current directory and find - # all source files. The object files are all compiled versions of the source - # file, with the .cpp extension being replaced by .o. - # - - SOURCES = $(wildcard *.cpp) - OBJECTS = $(SOURCES:%.cpp=%.o) - - - # - # From here the build instructions start - # - - all: ${OBJECTS} ${EXTENSION} - - ${EXTENSION}: ${OBJECTS} - ${LINKER} ${LINKER_FLAGS} -o $@ ${OBJECTS} ${LINKER_DEPENDENCIES} - - ${OBJECTS}: - ${COMPILER} ${COMPILER_FLAGS} $@ ${@:%.o=%.cpp} - - install: - ${CP} ${EXTENSION} ${EXTENSION_DIR} - ${CP} ${INI} ${INI_DIR} - - clean: - ${RM} ${EXTENSION} ${OBJECTS} - - </pre></code> -</p> -<p> - But your extension should not only have a Makefile, but also an initial - yourextension.ini file. This file is much simpler that the Makefile: -</p> -<p> - <code><pre> - extension=yourextension.so - </pre></code> -</p> -<p> - You can download both the Makefile and the ini file from our empty extension - template, so that you can start making your application right away. -</p> - diff --git a/documentation/install.html b/documentation/install.html index 917d59d..b8d6d54 100644 --- a/documentation/install.html +++ b/documentation/install.html @@ -42,7 +42,7 @@ with the core principle of the PHP-CPP library: to make life easy. </p> <p> - However, if there is demand for, we may add support for multi-threaded PHP + However, if there is demand for, we will add support for multi-threaded PHP installations, and hopefully we can even keep the same simple C++ API as we have now. </p> @@ -54,7 +54,7 @@ Installation begins with downloading the source code. You can either download the latest release from <a href="http://www.php-cpp.com">http://www.php-cpp.com</a>, or get the - latest bleading edge work-in-progress version from + latest bleeding edge work-in-progress version from <a href="https://github.com/CopernicaMarketingSoftware/PHP-CPP">GitHub</a>. </p> <p> @@ -68,8 +68,8 @@ </p> <p> After you've downloaded the software (either from our website, or directly - from GitHub, change your working directory to the PHP-CPP directly, and open - the file named "Makefile" in your editor of choice. + from GitHub), change your working directory to the PHP-CPP directory, and open + the file named "Makefile" with your editor of choice. </p> <p> The Makefile is a file that holds settings and instructions for the compiler. diff --git a/documentation/your-first-extension.html b/documentation/your-first-extension.html new file mode 100644 index 0000000..072e79a --- /dev/null +++ b/documentation/your-first-extension.html @@ -0,0 +1,228 @@ +<h1>Your first extension</h1> +<p> + When you create your own PHP-CPP extensions, you also have to compile and + deploy them. A normal PHP script only has to be copied to a web server to be + deployed, but it takes a little more effort to deploy an extension. +</p> +<p> + To help your users, customers, and/or operations department with deploying + your native extensions, you best create a Makefile with settings and + instructions for the compiler. All that is then left for someone to do, + is run "make" and "make install". +</p> +<p> + And that's not all. You also have to make changes to the system wide php.ini + file to actually enable your extension. The best way to do that is create + your own small yourextension.ini file, and copy that to the PHP config file + directory of your webserver. +</p> +<p> + To help you out with that, we have created an almost empty extension with + all the required utilities for starting up a new extension. It contains a + sample Makefile, a sample configuration file, and a first main.cpp file + in which the get_module() call is already implemented. This gives you a + kickstart in developing an extension. +</p> +<p> + <ul> + <li><a href="http://www.php-cpp.com/EmptyExtension.zip">EmptyExtension.zip</a></li> + <li><a href="http://www.php-cpp.com/EmptyExtension.tar.gz">EmptyExtension.tar.gz</a></li> + </ul> +</p> +<h2>Makefile</h2> +<p> + The EmptyExtension file contains a Makefile with instructions for the compiler. + You will have to make some (small) changes to this Makefile to make it compatible + with your extension. The most important things you want to modify are the NAME + variable, and probably also the INI_DIR. +</p> +<p> +<pre> +# +# Makefile template +# +# This is an example Makefile that can be used by anyone who is building +# his or her own PHP extensions using the PHP-CPP library. +# +# In the top part of this file we have included variables that can be +# altered to fit your configuration, near the bottom the instructions and +# dependencies for the compiler are defined. The deeper you get into this +# file, the less likely it is that you will have to change anything in it. +# + +# +# Name of your extension +# +# This is the name of your extension. Based on this extension name, the +# name of the library file (name.so) and the name of the config file (name.ini) +# are automatically generated +# + +NAME = yourextension + + +# +# Php.ini directories +# +# In the past, PHP used a single php.ini configuration file. Today, most +# PHP installations use a conf.d directory that holds a set of config files, +# one for each extension. Use this variable to specify this directory. +# + +INI_DIR = /etc/php5/conf.d + + +# +# The extension dirs +# +# This is normally a directory like /usr/lib/php5/20121221 (based on the +# PHP version that you use. We make use of the command line 'php-config' +# instruction to find out what the extension directory is, you can override +# this with a different fixed directory +# + +EXTENSION_DIR = $(shell php-config --extension-dir) + + +# +# The name of the extension and the name of the .ini file +# +# These two variables are based on the name of the extension. We simply add +# a certain extension to them (.so or .ini) +# + +EXTENSION = ${NAME}.so +INI = ${NAME}.ini + + +# +# Compiler +# +# By default, the GNU C++ compiler is used. If you want to use a different +# compiler, you can change that here. You can change this for both the +# compiler (the program that turns the c++ files into object files) and for +# the linker (the program that links all object files into the single .so +# library file. By default, g++ (the GNU C++ compiler) is used for both. +# + +COMPILER = g++ +LINKER = g++ + + +# +# Compiler and linker flags +# +# This variable holds the flags that are passed to the compiler. By default, +# we include the -O2 flag. This flag tells the compiler to optimize the code, +# but it makes debugging more difficult. So if you're debugging your application, +# you probably want to remove this -O2 flag. At the same time, you can then +# add the -g flag to instruct the compiler to include debug information in +# the library (but this will make the final libphpcpp.so file much bigger, so +# you want to leave that flag out on production servers). +# +# If your extension depends on other libraries (and it does at least depend on +# one: the PHP-CPP library), you should update the LINKER_DEPENDENCIES variable +# with a list of all flags that should be passed to the linker. +# + +COMPILER_FLAGS = -Wall -c -O2 -std=c++11 -fpic -o +LINKER_FLAGS = -shared +LINKER_DEPENDENCIES = -lphpcpp + + +# +# Command to remove files, copy files and create directories. +# +# I've never encountered a *nix environment in which these commands do not work. +# So you can probably leave this as it is +# + +RM = rm -f +CP = cp -f +MKDIR = mkdir -p + + +# +# All source files are simply all *.cpp files found in the current directory +# +# A builtin Makefile macro is used to scan the current directory and find +# all source files. The object files are all compiled versions of the source +# file, with the .cpp extension being replaced by .o. +# + +SOURCES = $(wildcard *.cpp) +OBJECTS = $(SOURCES:%.cpp=%.o) + + +# +# From here the build instructions start +# + +all: ${OBJECTS} ${EXTENSION} + +${EXTENSION}: ${OBJECTS} + ${LINKER} ${LINKER_FLAGS} -o $@ ${OBJECTS} ${LINKER_DEPENDENCIES} + +${OBJECTS}: + ${COMPILER} ${COMPILER_FLAGS} $@ ${@:%.o=%.cpp} + +install: + ${CP} ${EXTENSION} ${EXTENSION_DIR} + ${CP} ${INI} ${INI_DIR} + +clean: + ${RM} ${EXTENSION} ${OBJECTS} + +</pre> +</p> +<h2>Yourextension.ini</h2> +<p> + Your extension should not only have a Makefile, but also an initial + yourextension.ini file. This file is much simpler that the Makefile. You + should also modify this file to refer to the real name of your extension + (instead of yourextension.so). +</p> +<p> +<pre> +extension=yourextension.so +</pre> +</p> +<h2>Main.cpp</h2> +<p> + The last file that is available in this EmptyExtension file is the actual + implementation of the extension. Because the extension is empty (duh!) the + contents of this main.cpp need a lot of modification: you will have to add + all your functions and classes to it. +</p> +<p> +<pre class="language-c++"><code> +#include <phpcpp.h&rt; + +/** + * tell the compiler that the get_module is a pure C function + */ +extern "C" { + + /** + * Function that is called by PHP right after the PHP process + * has started, and that returns an address of an internal PHP + * strucure with all the details and features of your extension + * + * @return void* a pointer to an address that is understood by PHP + */ + PHPCPP_EXPORT void *get_module() + { + // static(!) Php::Extension object that should stay in memory + // for the entire duration of the process (that's why it's static) + static Php::Extension extension("yourextension", "1.0"); + + // @todo add your own functions, classes, namespaces to the extension + + // return the extension + return extension; + } +} +</code></pre> +</p> + +
\ No newline at end of file |