diff options
| -rw-r--r-- | Makefile | 148 | ||||
| -rw-r--r-- | documentation/install.html | 108 | ||||
| -rw-r--r-- | documentation/tutorial.html | 26 | ||||
| -rw-r--r-- | src/Makefile | 23 | ||||
| -rw-r--r-- | src/value.cpp | 21 |
5 files changed, 269 insertions, 57 deletions
@@ -1,21 +1,141 @@ -PREFIX = /usr -INCLUDE_DIR = ${PREFIX}/include -LIBRARY_DIR = ${PREFIX}/lib +# +# PHP-CPP Makefile +# +# This makefile has a user friendly order: the top part of this file contains +# all variable settings that you may alter to suit your own system, while at +# the bottom you will find instructions for the compiler in which you will +# probably not have to make any changes +# -all: - cd src; $(MAKE) +# +# Zend header files +# +# The variable PHP_DIR contains the location on your system where the regular +# header files of the Zend engine can be found. Usually this is either +# /usr/include/php5 or /usr/local/include/php5. Inside this directory you +# will find sub-directories named TSRM, Zend, ext and main. +# -tests: - cd tests; $(MAKE) +PHP_DIR = /usr/include/php5 + + +# +# Installation directory +# +# When you install the PHP-CPP library, it will place a number of C++ *.h +# header files in your system include directory, and a libphpcpp.so shared +# library file in your system libraries directory. Most users set this to +# the regular /usr/include and /usr/lib directories, or /usr/local/include +# and /usr/local/lib. You can of course change it to whatever suits you best +# + +INSTALL_PREFIX = /usr +INSTALL_HEADERS = ${INSTALL_PREFIX}/include +INSTALL_LIB = ${INSTALL_PREFIX}/lib + + +# +# Name of the target library name +# +# The PHP-CPP library will be installed on your system as libphpcpp.so. +# This is a brilliant name. If you want to use a different name for it, +# you can change that here +# + +RESULT = libphpcpp.so + + +# +# 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 a single .so +# library file. By default, g++ (the GNU C++ compiler) is used for both. +# + +COMPILER = g++ +LINKER = g++ + + +# +# Compiler 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). +# + +COMPILER_FLAGS = -Wall -c -I. -I${PHP_DIR} -I${PHP_DIR}/main -I${PHP_DIR}/ext -I${PHP_DIR}/Zend -I${PHP_DIR}/TSRM -O2 -std=c++11 -fpic -o + + +# +# Linker flags +# +# Just like the compiler, the linker can have flags too. The default flag +# is probably the only one you need. +# + +LINKER_FLAGS = -shared + + +# +# 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 + + +# +# The source files +# +# For this we use a special Makefile function that automatically scans the +# src/ directory for all *.cpp files. No changes are probably necessary here +# + +SOURCES = $(wildcard src/*.cpp) + + +# +# The object files +# +# The intermediate object files are generated by the compiler right before +# the linker turns all these object files into the libphpcpp.so shared library. +# We also use a Makefile function here that takes all source files. +# + +OBJECTS = $(SOURCES:%.cpp=%.o) + + +# +# End of the variables section. Here starts the list of instructions and +# dependencies that are used by the compiler. +# + +all: ${OBJECTS} ${RESULT} + +${RESULT}: ${OBJECTS} + ${LINKER} ${LINKER_FLAGS} -o $@ ${OBJECTS} clean: - cd src; $(MAKE) clean -# cd tests; $(MAKE) clean + ${RM} ${OBJECTS} ${RESULT} + +${OBJECTS}: + ${COMPILER} ${COMPILER_FLAGS} $@ ${@:%.o=%.cpp} install: - mkdir -p ${INCLUDE_DIR}/phpcpp - mkdir -p ${LIBRARY_DIR} - cp -f phpcpp.h ${INCLUDE_DIR} - cp -f include/*.h ${INCLUDE_DIR}/phpcpp - cp -f src/libphpcpp.so ${LIBRARY_DIR} + ${MKDIR} ${INSTALL_HEADERS}/phpcpp + ${CP} phpcpp.h ${INSTALL_HEADERS} + ${CP} include/*.h ${INSTALL_HEADERS}/phpcpp + ${CP} ${RESULT} ${INSTALL_LIB} diff --git a/documentation/install.html b/documentation/install.html new file mode 100644 index 0000000..aa3df2c --- /dev/null +++ b/documentation/install.html @@ -0,0 +1,108 @@ +<div style="width: 1024px; font-family: verdana; font-size: 10pt; line-height: 16pt;"> + + +<h1>How to install PHP-CPP</h1> +<p> + Before you can build your own super fast native PHP extension using the + PHP-CPP library, you will first have to install the PHP-CPP library on your + systems(s). +</p> +<p> + Luckily, for most of us (those who use Linux environments), this will be + a piece of cake. If you're on a different platform however, you are left on + your own, because we (as in me, the PHP-CPP developer), only uses Linux + systems. There is however no reason why this library should not also work on + other platforms, because it only uses straight forward C++ code. Thus, if + you are on a different platform and have managed to compile the library on + it, please give us feedback so that we can update these installation + instructions and include other platforms as well. +</p> + + +<h2>Limitations</h2> +<p> + At this moment, PHP-CPP only supports single-threaded PHP installations. + Web servers come in a number forms: there are the ones that handle each + page request in different process, and the ones that handle each page request + in the same process, but in a different thread. If you're using such a + multi-threaded PHP installation, you can not use the PHP-CPP library. Most + installations are single-threaded however, so this should not be a show stopper. +</p> +<p> + Are you not sure whether you have a single-threaded or multi-threaded PHP + environment? Just try to compile the PHP-CPP library, if you see a zillion + errors, you can be pretty sure that this is because of your installation + is multi-threaded. +</p> +<p> + The reason why we've chosen not to support multi-threaded PHP installations + lies in the fact that internally the Zend engine uses a very odd system + to ensure thread safety. Essentially, they pass an additional parameter to + each and every function call that holds a pointer-to-a-pointer with thread + information that you can access with specific C macro's, and that you have + to pass on to every other function call that you make. This makes life for + extension writers much harder than is necessary - and is in total conflict + 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 + installations, and hopefully we can even keep the same simple C++ API as we + have now. +</p> + + + +<h2>Download</h2> +<p> + 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 + <a href="https://github.com/CopernicaMarketingSoftware/PHP-CPP">GitHub</a>. +</p> +<p> + To get the latest GitHub version, run the following command from the command + line: +</p> +<p> + <code><pre> + git clone https://github.com/CopernicaMarketingSoftware/PHP-CPP.git + </pre></code> +</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. +</p> +<p> + The Makefile is a file that holds settings and instructions for the compiler. + In 96 out of 100 situations, the default settings in this Makefile will + already be perfect for you, but you may want to have a look at it and make + (small) changes to it. You can for example change the installation directory, + and the compiler that is going to be used. +</p> +<p> + After you've checked that all settings in the Makefile are correct, you can + build the software. Do this by running the following command from within + the PHP-CPP directory. +</p> +<p> + <code><pre> + make + </pre></code> +</p> +<p> + The PHP-CPP library has now been built, and all that is left to do is + install it on your system. You can use the "make install" command for it. + This command should be executed as root, either by using "sudo", or by + logging on as root first. +</p> +<p> + <code><pre> + sudo make install + </pre></code> +</p> +<p> + Congratulations! You are now the happy owner of a system with PHP-CPP installed + and nothing can stop you from building your first fast native PHP extension. +</p> diff --git a/documentation/tutorial.html b/documentation/tutorial.html index 30d8ea7..ff2bbbc 100644 --- a/documentation/tutorial.html +++ b/documentation/tutorial.html @@ -13,9 +13,9 @@ <h2>How does PHP load its extensions?</h2> <p> You probably already know that native PHP extensions are compiled into *.so - files on unix-like systems, and *.dll files on Windows environments, and that + files on unix-like systems, and *.dll files in Windows environments, and that the global php.ini file holds a list of all extensions available on your system. - This means that if you're building your own extension, you will also need to + This means that if you're building your own extension, you are also going to create such a *.so or *.dll file and you will need to update the PHP configuration so that your own extension is loaded by PHP. </p> @@ -52,7 +52,7 @@ <h2>The get_module() startup function</h2> <p> Before we explain how you can create your own extension however, we first explain - what PHP does to load an extension. When PHP starts, it loads the configuration + what PHP does to load an extension. When PHP starts, it loads the *.ini configuration file(s) that we just described and for each "extension=name.so" line in these files, it opens the appropriate library, and calls the "get_module()" function from it. Each extension library (your extension too) must therefore @@ -214,7 +214,7 @@ PHPCPP_EXPORT void *get_module() { static Php::Extension myExtension("my_extension", "1.0"); myExtension.add("example", example, { - Php::ByVal("a", Php::numericType), + Php::ByVal("a", Php::Type::Numeric), Php::ByVal("b", "ExampleClass"), Php::ByRef("c", "OtherClass") }); @@ -224,15 +224,15 @@ </pre></code> </p> <p> - Above you see that we pass in additional information when we register the - - - - The Extension::add() method can be used to register native functions, and - make them available in PHP. In the examples above, you've seen that the - method takes two parameters: the name the function shou - - + Above you see that we passed in additional information when we registered the + "example" function. We tell our extension that our function accepts three parameters: + the first parameter must be a regular number, while the other ones are object + instances of type "ExampleClass" and "OtherClass". In the end, your native C++ + "example" function will still be called with a Php::Parameters instance, but + the moment it gets called, you can be sure that the Php::Parameters object + will be filled with three members, and that two of them are objects of the + appropriate type, and that the third one is also passed by reference. +</p> <h2>Working with variables</h2> <p> Variables in PHP are non-typed. A variable can thus hold any possible type: diff --git a/src/Makefile b/src/Makefile deleted file mode 100644 index 64b4eb1..0000000 --- a/src/Makefile +++ /dev/null @@ -1,23 +0,0 @@ -CPP = g++ -RM = rm -f -PHP_DIR = /usr/include/php5 -CPP_FLAGS = -c -I. -I${PHP_DIR} -I${PHP_DIR}/main -I${PHP_DIR}/ext -I${PHP_DIR}/Zend -I${PHP_DIR}/TSRM -g -std=c++11 - -LD = g++ -LD_FLAGS = -Wall -shared -O2 -RESULT = libphpcpp.so - -SOURCES = $(wildcard *.cpp) -OBJECTS = $(SOURCES:%.cpp=%.o) - -all: ${OBJECTS} ${RESULT} - -${RESULT}: ${OBJECTS} - ${LD} ${LD_FLAGS} -o $@ ${OBJECTS} - -clean: - ${RM} *.obj *~* ${OBJECTS} ${RESULT} - -${OBJECTS}: - ${CPP} ${CPP_FLAGS} -fpic -o $@ ${@:%.o=%.cpp} - diff --git a/src/value.cpp b/src/value.cpp index b43d72f..1bec146 100644 --- a/src/value.cpp +++ b/src/value.cpp @@ -329,6 +329,9 @@ Value &Value::operator=(Value &&value) // the other object is no longer valid value._val = nullptr; } + + // done + return *this; } /** @@ -1201,13 +1204,17 @@ Value &Value::setType(Type type) // run the conversion switch (type) { - case Type::Null: convert_to_null(_val); break; - case Type::Numeric: convert_to_long(_val); break; - case Type::Float: convert_to_double(_val); break; - case Type::Bool: convert_to_boolean(_val); break; - case Type::Array: convert_to_array(_val); break; - case Type::Object: convert_to_object(_val); break; - case Type::String: convert_to_string(_val); break; + case Type::Null: convert_to_null(_val); break; + case Type::Numeric: convert_to_long(_val); break; + case Type::Float: convert_to_double(_val); break; + case Type::Bool: convert_to_boolean(_val); break; + case Type::Array: convert_to_array(_val); break; + case Type::Object: convert_to_object(_val); break; + case Type::String: convert_to_string(_val); break; + case Type::Resource: throw Php::Exception("Resource types can not be handled by the PHP-CPP library"); break; + case Type::Constant: throw Php::Exception("Constant types can not be assigned to a PHP-CPP library variable"); break; + case Type::ConstantArray: throw Php::Exception("Constant types can not be assigned to a PHP-CPP library variable"); break; + case Type::Callable: throw Php::Exception("Callable types can not be assigned to a PHP-CPP library variable"); break; } // done |