PHP Wiki doc:scratchpad

doc:scratchpad:benchmark

2009-08-18T09:21:30+00:00

1250247529		current
Line 106:		Line 106:

	When the deploy.php script has finished, the servers are ready for installing the web applications (currently only phpBB).		When the deploy.php script has finished, the servers are ready for installing the web applications (currently only phpBB).
		+
		+	==Available files==
		+	* config.php
		+	Configuration before the deployment of the virtual machines
		+	* deploy.php START-IP
		+	Deployment script that deploys the three virtual machines to START-IP, START-IP + 1 and START-IP + 2.
		+	* functions.php
		+	Functions used for the deployment and upload/execution of commands.
		+	* installers/
		+	This is were the applications are stored
		+	* machines/
		+	This is were machine-specific files are stored, such as configuration-files and such.
		+	* roles/
		+	Here are the role-files places (files that choose which packages that are installed after the deployment)
		+	* setup.php
		+	This is a file that's included when all the servers has booted up in the deployment script and this performs configurations and additional setups.
		+	* shutdown.php
		+	This shutdowns (destroys) the virtual machines and removes the created files (ips.txt which contains the IP-adresses of the VM's) and the known_hosts file that is created when ssh and scp commands are executed.

	===phpBB3 benchmark===		===phpBB3 benchmark===

doc:scratchpad:howto

2009-09-11T13:59:53+00:00

1249385527		current
Line 1:		Line 1:
-	===== Quick guide for improving the existing PHP documentation =====	+	This page has been removed, in favor of: [[doc/howto]]
-	==== Getting setup ====	+
-		+
-	What you need is:	+
-		+
-	== Source files of the PHP Manual ==	+
-	They are stored in a SVN module named 'phpdoc'. See also the [[http://www.php.net/svn.php\|generic generic php.net SVN instructions]]. And these examples use the svn command but other methods exist, like [[http://www.tortoisesvn.net/\|TortoiseSVN]] for Windows users.	+
-	<code>	+
-	$ svn checkout http://svn.php.net/repository/phpdoc	+
-	</code>	+
-		+
-	== Using TortoiseSVN on Windows to do a checkout ==	+
-	* First off, download and install TortoiseSVN from its website: [[http://tortoisesvn.net/]]	+
-	* Open a new explorer window and go to the folder you wish to do a checkout in	+
-	* Right click anywhere in the blank area to spawn the context menu, select "SVN Checkout..."	+
-	* A new window will popup asking for details about the checkout, these values will be remembered, so you will not need to enter them again	+
-	* Enter the following URL: "http://svn.php.net/repository/phpdoc", then OK to begin the checkout. If you're prompted to enter a password while checking out, then type in "phpfi" and OK	+
-	* When the checkout is complete, then it should have created a directory called "phpdoc" where the php documentation source tree will be	+
-		+
-		+
-		+
-		+
-	== The build system ==	+
-	This renders the DocBook XML into other formats, like the HTML you see at php.net. It's named [[doc:phd\|PhD]] (See: [[doc:phd:install\|PhD install guide]])	+
-		+
-	<code>	+
-	$ pear channel-discover doc.php.net	+
-	$ pear install doc.php.net/phd-beta	+
-	</code>	+
-		+
-	== A text editor ==	+
-	Any will do	+
-		+
-	== Knowledge ==	+
-	* PHP	+
-	* The [[http://doc.php.net/php/dochowto/chapter-conventions.php\|coding standards]]:	+
-		+
-	== Everything working ==	+
-	Before you get started documenting, make sure the tool chain and checkout are okay. To do so, consider the following scenario:	+
-	<code>	+
-	$ phd -V (check to see if phd is installed, and in the path)	+
-	$ cd phpdoc (make the manual sources your current directory)	+
-	$ php configure.php -V (check to see if this works)	+
-	$ php configure.php (This will create a huge .manual.xml file which PhD uses to render the docs)	+
-	$ phd -d .manual.xml -f xhtml -t chunkedhtml (Creates an html/ folder with a few thousand files)	+
-	</code>	+
-		+
-	Poke around the html/ directory and open up some of the files in you favorite browser to see if everything is fine.	+
-	==== Knowing the structure ====	+
-		+
-	The documentation for extensions is located in:	+
-		+
-	/phpdoc/en/trunk/reference/extension_name/	+
-		+
-	For example, the SVN extension documentation exists in:	+
-		+
-	/phpdoc/en/trunk/reference/svn/	+
-		+
-	There you'll find several files:	+
-		+
-	* //book.xml// (Acts as the container for the extension and contains the preface. Other files (like //examples.xml// are included from here)	+
-	* //setup.xml// (Includes setup, install and configuration documentaiton)	+
-	* //constants.xml// (Lists all constants the extension declares, if any)	+
-	* //configure.xml// (Usually this information is in setup.xml, but if the file exists it is magically included into setup.xml)	+
-	* //examples.xml// (Various examples)	+
-	* //foo.xml// (Example, foo can be anything specific to a topic. Just be sure to include via //book.xml//)	+
-		+
-	A procedural extension (like SVN) also has:	+
-		+
-	* //reference.xml// (container for the functions, rarely contains any info)	+
-	* //functions/// (folder with one XML file per function that the extension declares)	+
-		+
-	And OO extensions (such as imagick) contain:	+
-		+
-	* //classname//.xml (container for the methods defined by the class, contains also basic info about it)	+
-	* //classname/// (folder with one XML per method that the class declares)	+
-		+
-	* Note: "//classname//" is the lowercased name of the class, not a literal file or directory name.	+
-		+
-	==== Editing existing documentation ====	+
-	Simply open the files and edit them. Remember to follow the "coding standard" described in the documentation howto. And after it validates, commit.	+
-	<code>	+
-	$ vim phpdoc/en/trunk/reference/strings/strlen.xml	+
-	$ php configure.php	+
-	$ svn commit -m "Added SeeAlso strpos()" phpdoc/en/trunk/reference/strings/strlen.xml	+
-	</code>	+
-		+
-	==== Adding new documentation ====	+
-		+
-	When adding new functions or methods, there are a couple of options. Either way, the generated (or copied) files will need to be filled out.	+
-		+
-	== Option A: Copy skeleton files ==	+
-	This involves copying the skeleton files into the correct location:	+
-		+
-	<code>	+
-	cp /phpdoc/RFC/skeletons/method.xml classname/methodname.xml (for new methods)	+
-	cp /phpdoc/RFC/skeletons/function.xml functions/functionname.xml (for new functions)	+
-	</code>	+
-		+
-	* Note: "classname" is the lowercased name of the class, not a literal file name.	+
-	* Note: "methodname" is the lowercased name of the method name, not a literal file name.	+
-	* Note: "functionname" is the lowercased name of the function name, not a literal file name.	+
-		+
-	== Option B: Generating files using docgen ==	+
-	The docgen script is found within the php documentation (phpdoc/scripts/docgen/) and uses Reflection to generate documentation (DocBook) files. See the [[doc:scratchpad:pecldocs\|PECL Docs]] section for details.	+
-		+
-	==== Testing the changes ====	+
-		+
-	Methods and functions are automagically included into the hierarchy so you don't have to "configure" anything, just run "//php configure.php//" to build the .manual.xml and validate the changes. If no error occur it means you changes validated.	+
-		+
-	<code>	+
-	$ cd phpdoc	+
-	$ php configure.php	+
-	</code>	+
-		+
-	When the above outputs something like "All good. Saving .manual.xml... done." then you know it validates. Now its time to optionally check the rendering:	+
-		+
-	<code>	+
-	$ phd -d .manual.xml -f xhtml -t chunkedhtml	+
-	</code>	+
-		+
-	This will create a "html/" directory in your current working directory. Open up the files you just added in your browser and make sure everything is fine (the filenames are taken from the "xml:id" attribute on the root element of the XML file).	+
-		+
-	If everything is looking good, its time to post the changes.	+
-	==== Committing the changes ====	+
-		+
-	== Creating patches ==	+
-		+
-	If you edited existing documentation you will have to create a patch. The following will iterate recursively over the directory and push all changes into the changes.patch file:	+
-		+
-	<code>	+
-	$ svn diff > changes.patch	+
-	</code>	+
-		+
-	If you added new files you will have to create an archive of the new files you added (tar -cf changes.tar file1.xml file2.xml file3.xml). On Windows you may use an external utility to create an archive such as [[http://www.rarsoft.com/\|WinRAR]].	+
-		+
-	Then upload the archive (or patch file) to http somewhere and post the link to phpdoc@lists.php.net including a short summary of what you did.	+
-		+
-	And later committing them yourself	+
-		+
-	== Committing patches ==	+
-		+
-	If you have SVN karma then there is no need to create patches... just commit!	+

doc:scratchpad:namespacefaq

2008-10-28T12:34:24+00:00

1225194712		current
Line 9:		Line 9:

	Q: Would removing constants/functions from namespaces make it possible to stick with "::" for namespaces?		Q: Would removing constants/functions from namespaces make it possible to stick with "::" for namespaces?
		+
		+	A: Yes, but at a cost. Functions and constants within namespaced files would throw a fatal error. [Reference needed]

	Q: Was the "::" separator was dropped because of limitations on the Zend Engine?		Q: Was the "::" separator was dropped because of limitations on the Zend Engine?

	Q: Was the fact that the "\" character is harder to type on various international keyboards considered and if so why was this character still chosen?		Q: Was the fact that the "\" character is harder to type on various international keyboards considered and if so why was this character still chosen?
		+
		+	A: Yes, it was considered. However the fact that "\" is already used in PHP means that nobody has a keyboard that actually lacks that character. There are also workarounds for those facing difficulties. [References needed]

	Q: Why was character combination XYZ (":::", "@" etc.) not chosen?		Q: Why was character combination XYZ (":::", "@" etc.) not chosen?
		+
		+	A: There have been long and intensive public discussions over the choice of namespace separator in the past, and everyone at the internals meeting was familiar with the arguments against a wide range of potential characters. The possibilities were therefore very limited, as documented on the wiki page about this decision. [Link to Lukas' entry]

	Q: Why was "\" chosen given that it makes it impossible to write something like "spl_autoload_register(array("myNamespace\theLoader", "load"));" because the \t would be interpreted as a tab?		Q: Why was "\" chosen given that it makes it impossible to write something like "spl_autoload_register(array("myNamespace\theLoader", "load"));" because the \t would be interpreted as a tab?
		+
		+	A: It is already impossible to write Windows paths in PHP in the same way, ergo at least half the PHP community is already familiar with the idea that they need to either use single quotation marks or escape the backslash ("\\").

	Q: Why do the PHP internals developer think that "\" is not prone to cause issues when typos are made?		Q: Why do the PHP internals developer think that "\" is not prone to cause issues when typos are made?
Line 22:		Line 30:
	Q: Don't the PHP internals developer think that the fact that "\" is widely used as the escape character will be cause for confusion?		Q: Don't the PHP internals developer think that the fact that "\" is widely used as the escape character will be cause for confusion?

-	Q: C++ uses "::" for namespaces, why did the PHP internals developer feel they needed to solve the ambiguity issues rather than leaving it to each developer to prevent ambiguity between namespace names and other identifiers?	+	A: No, because the usage context is completely different.
		+
		+	Q: C++ uses "::" for namespaces, why did the PHP internals developers feel they needed to solve the ambiguity issues rather than leaving it to each developer to prevent ambiguity between namespace names and other identifiers?
		+
		+	A: Ambiguity is an edge case, meaning that developers wouldn't necessarily be aware of the potential for it through their own past experience, and debugging would be extremely difficult. Further, there was no way to provide a PHP error message on ambiguity without impacting performance in all cases. [Reference needed]

	Q: Why wasn't the proposal chosen to just require "use namespace" and "use class" chosen?		Q: Why wasn't the proposal chosen to just require "use namespace" and "use class" chosen?

	Q: Do I have to prefix all my internal function names with \ now?		Q: Do I have to prefix all my internal function names with \ now?

doc:scratchpad:pecldocs

2009-03-24T17:14:59+00:00

1237914899		current
Line 17:		Line 17:
	</code>		</code>

-	This will create a directory named 'tmp' for the extension named 'extname' which will be full of documentation skeletons. Reflection is used to make guesses about the extension, like for classes, methods, functions, constants, parameters, version information, etc. but this information will not be fully correct. Please go through and edit each XML file by updating this information and adding documentation.	+	This will create a directory named 'tmp' that will contain documentation skeletons for the 'pecl' extension named 'extname'. Reflection is used to make guesses about the extension, like for classes, methods, functions, constants, parameters, version information, etc. but this information will not be fully correct. Please go through and edit each XML file by updating this information and adding documentation.

	* Read the Validating Changes section of the [[doc:scratchpad:howto\|PHP Documentation HOWTO]].		* Read the Validating Changes section of the [[doc:scratchpad:howto\|PHP Documentation HOWTO]].

doc:scratchpad:upgrade

2008-09-16T18:26:22+00:00

1210785755		current
Line 1:		Line 1:
	===== Upgrade and Migration information =====		===== Upgrade and Migration information =====
-	Information found here will one day live within the migration section of the PHP Manual. See the manual pages for [[http://php.net/migration51\|5.2]] and [[http://php.net/migration52\|5.2]] for example manual pages.	+	Information found here will one day live within the migration section of the PHP Manual. See the manual pages for [[http://php.net/migration51\|5.1]] and [[http://php.net/migration52\|5.2]] for example manual pages.

	* [[doc:scratchpad:upgrade:53\|5.3.0]]		* [[doc:scratchpad:upgrade:53\|5.3.0]]

doc:scratchpad:wheretohelp

2009-04-27T01:48:51+00:00

	current
Line 1:	Line 1:
	+	===== Source Development =====
	+
	+	The source code behind PHP is managed through the versioning system CVS. There are three active branches:
	+	* PHP 5.2 (Stable) is branched as PHP_5_2
	+	* PHP 5.3 (Development) is branched as PHP_5_3
	+	* PHP 6.0 (Alpha) is HEAD, so named php-src
	+
	+	In CVS, when checking out these modules it will also automagically include the TSRM, Zend and ZendEngine2 modules.
	+
	+	==== Getting the source code ====
	+	There are two main methods for getting the latest PHP source files, either directly from CVS or by downloading a Snapshot
	+
	+	=== CVS ===
	+	This is where developers actively add/modify code. A few differences from snaps:
	+	* You can write patches or commit to CVS
	+	* You can test the build tools via buildconf
	+	* Should specify the branch when checking out
	+
	+	=== Snapshots ===
	+	Each branch is built around four times a day, and the snapshots system runs a few scripts in order to lesson the burden of required tools for building. A few differences from CVS:
	+	* Snaps do not require all build tools like buildconf and flex
	+	* It's easier to deal with
	+	* Can refer to a specific snap when reporting bugs
	+
	+	==== Building ====
	+	Because PHP is a glue for many other libraries, often times third-party libraries are required to build it. For example, if you want to build in Postgresql support then the server doing the build requires access to PostgreSQL and its developmental (head) files. When a system uses packages or RPMs, often times this means also installing foo-dev or foo-devel packages as they contain the needed header files.
	+
	+	The PHP configure system checks for these libraries and will inform you if they are missing.
	+
	+	=== Configuration options specific to developers ===
	+	* --enable-debug : this includes extra symbols
	+	* --maintainer-zts : ...
	+	* valgrind
	+	* gdb
	+	* ...
	+
	+	==== Learning how to write php-src code ====
	+	* Internals docs
	+	* Example extension
	+	* All PECL extensions (CVS)
	+
	+	=== Writing an extension ===
	+	* What is PECL?
	+	* Why PECL?
	+
	+	===== Bugs =====
	+	The bugs system is used to report bugs and feature requests for internals and related activities like the documentation and php.net website.
	+
	+	* Finding open bugs
	+	* Reporting bugs
	+	* Submitting patches
	+	* Generating a back trace
	+
	+	===== Writing Tests =====
	+	Writing tests means ...
	+	* A test example
	+	* Code coverage
	+
	+	===== Documentation =====
	+	* How we do it
	+	* How you can do it
	+	* What is needed now
	+	* HOWTO
	+	* Determine different types of documentation
	+	* developer (internals)
	+	* extension (for a specific extension)
	+	* installation (for installing php somewhere)
	+	* general (for anything else)
	+	* the howto itself
	+	* user notes
	+	* other wiki stuff
	+
	+	===== Communication =====
	+	* How to contact developers
	+	* How to contact an extension maintainer
	+	* What to do if the maintainer does not reply
	+	* Different modes of communication (mail, irc)
	+	* If nobody replies in irc, it could be because ...