Documentation

The PHP3 documentation is a great piece of work. Many, many thanks to Stig. There are many things, which should be done better in a new version of doc for PHP. I have seen better examples in the net. Currently I'm ill, so I have a little bit time to think about documentation. I think it's the right time to do this. So I would start with it with the same method I started the last time this discussion: I made a content description. Like the last time I take the top-down method for this. And I orientate myself much more on the currently existing PHP3 documentation. - FRONTPAGE - Copyright/Lizense of doc - Dedication - TOC - Preface and About [something about the authors?] - Language Reference !- Function Reference !- Installing and Configuration - Appendixes You see the main difference is, that the big block "Language Reference" is splitted into the logical parts Function Reference and Installing and Configuration. This is mainly to strip the docs into logical parts, which can "stand alone" without the rest. This chapter is not thought for absolute programming beginners (they should buy a book), it should be a very good language reference. So it is not written in the order of how you learn a language, it is written for the needs of a programmer, when he is looking for something. There are the following chapters: -------------------------------------------------------------------- - An introduction to PHP4 - PHP4 features - ZEND ... !- How does configuration influence the behavior of PHP4 language? ! A more or less detailed description about how some ! configuration-parameters are influencing the language itself. For ! more information about the parameters link to Installing and ! Configuration. - Syntax and Grammar The ideas for the following chapters I have "stolen" from Christian Köhntopp :-) and Alfred Wassermann. There are also some more ideas, from myself. I tried to mix them up to get a better result. - Enbedding PHP4 in HTML/Escaping from HTML - Hello World (an example program) - Instruction separation - format free - with ; or ?><?php - Variables This part is in the current doc very big and it must be bigger. - Types - int - string - double - boolean (?) - definition of true an false (false: 0, 0.0, "", "0" and array() - not like in C!) - array - hashes (associative arrays) - arrays of arrays - function (?) - object (Is an object-definition a language construct or a variable definition?) - special variables of some function classes - Syntax - what is a correct - variable-name? - hash? - strings - "-syntax and escaping inside string - '-syntax " - "' are not needed inside hashes (where else?) - very long strings - Variable - variables - functions - objects (?) - Bind variable variables and arrays correct while using {}-constuctor - Variables inside of strings there are different rules in syntax inside a string: echo "$a"; echo "$a[$b]" ; echo "${a[$b]}"; ... etc. - Initializing - =-operator; inbuilt type declaration, see down - Values of uninitalized vars - isset() versus empty() - Warnings (how to put them on and why - BTW: I havn't found this option any more) - Type juggling and traps - what happens if you don't care the type some examples, which will bring the wrong result - Determining variable types 1 or more examples with any type, array aggregate constructor, objects and e.g. a filepointer and what types they become - Type casting - String conversion with a example part - External/predefined variables - use phpinfo() to see external variables - External variables from GET/POST-Method (Forms) or COOKIES - HTTP_POST/GET/COOKIE_VARS with an example code of how to output all vars - Image Submit (where is it gone?) - Checkbutton/Radio (<INPUT NAME="a[]">) - assoc Arrays in HTML versus JavaScript - GPC-Order - poisoning of global name space! - Environement-Variables - what is correct use of PHP_SELF, SERVER_HOME etc. ... - Special variables, values and constants - GLOBALS[] - GLOBALS and variable variables (use that instead) - __FILE__, __LINE__ - Constants (define()) - Scope - no global scope - see functions - Some more information about Arrays - Array manipulation - an example with a short translation list $woche=ARRAY(Sun=>Sonntag,Mon=>Montag,... Fri=>Freitag); echo 'Heute ist '. $woche[Date("D")]; - how they are handled internally (a list of hashes) - Count(), internal array pointer ( $a[]=$i ; each(); list() ) - don't use prev(), next()..., use each() and list() instead - Include versus Require - lexer/scanner-level - require is faster - include can do more - include-path - Spaces/newlines at end of include - Name of includes and use other endings for includes (e.g. .inc or .ihtml), make them invisible in your server - Functions - Syntax - Remember the scope! - Return Values - GLOBAL-construct - STATIC-construct - Arguments - Call by Reference - Default/predefined variables (optional parameters) - Classes - Syntax - vocabulary (class, instance) - how to create a new instance - example - Operators A table of all operators: operator operation precedence example/comment - $i = $i + 1 -> $i += 1 -> $i =+ 1 -> $i++ - Control-Structures - An overview to expressions - IF - else - elseif - Short-if: ( ) ? : - SWITCH - smarter than C - LOOPS - while - do..while - for - foreach - break - continue - Blocks {} - Alternate Syntax (:) - sometimes clearer than C-Syntax - ARRAY - LIST - EVAL - EXIT, DIE - Death Duties Languages constructs, which are inside of PHP4 but shouldn't be used any more - old_function - doubleval, strval (?) - prev, next, key, current ... ----------------------------------------------------------------- The next chapter is the Function Reference. I have been looking into the current one many times. I don't like it. It is so big and it is not ordered very sensible. It's very easy to forget, that there is a function, which does exactly what I want, but I havn't found it, cause it is anywhere in the docs. First I would split it up in to some bigger parts, which meets more my needs: - Arrays and Objects - Internal and Miscellaneous - Functions (Strings, Regex, Math) - Date/Time - Filesystem and Execution - Network, HTTP and Apache - Special Modules (Image, PDF, Mail, IMAP, SNMP, GZ, XML) - Databases - All functions by module (this is the current state) This is the order how I as a programmer would prefer to search for functions. It would not include the complete reference to every function, but only the lists of the short descriptions. Most times this is enough, and if you want to get more information you can look in the module-reference Now fine work: The Arrow -> means, that there will a list of functions and I want the user to read the corresponding module documentation for more information. ------------------------------------------------------------------ - Arrays and Objects - -> Arrays - Date-Object - Dir-Object - ? - Internal and Miscellaneous - -> Apache Specific functions - -> Dynamic Loading functions - -> PHP Options and Information - -> Miscellaneous PHP-Functions - Functions (Strings, Regex, Math, Variables) - -> BC (Arbitrary Precision) Functions - -> Mathematical Functions - -> Regular Expression Functions - -> String Functions - -> URL Functions - -> Variable Functions - Date/Time - -> Calendar Functions - -> Date/Time Functions - Filesystem and Execution - -> Programm Execution Functions - -> Directory Functions - -> Filesystem Functions - -> GZ-File Functions - Network, HTTP and Apache - Apache Specific Functions -> Internal and Misc. - fopen with an URL! - -> Functions related to HTTP - -> Network Functions - Mail Functions -> Special Modules - IMAP Functions -> Special Modules - SNMP Functions -> Special Modules - Special Modules (Image, PDF, Mail, IMAP, SNMP, GZ, XML) - -> Image Functions - GetImageSize() does always work - -> PDF Functions - -> Mail Functions - -> SNMP Functions - GZ -> Filesystem Functions - -> XML Functions - Databases - yumm, everything else - All functions by module (this is the current state) So, I think this is enough for one day. :-) -- SSilk - Alexander Aulbach - Herbipolis/Frankonia Minoris - (0931)22032