### XML Example with Screen Output in PHP Source: https://github.com/php/doc-base/blob/master/docs/cs-for-examples.md Shows how to structure examples using XML, including program listing and screen output sections for clarity. ```xml &reftitle.examples; A <function>foo</function> example ]]> &example.outputs; string(1) "a" [1]=> string(1) "b" [2]=> string(1) "c" } ]]> ``` -------------------------------- ### Multiline Output Comment in PHP Source: https://github.com/php/doc-base/blob/master/docs/cs-for-examples.md Demonstrates using block comments to show longer example output directly within the code. ```php string(5) "bread" [1]=> string(13) "peanut butter" [2]=> string(3) "jam" } */ ?> ``` -------------------------------- ### Build PHP.net Website HTML Documentation Source: https://github.com/php/doc-base/blob/master/docs/local-setup.md Render the documentation into the special HTML format used by the PHP.net website. This requires a local web server setup as described in the additional instructions. ```sh $ php phd/render.php --docbook doc-base/.manual.xml --package PHP --format php $ open https://localhost:8080/manual/en/ ``` -------------------------------- ### Run Local Web Server Source: https://github.com/php/doc-base/blob/master/docs/local-web-setup.md Start PHP's built-in web server on localhost:8080, using '.router.php' for routing. This command should be run in a separate terminal instance. ```bash cd phpdoc/web-php php -S localhost:8080 .router.php ``` -------------------------------- ### Inline Output Comment in PHP Source: https://github.com/php/doc-base/blob/master/docs/cs-for-examples.md Illustrates using C++ style comments to denote example output on the same line as the code. ```php echo $var; // 32 ``` -------------------------------- ### Updating Translation Header Example Source: https://github.com/php/doc-base/blob/master/docs/translating.md Shows the before and after of a translated file's header comment after updating the EN-Revision commit hash to sync with the English source. ```xml ``` ```xml ``` -------------------------------- ### Translating a New File Header Source: https://github.com/php/doc-base/blob/master/docs/translating.md Example of a translated file header for a new translation. It includes the EN-Revision commit hash from the English source and the maintainer's username. ```xml ``` -------------------------------- ### Diff Example for Updating Translations Source: https://github.com/php/doc-base/blob/master/docs/translating.md This diff shows changes between two versions of a documentation file, highlighting parameter type modifications in the synopsis. Use this to identify necessary updates in your translated file. ```diff diff --git a/reference/password/functions/password-needs-rehash.xml b/reference/password/functions/password-needs-rehash.xml index 984eb2dc5c..860758a4a4 100644 --- a/reference/password/functions/password-needs-rehash.xml +++ b/reference/password/functions/password-needs-rehash.xml @@ -12,8 +12,8 @@ booleanpassword_needs_rehash stringhash - stringalgo - stringoptions + intalgo + arrayoptions This function checks to see if the supplied hash implements the algorithm ``` -------------------------------- ### Clone and Build PHP Documentation with Docker Source: https://github.com/php/doc-base/blob/master/docs/local-setup.md Use this snippet to set up the PHP documentation build environment using Docker and make. It clones the English documentation repository and initiates the build process. ```sh $ mkdir phpdoc $ cd phpdoc $ git clone https://github.com/php/doc-en.git en $ cd en $ make $ open output/php-chunked-xhtml/index.html ``` -------------------------------- ### Symlink PHP Documentation (Windows) Source: https://github.com/php/doc-base/blob/master/docs/local-web-setup.md On Windows, navigate to the manual directory and remove the existing 'en' directory before creating a directory symbolic link to the generated PHP documentation. Ensure you run the command prompt as an administrator. ```cmd cd \your\path\to\web-php\manual\ rmdir /S en mklink /D en \your\path\to\output\web-php ``` -------------------------------- ### Copy Skeleton Files for New Methods and Functions Source: https://github.com/php/doc-base/blob/master/docs/editing.md Use these commands to copy skeleton XML files for new methods or functions into the correct directory structure. Replace 'classname', 'methodname', and 'functionname' with the actual lowercase names. ```bash cp doc-base/skeletons/method.xml classname/methodname.xml #for new methods cp doc-base/skeletons/function.xml functions/functionname.xml #for new functions ``` -------------------------------- ### Build Chunked HTML Documentation Source: https://github.com/php/doc-base/blob/master/docs/local-setup.md Generate a multiple-file (chunked) HTML version of the PHP documentation from the .manual.xml file. The output will be placed in the output/php-chunked-xhtml directory. ```sh $ php phd/render.php --docbook doc-base/.manual.xml --package PHP --format xhtml $ open output/php-chunked-xhtml/index.html ``` -------------------------------- ### Clone PHP Sources Source: https://github.com/php/doc-base/blob/master/docs/local-web-setup.md Use git to clone the web-php repository from GitHub. ```bash $ git clone https://github.com/php/web-php.git ``` -------------------------------- ### Validate and Build .manual.xml Source: https://github.com/php/doc-base/blob/master/docs/local-setup.md Run this command to validate the XML structure of the PHP documentation according to the Docbook specification. It checks for errors and generates the .manual.xml file. ```sh $ php doc-base/configure.php ``` -------------------------------- ### Generate PHP Extension Skeletons Source: https://github.com/php/doc-base/blob/master/docs/faq.md Use the docgen script to create initial documentation skeletons for a new PHP extension. Specify the extension name and output directory. ```sh php docgen.php -e simplexml -o outdir ``` -------------------------------- ### Symlink PHP Documentation (Linux/macOS) Source: https://github.com/php/doc-base/blob/master/docs/local-web-setup.md Navigate to the manual directory and remove the existing 'en' directory before creating a symbolic link to the generated PHP documentation. ```bash cd web-php/manual rm -rf en ln -s ../../output/php-web en ``` -------------------------------- ### Clone PHP Documentation Repositories without Docker Source: https://github.com/php/doc-base/blob/master/docs/local-setup.md This snippet outlines the process for cloning the necessary PHP documentation repositories (phd, doc-base, doc-en) when building without Docker. Ensure these are cloned into a single parent directory. ```sh $ mkdir phpdoc $ cd phpdoc $ git clone https://github.com/php/phd.git $ git clone https://github.com/php/doc-base.git $ git clone https://github.com/php/doc-en.git en ``` -------------------------------- ### foo() with second argument (PHP 8.1.0+) Source: https://github.com/php/doc-base/blob/master/docs/cs-for-examples.md Demonstrates the use of a function with a new argument added in PHP 8.1.0. Ensure your PHP version supports this feature. ```php ``` -------------------------------- ### Document Optional Method Parameter Source: https://github.com/php/doc-base/blob/master/docs/faq.md Document an optional method parameter using the 'choice="opt"' attribute on and the tag for the default value. ```xml bool httponly false ``` -------------------------------- ### Validate Documentation Changes Source: https://github.com/php/doc-base/blob/master/docs/editing.md Run the configure.php script to validate your documentation changes. Navigate to the phpdoc directory and execute the script, specifying the language if it's not English. ```bash $ cd phpdoc $ php configure.php --with-lang={LANG} ``` -------------------------------- ### Check Tags with Few Expected Translations Source: https://github.com/php/doc-base/blob/master/scripts/translation/README.md Utilize the qaxml-tags.php script to verify tags where only a few translations are anticipated. This is useful for tags like code, filename, etc., that might have limited translation needs. ```bash php doc-base/scripts/translation/qaxml-tags.php --content=code php doc-base/scripts/translation/qaxml-tags.php --content=computeroutput php doc-base/scripts/translation/qaxml-tags.php --content=filename php doc-base/scripts/translation/qaxml-tags.php --content=literal php doc-base/scripts/translation/qaxml-tags.php --content=varname ``` -------------------------------- ### Function definition with correct spacing Source: https://github.com/php/doc-base/blob/master/docs/cs-for-examples.md Illustrates the correct indentation and spacing for PHP code. Use spaces instead of tabs, with four spaces per indentation level. ```php ``` -------------------------------- ### Validate and Build Translation .manual.xml Source: https://github.com/php/doc-base/blob/master/docs/local-setup.md When building a translation, use this command to validate the XML and specify the language code. This ensures the translation is checked against the Docbook specification and uses the specified language. ```sh $ git clone https://github.com/php/doc-fr.git fr $ php doc-base/configure.php --with-lang=fr ``` -------------------------------- ### Configure Git for Windows EOL Handling Source: https://github.com/php/doc-base/blob/master/docs/local-setup.md On Windows, use this command to configure Git to preserve the U+000A LINE FEED (LF) end-of-line mark. This is crucial for consistent file handling during translation. ```sh cd LANG git config core.autocrlf true git add --renormalize . git status ``` -------------------------------- ### String Interpolation vs. Concatenation in PHP Source: https://github.com/php/doc-base/blob/master/docs/cs-for-examples.md Demonstrates preferred methods for embedding variables within strings for output using echo. Prefer interpolation or comma separation over string concatenation. ```php $output = "bar is $bar"; echo "bar is $bar"; $output = "bar is {$bar}"; echo "bar is {$bar}"; ``` ```php $output = 'bar is ' . $bar; echo 'bar is ', $bar; ``` -------------------------------- ### Changelog Version Formatting Source: https://github.com/php/doc-base/blob/master/docs/style.md When specifying multiple PHP versions for a changelog entry, separate them with a comma, listing the lower version first. This format is used for clarity in version-specific updates. ```xml 5.2.11, 5.3.1 ``` -------------------------------- ### Check for Missing PHP Documentation Source: https://github.com/php/doc-base/blob/master/docs/faq.md A multi-step process to identify functions or methods lacking documentation. This involves configuring the doc-base, running PhD, and then executing a check-missing-docs script. ```sh php doc-base/configure.php phd --docbook doc-base/.manual.xml --package PHP --format php php doc-base/scripts/check-missing-docs.php -d output/index.sqlite ``` -------------------------------- ### Preferred error handling with boolean check Source: https://github.com/php/doc-base/blob/master/docs/cs-for-examples.md Demonstrates the preferred method for error handling using a boolean check and braces. This approach allows for more complex logic within the error handling block. ```php if (!foobar($lname)) { ... exit; } ``` -------------------------------- ### Check Tags with No Expected Translations Source: https://github.com/php/doc-base/blob/master/scripts/translation/README.md Use the qaxml-tags.php script to check specific tags where no translations are expected. This helps ensure that these tags are not inadvertently translated. ```bash php doc-base/scripts/translation/qaxml-tags.php --content=acronym php doc-base/scripts/translation/qaxml-tags.php --content=classname php doc-base/scripts/translation/qaxml-tags.php --content=constant php doc-base/scripts/translation/qaxml-tags.php --content=envar php doc-base/scripts/translation/qaxml-tags.php --content=function php doc-base/scripts/translation/qaxml-tags.php --content=interfacename php doc-base/scripts/translation/qaxml-tags.php --content=parameter php doc-base/scripts/translation/qaxml-tags.php --content=type php doc-base/scripts/translation/qaxml-tags.php --content=classsynopsis php doc-base/scripts/translation/qaxml-tags.php --content=constructorsynopsis php doc-base/scripts/translation/qaxml-tags.php --content=destructorsynopsis php doc-base/scripts/translation/qaxml-tags.php --content=fieldsynopsis php doc-base/scripts/translation/qaxml-tags.php --content=funcsynopsis php doc-base/scripts/translation/qaxml-tags.php --content=methodsynopsis ``` -------------------------------- ### Link to External URL Entity Source: https://github.com/php/doc-base/blob/master/docs/faq.md Use a defined entity to create an external link in the documentation. Ensure the xlink namespace is declared. ```xml Check out Google ``` -------------------------------- ### Accessing Arrays in Strings in PHP Source: https://github.com/php/doc-base/blob/master/docs/cs-for-examples.md Shows recommended ways to access array elements within strings. Using curly braces for interpolation or separate echo arguments is preferred for clarity. ```php $variable = "an $array[key] key"; echo "an $array[key] key"; ``` ```php $variable = "an {$array['key']} key"; echo "an {$array['key']} key"; echo 'an ', $array['key'], ' key'; ``` -------------------------------- ### Add a Note with a Title Source: https://github.com/php/doc-base/blob/master/docs/faq.md A typical note structure in DocBook XML, including an optional title and the note's content. ```xml Foo Note contents are here. ``` -------------------------------- ### Error handling with 'or' operator Source: https://github.com/php/doc-base/blob/master/docs/cs-for-examples.md Shows basic error handling using the 'or' operator. This method is suitable for development but not recommended for production due to its limitations. ```php foobar($lname) or die(...); ``` -------------------------------- ### Run Strict Structural Checks Source: https://github.com/php/doc-base/blob/master/scripts/translation/README.md Execute a series of scripts to perform strict structural checks on translation files. These scripts help identify and fix issues like whitespace problems and missing revision tags. ```bash php doc-base/scripts/broken.php php doc-base/scripts/translation/qaxml-revtag.php php doc-base/scripts/translation/qaxml-attributes.php php doc-base/scripts/translation/qaxml-entities.php php doc-base/scripts/translation/qaxml-pi.php php doc-base/scripts/translation/qaxml-tags.php --detail php doc-base/scripts/translation/qaxml-ws.php ``` -------------------------------- ### Define External URL Entity Source: https://github.com/php/doc-base/blob/master/docs/faq.md Define an external URL as an entity in the global.ent file for reuse in documentation. ```xml ``` -------------------------------- ### Revert Git EOL Configuration on Windows Source: https://github.com/php/doc-base/blob/master/docs/local-setup.md If the previous Git configuration for EOL handling on Windows resulted in unintended changes, use these commands to revert the configuration and reset the status. ```sh git config --unset core.autocrlf git reset git status ``` -------------------------------- ### Avoid Personal Pronouns in Technical Descriptions Source: https://github.com/php/doc-base/blob/master/docs/style.md When writing technical descriptions, avoid using personal pronouns like 'you'. Rephrase sentences to be more objective and professional. This applies to most sections of the manual except for the PHP Tutorial and FAQs. ```text INCORRECT: You can use the optional second parameter to specify tags that should not be stripped. CORRECT: The optional second parameter may be used to specify tags that should not be stripped. ``` -------------------------------- ### EN-Revision Comment Syntax Source: https://github.com/php/doc-base/blob/master/docs/translating.md This is the required format for the EN-Revision comment in translated files. It includes the commit hash of the English source file, the maintainer's username, and the status of the translation. ```xml ``` -------------------------------- ### Add 'noversion' Role to Refentry Source: https://github.com/php/doc-base/blob/master/docs/faq.md To prevent a refentry from emitting versioning information, add the 'role="noversion"' attribute to the tag. ```xml ``` -------------------------------- ### JavaScript Function Redirect Source: https://github.com/php/doc-base/blob/master/htmlhelp/suppfiles/html/_function.html This JavaScript function redirects the browser to a new page based on the URL's hash fragment. It's useful for implementing client-side navigation or loading specific content dynamically. ```javascript function loadPage() { if (location.hash.length > 0) { funcname = location.hash.substr(1); funcpage = "function." + funcname.replace(/\_/g, "-") + ".html"; path = location.href.substring(0, location.href.lastIndexOf("/")); location.replace(path + '/' + funcpage); } } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.