fixed some compiler warnings in value.cpp, added documentation on how to install PHP-CPP, removed the Makefile from the src directory and moved everything into the single Makefile in the library root directory, also updated the main (and now only) Makefile with instructions so that it is easier for others to understand

5 files changed, 269 insertions, 57 deletions

diff --git a/Makefile b/Makefile
index 8209a7e..30b83c6 100644
--- a/Makefile
+++ b/Makefile
@@ -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