PHP Wiki - doc:articles

localdocsetup

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2011/06/14 05:55		current
Line 1:		Line 1:
-	====== Checking out, building, and viewing the PHP documentation on an unofficial php.net mirror ======	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/local-setup.php\|new guide]]
-		+
-	Viewing results as a php.net mirror isn't a simple process, but it can be done. The following is one route, and it assumes:	+
-		+
-	* PHP 5.3+ is available	+
-	* A web server, specifically (in this example) Apache	+
-	* The rsync tool is available	+
-	* A basic level of shell/terminal usage, or know that shell commands follow a $ below	+
-	* A desire to build and display the documentation locally	+
-	* Your PHP Documentation path will be: /tmp/svn/doc-en (change this no doubt)	+
-	* Your local mirror path will be: /home/sites/myphpnet/ (change this no doubt)	+
-	* Your local hostname will be: http://mydocs.site/ (change this no doubt)	+
-	* You are using Linux or a Mac (@todo Make this guide Windows friendly)	+
-		+
-	If you're interested in simply setting up a local PHP mirror (and NOT build the documentation) then simply follow the [[http://php.net/mirroring\|php.net mirroring guidelines]] and ignore this document.	+
-		+
-	===== Checkout the php documentation from SVN =====	+
-		+
-	Assumptions: This assumes using /tmp as the root directory, and checkout of the English language. Adjust accordingly.	+
-		+
-	==== Option #1 : Traditional ====	+
-	<code shell>	+
-	$ mkdir /tmp/svn	+
-	$ cd /tmp/svn	+
-	$ svn co https://svn.php.net/repository/phpdoc/modules/doc-en doc-en	+
-	$ cd /tmp/svn/doc-en	+
-	</code>	+
-	==== Option #2 : Automated ====	+
-	<code shell>	+
-	$ cd /tmp	+
-	$ wget https://svn.php.net/repository/phpdoc/doc-base/trunk/scripts/create-phpdoc-setup.php	+
-	$ php create-phpdoc-setup.php -h	+
-	$ php create-phpdoc-setup.php -b /tmp/svn -l en	+
-	$ cd /tmp/svn/doc-en	+
-	</code>	+
-	===== Validate the PHP Documentation XML =====	+
-	<code shell>	+
-	$ cd /tmp/svn/doc-en	+
-	$ php doc-base/configure.php	+
-	</code>	+
-	===== Build the documentation =====	+
-		+
-	We use PhD to build the documentation. It takes the source that configure.php generates, and builds and formats the PHP documentation. PhD offers several formats including HTML (multiple or single page), PDF, Man, Epub, and others, including PHP which is what we use at php.net.	+
-		+
-	==== Install PhD ====	+
-		+
-	=== Option #1 : Traditional ===	+
-		+
-	Requirements: PEAR, and an SSL enabled PHP version greater than 5.3.0.	+
-	<code shell>	+
-	$ pear install phpdocs/PhD	+
-	$ pear install phpdocs/PhD_Generic phpdocs/PhD_PHP	+
-	$ phd --help	+
-	</code>	+
-	=== Option #2 : Automated ===	+
-		+
-	The create-phpdoc-setup.php installs PhD.	+
-		+
-	==== Use PhD to build the documentation ====	+
-	<code shell>	+
-	$ cd /tmp/svn/doc-en	+
-	$ php doc-base/configure.php	+
-	$ phd --docbook /tmp/svn/doc-en/doc-base/.manual.xml --package PHP --format php --output mydocs	+
-	$ cd /tmp/svn/doc-en/mydocs/php-web/	+
-	$ ls	+
-	</code>	+
-	Note: This builds the php.net version of the documentation, but does not contain the files and includes used to run php.net. In other words, files like the php.net headers and footers are not built by PhD and are instead stored in a separate SVN module (web/php).	+
-		+
-	Alternative: The XHTML format is simple and does not require mirroring the php.net website. The following builds manual pages as plain HTML files:	+
-	<code shell>	+
-	$ cd /tmp/svn/doc-en	+
-	$ phd --docbook /tmp/svn/doc-en/doc-base/.manual.xml --package PHP --format xhtml --output mydocs	+
-	$ cd /tmp/svn/doc-en/mydocs/php-chunked-xhtml/	+
-	$ open function.strlen.html	+
-	</code>	+
-	===== Setup a local php.net mirror =====	+
-		+
-	==== Setup an Apache virtual host ====	+
-		+
-	The official PHP mirroring documentation contains a detailed example for doing this, but here's a simpler example:	+
-		+
-	==== Download (rsync) the php.net files ====	+
-		+
-	<code shell>	+
-	$ rsync -avzC --timeout=600 --delete --delete-after --exclude='manual/' --exclude='distributions/' --exclude='extra/' --exclude='backend/notes/' rsync.php.net::phpweb /home/sites/myphpnet/	+
-	</code>	+
-		+
-	==== Symlink (or move) the generated PHP documentation to your local php.net sources ====	+
-		+
-	<code shell>	+
-	$ ln -s /tmp/svn/doc-en/mydocs/php-web /home/sites/myphpnet/manual/en	+
-	</code>	+
-		+
-	==== Configure Apache ====	+
-		+
-	* Open the apache configuration file (e.g., apache.conf, httpd.conf, apache/conf.d/virtualhosts/myphp.site, ...)	+
-	* Add the virtual host:	+
-		+
-	<code>	+
-	*<VirtualHost >**	+
-	<Directory /home/sites/myphpnet>	+
-	Options -Indexes -MultiViews	+
-	</Directory>	+
-		+
-	ServerName myphp.site	+
-	DocumentRoot /home/sites/myphpnet/	+
-		+
-	# Set directory index	+
-	DirectoryIndex index.php index.html	+
-		+
-	# Handle errors with local error handler script	+
-	ErrorDocument 401 /error.php	+
-	ErrorDocument 403 /error.php	+
-	ErrorDocument 404 /error.php	+
-		+
-	# Add types not specified by Apache by default	+
-	AddType application/octet-stream .chm .bz2 .tgz .msi	+
-	AddType application/x-pilot .prc .pdb	+
-		+
-	# Set mirror's preferred language here	+
-	SetEnv MIRROR_LANGUAGE "en"	+
-		+
-	RemoveHandler var	+
-		+
-	# Turn spelling support off (which would break URL shortcuts)	+
-	<IfModule mod_speling.c>	+
-	CheckSpelling Off	+
-	</IfModule>	+
-	</VirtualHost>	+
-	</code>	+
-		+
-	* Adjust /etc/hosts by adding the following:	+
-	<code>	+
-	127.0.0.1 myphp.site	+
-	</code>	+
-	* Restart Apache	+
-	<code shell>	+
-	$ sudo apachectl restart	+
-	</code>	+
-	===== View the new site =====	+
-		+
-	* http://myphp.site/manual/en/	+

newtranslation

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2008/05/11 00:50		current
Line 8:		Line 8:
	* Update CVSROOT/modules		* Update CVSROOT/modules
	* Update CVSROOT/loginfo		* Update CVSROOT/loginfo
		+	* Update CVSROOT/avail (in a couple places)
	* Add {lang} to docweb for revcheck		* Add {lang} to docweb for revcheck
	* Add {lang} to phpweb/includes/languages.inc as INACTIVE		* Add {lang} to phpweb/includes/languages.inc as INACTIVE
	* Add the new {lang} mailing list to our super secret gmail doc account (user php.doc.lists)		* Add the new {lang} mailing list to our super secret gmail doc account (user php.doc.lists)

nomenclature

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2012/01/10 01:17		current
Line 1:		Line 1:
-	====phpdoc Nomenclature and Style Guide====	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/style.php\|new guide]]
-		+
-	==Purpose==	+
-	This document exists to clarify the nomenclature and grammatical style of the PHP Manual.	+
-		+
-	==Reference==	+
-	As a general rule, American English (and not British/International English) should be used. Various resources are available at http://dict.org/.	+
-	Various grammar rules, like for affect vs. effect, there vs their, can be found here: http://owl.english.purdue.edu/handouts/grammar/	+
-		+
-	* note: I (Sean) don't care if we choose International English over American (I _am_ Canadian, after all). I just think we should choose one or the other, and stick to it	+
-	* note: I (Aidan) think American english sucks, I'd prefer International.	+
-	* note: I (Techtonik) also think International is better, because it is the language learned in many countries as foreign.	+
-	* note: I (Tularis) agree that International would be better fitting. There's a reason why it's often called International after all. As Techtonik noted above, the International version is what is taught in schools here aswell (Netherlands), though people often use a combination of both American English and International English.	+
-		+
-	==Examples==	+
-	* color, not colour	+
-	* favorite, not favourite	+
-		+
-	===Punctuation===	+
-	Punctuation in the PHP Manual follows regular grammatical rules. When writing flowing sentences, such as in function descriptions, normal punctuation should be used. Lists, titles, and sentence fragments should not be punctuated with a period. Sentences need not have two spaces between them. Commas and apostrophes should be used appropriately.	+
-		+
-	===Personalization===	+
-	The PHP Manual is a technical document, and should be written so. The use of "you" is rampant in the manual, and presents an unprofessional image.	+
-		+
-	===Exceptions===	+
-	The only exceptions to the personalization rule are:	+
-	* The PHP Tutorial	+
-	* FAQs	+
-		+
-	==Examples==	+
-	(from strip_tags	+
-		+
-	"You can use the optional second parameter to specify tags which should not be stripped."	+
-		+
-	should be:	+
-		+
-	"The optional second parameter may be used to specify tags which should not be stripped."	+
-		+
-	===Quantifiers===	+
-	The use of "less" vs. "fewer" can be confusing. As a general rule, "less" is used when the subject	+
-	cannot be precisely quantified.	+
-		+
-	==Examples==	+
-	* "The new version is less buggy" is correct.	+
-	* "There are less bugs in the new version" should be "There are fewer bugs in the new version."	+
-		+
-	===Chronology===	+
-	When referring to a specific version of PHP, "since" should not be used. "As of" should be used in this case.	+
-	Although the new style will not have this structure (a CHANGELOG instead), it's still good to know :)	+
-		+
-	==Example==	+
-	As of PHP 5, the return value is an array, not bool.	+
-		+
-	===General Grammar===	+
-	The PHP Manual should be written with particular attention to general English grammar. Contractions should	+
-	be used appropriately. Special attention should be applied to sentence construction when using prepositions	+
-	(ie, sentences should not end in prepositions).	+
-		+
-	===PHP Manual Terms===	+
-	Various non-english, technical terms are used throughout the PHP Manual, without clear indication of their	+
-	appropriate spelling. The following list clears up this issue:	+
-		+
-	^Appropriate Use ^ Inappropriate Use(s) ^	+
-	\|any way\|anyway, anyways\|	+
-	\|appendices\|appendixes\|	+
-	\|built-in\|built in, builtin\|	+
-	\|command line\|commandline, CLI\|	+
-	\|email\|e-mail\|	+
-	\|[[http://pear.php.net/manual/en/standards.exampleurls.php\|example.com]]\|php.net,google.com\|	+
-	*\|Linux\|linux, nx, nix, nux, etc\|*	+
-	\|PHP 4\| PHP4, PHP-4\|	+
-	\|PHP 5\| PHP5, PHP-5\|	+
-	\|PHP 4.3.0 \| PHP 4.3, PHP 4.3.0RC2, PHP 5.0.0BETA, PHP 4.3.0PL1\|	+
-	\|superglobals\|super globals, autoglobals\|	+
-	\|web server\|webserver\|	+
-	\|extension\|module\|	+
-	\|Windows\|windows (when referring to Microsoft Windows)\|	+
-	\|Unix\|UNIX, UNIX is a registered trademark\|	+
-	*\|the foo page [[http://www.w3.org/QA/Tips/noClickHere\|]]\|click here,go here\|**	+
-		+
-	!!TODO: Alphabetize this, add more!!	+

phd_ide

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2011/07/08 13:31		current
Line 49:		Line 49:
	=== SQLite 3 ===		=== SQLite 3 ===
	<code bash>		<code bash>
-	$ phd --docbook path/to/.manual.xml -- package IDE --format sqlite	+	$ phd --docbook path/to/.manual.xml --package IDE --format sqlite
	</code>		</code>
	==== Conclusion ====		==== Conclusion ====

	The PhD_IDE PhD package allows customizing the output of the PHP Manual. It takes DocBook XML and converts it to a PHP object containing all (most) of the functions documentation. The main purpose is to allow IDE's to build syntax files for code insight and PHP documentation, but its usage is flexible.		The PhD_IDE PhD package allows customizing the output of the PHP Manual. It takes DocBook XML and converts it to a PHP object containing all (most) of the functions documentation. The main purpose is to allow IDE's to build syntax files for code insight and PHP documentation, but its usage is flexible.

updating-markup

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2009/02/16 22:42		current
Line 1:		Line 1:
-	Updating PHP docs to the new markup	+	==== Updating PHP docs to the new markup ====

	Several PHP extensions have documentation for OO-style APIs which is written as if the documentation was a procedural API. A good example of this was ext/soap, but also ext/rar seems to be using the old markup too. So, I'm going to take this as my example. If you go to http://php.net/rar, and look over the methods of the Rar class, you can see they're documented just the same as the functions rar_close(), rar_entry_get(), etc. This isn't handy and makes the search less useful. There is a new variant of the DocBook markup which makes more sense for OO APIs, and it should be converted. This is basically a copy and paste job.		Several PHP extensions have documentation for OO-style APIs which is written as if the documentation was a procedural API. A good example of this was ext/soap, but also ext/rar seems to be using the old markup too. So, I'm going to take this as my example. If you go to http://php.net/rar, and look over the methods of the Rar class, you can see they're documented just the same as the functions rar_close(), rar_entry_get(), etc. This isn't handy and makes the search less useful. There is a new variant of the DocBook markup which makes more sense for OO APIs, and it should be converted. This is basically a copy and paste job.
Line 39:		Line 39:

	TODO: Describe fixing user notes.		TODO: Describe fixing user notes.
		+	TODO: Describe how to deal with old CVS history... links to old files should be in the commit message at least.

whitespace

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2011/04/06 10:59		current
Line 1:		Line 1:
-	====== Why we care about whitespace ======	+	This page has been removed, in favor of [[http://doc.php.net/tutorial/whitespace.php\|new guide]]
-	I just wanted to post a little reminder about why we care so much about whitespace. Over the years this topic has come up in many forms, usually via a whitespace unfriendly commit that is immediately followed by a fellow team members complaint. And soon after, a fix is made. There are reasons we as a group (especially all past and present editors) have been strict and anal about this topic and here's why:	+
-		+
-	==== Consistent look to the documentation ====	+
-	All the documentation ends up looking the same within all editors. The indention here is one space, no tabs, and only PHP code itself is four spaces as per our coding standards. This is a beautiful and consistent feature of the PHP manual sources.	+
-		+
-	==== Pretty diffs ====	+
-	Peer review is critical to the success of any Open Source project, including the PHP Manual. Fellow members of the team follow and read the commits so a diff should focus on changed content and not mix in whitespace manipulations. If something doesn't fit or look right, our eyes focus on it... this wastes time. Translators also rely on pretty diffs.	+
-		+
-	==== Diff === Artistic Masterpiece ====	+
-	Each diff can be seen as a piece of art. Look it over... is this something you might send your lover? Professor? Potential employer? Remember that every commit we make goes on record forever and represents the author. Making them pretty and useful means we will be pretty and useful, both individually and as a group.	+
-		+
-	==== A Diff should be perfect ====	+
-	Sometimes we want to quickly commit something and if needed update it again later. This is no good and instead we should wait until later before making the commit. There is no need to spam the mailing list with "I didn't have time and was going to fix it later" commits... there is no rush, the manual has existed for 10 years without the information and can wait another hour/day... simply save the file and attend to it later. The perfect diff meets all of the above descriptions.	+
-		+
-	====== How to create pretty whitespace =====	+
-	Unified diffs make this easy. Before any commit is made, the author should look over a diff of the edited file(s). This allows said author to find errors (like typos) as well as accidental whitespace changes. After making another change, check it again. Once the diff is as intended then commit it (after make test of course!) and move on.	+
-		+
-	I hope this helps explain why we are so strict about whitespace.	+

writing-tests

Anonymous (anonymous@undisclosed.example.com) — 2025-04-03T13:08:43+00:00

2008/04/10 22:27		current
Line 1:		Line 1:
	Part of an upcoming php.net article titled "How can you help PHP.NET today?" with this part focusing on writing tests. It's essentially in a FAQ format:		Part of an upcoming php.net article titled "How can you help PHP.NET today?" with this part focusing on writing tests. It's essentially in a FAQ format:

-	* Why should I write a test?	+	===== Why should I write a test? =====
	Code coverage is important for the success of any project including PHP. When code coverage reaches 100%, it'll mean that every piece of code within the PHP sources will be executed while running the tests. This helps determine if behaviour changes so essentially it helps prevent bugs from being introduced into PHP.		Code coverage is important for the success of any project including PHP. When code coverage reaches 100%, it'll mean that every piece of code within the PHP sources will be executed while running the tests. This helps determine if behaviour changes so essentially it helps prevent bugs from being introduced into PHP.

-	* What kind of setup do I need to write good tests?	+	===== What kind of setup do I need to write good tests? =====
	gcc >= 3.4 with gcov.		gcc >= 3.4 with gcov.
	Your local setup should also include lcov that is available here:		Your local setup should also include lcov that is available here:
Line 23:		Line 21:
	In summary: Install lcov, compile PHP with --enable-gcov, and now you're ready.		In summary: Install lcov, compile PHP with --enable-gcov, and now you're ready.

-	* How do I find what needs a test?	+	===== How do I find what needs a test? =====
	* Go to gcov.php.net		* Go to gcov.php.net
	* Choose a branch, then 'coverage'		* Choose a branch, then 'coverage'
	* Will go into some detail on what it means		* Will go into some detail on what it means

-	* How do I create a test?	+	===== How do I create a test? =====
	* Go to http://qa.php.net/...		* Go to http://qa.php.net/...

-	* Do you have a good example of a test and what it covers?	+	===== Do you have a good example of a test and what it covers? =====
	* Yes...		* Yes...

-	* How do I cover uncovered code?	+	===== How do I cover uncovered code? =====
	* Locate a file with a percentage < 100%		* Locate a file with a percentage < 100%
	* Use the legend to determine uncovered code		* Use the legend to determine uncovered code
	* Write code that will execute it		* Write code that will execute it
-	*

-	* How do I determine if the desired code gets executed?	+	===== How do I determine if the desired code gets executed? =====
	* make lcov		* make lcov
	* view lcov_html/index.html		* view lcov_html/index.html
Line 48:		Line 45:
	* Note: The TESTS var is to speed-up the process, as it will only run the specific test(s)		* Note: The TESTS var is to speed-up the process, as it will only run the specific test(s)

-	* How and where do I submit my test?	+	===== How and where do I submit my test? =====
	You can submit tests to the development mailing list @ internals@lists.php.net		You can submit tests to the development mailing list @ internals@lists.php.net

-	* What is open-box and black-box testing and why do I care?	+	===== What is open-box and black-box testing and why do I care? =====

-	* Do I need valgrind? When and why might I use it?	+	===== Do I need valgrind? When and why might I use it? =====
	Short answer: You don't.		Short answer: You don't.
	Long answer: valgrind can be used to detect if some test triggers a memory-related bug in PHP. Although running the test suite with valgrind is a plus, but it takes ages. You can submit tests without running valgrind, because the http://gcov.php.net project will do that for you.		Long answer: valgrind can be used to detect if some test triggers a memory-related bug in PHP. Although running the test suite with valgrind is a plus, but it takes ages. You can submit tests without running valgrind, because the http://gcov.php.net project will do that for you.

-	* How do I install lcov on Linux, Mac, and/or Windows? What part of the package do I need?	+	===== How do I install lcov on Linux, Mac, and/or Windows? What part of the package do I need? =====
-		+	Just untar it and run make install.
-	just untar it and run make install.	+