Merge pull request #5689 from sfadschm/docs-example-code

[Docs] Extract example php code for static analysis.

.php-cs-fixer.dist.php

@@ -32,6 +32,7 @@
  __DIR__ . '/.no-header.php-cs-fixer.dist.php',
  __DIR__ . '/rector.php',
  __DIR__ . '/spark',
+ __DIR__ . '/user_guide_src/renumerate.php',
  ]);
 
 $overrides = [];

user_guide_src/renumerate.php

@@ -0,0 +1,98 @@
+<?php
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+$srcFolder = __DIR__ . '/source';
+
+// Exclude static folders
+$excludes = ['_static', 'images'];
+
+// Safety prefix
+$prefix = 'old_';
+
+// Begin user info
+echo 'The following sections were renumerated:', PHP_EOL;
+
+// Loop source directory
+$srcIterator = new DirectoryIterator($srcFolder);
+
+foreach ($srcIterator as $chapterInfo) {
+ if (! $chapterInfo->isDot() && $chapterInfo->isDir() && ! in_array($chapterInfo->getFilename(), $excludes, true)) {
+ $chapterName = $chapterInfo->getFilename();
+
+ // Iterate the working directory
+ $chapterIterator = new DirectoryIterator($chapterInfo->getPathname());
+
+ foreach ($chapterIterator as $sectionInfo) {
+ if (! $sectionInfo->isDot() && $sectionInfo->isFile() && $sectionInfo->getExtension() === 'rst') {
+ $sectionName = $sectionInfo->getBasename('.rst');
+ $sectionFolder = $sectionInfo->getPath() . '/' . $sectionName;
+
+ // Read the section file
+ $sectionContent = file_get_contents($sectionInfo->getPathname());
+
+ // Match all includes
+ preg_match_all("~\\.\\. literalinclude:: {$sectionName}\\/(.+)\\.php(\n[ ]*:lines: 2\\-)?~", $sectionContent, $matches);
+ $includeStrings = $matches[0];
+ $exampleNames = $matches[1];
+
+ // Exit early if no matches
+ if (count($exampleNames) === 0) {
+ continue;
+ }
+
+ // Check if examples are consecutive
+ $consecutive = true;
+
+ foreach ($exampleNames as $exampleIndex => $exampleName) {
+ if (str_pad($exampleIndex + 1, 3, '0', STR_PAD_LEFT) !== $exampleName) {
+ $consecutive = false;
+ break;
+ }
+ }
+
+ // Exit if examples are already consecutive
+ if ($consecutive) {
+ continue;
+ }
+
+ // Rename all example files to avoid conflicts
+ $exampleIterator = new DirectoryIterator($sectionFolder);
+
+ foreach ($exampleIterator as $exampleInfo) {
+ if (! $exampleInfo->isDot() && $exampleInfo->isFile() && $exampleInfo->getExtension() === 'php') {
+ rename($exampleInfo->getPathname(), $exampleInfo->getPath() . '/' . $prefix . $exampleInfo->getFilename());
+ }
+ }
+ $sectionContent = preg_replace("~\\.\\. literalinclude:: {$sectionName}\\/(.+)\\.php~", ".. literalinclude:: {$sectionName}/{$prefix}$1.php", $sectionContent);
+
+ // Renumerate examples
+ foreach ($exampleNames as $exampleIndex => $exampleName) {
+ $newName = str_pad($exampleIndex + 1, 3, '0', STR_PAD_LEFT);
+
+ // Rename example file
+ rename($sectionFolder . '/' . $prefix . $exampleName . '.php', $sectionFolder . '/' . $newName . '.php');
+
+ // Fix include link
+ $sectionContent = preg_replace(preg_quote(str_replace($exampleName, $prefix . $exampleName, $includeStrings[$exampleIndex]), '~'), str_replace($exampleName, $newName, $includeStrings[$exampleIndex]), $sectionContent, 1, $count);
+ }
+
+ // Write new content to rst
+ file_put_contents($sectionInfo->getPathname(), $sectionContent);
+
+ // User info
+ echo $chapterName, '/', $sectionName, PHP_EOL;
+ }
+ }
+ }
+}
+
+// End user info
+echo 'Renumerating finished.', PHP_EOL;

user_guide_src/source/changelogs/v4.0.0-alpha.2.rst

@@ -107,7 +107,6 @@ tests /
  - ParserTest #1311
  - EntityTest #1319
 
-
 user_guide_src /source/
  - cli/
  - cli_request #1303

user_guide_src/source/changelogs/v4.0.0-alpha.3.rst

@@ -5,7 +5,6 @@ Release Date: November 30, 2018
 
 **Next alpha release of CodeIgniter4**
 
-
 The list of changed files follows, with PR numbers shown.
 
 - admin/

user_guide_src/source/changelogs/v4.0.0-beta.1.rst

@@ -158,7 +158,7 @@ PRs merged:
 - #1737 Added support for dropTable and modifyTable with SQLite driver
 - #1736 Accommodate long travis execution times
 - #1733 Fix increment and decrement errors with Postgres
-- #1732 Don't check from CLI in Routes. Fixes #1724 
+- #1732 Don't check from CLI in Routes. Fixes #1724
 - #1729 New View Layout functionality for simple template
 - #1725 Update Request.php
 - #1723 Log an error if redis authentication is failed
@@ -176,4 +176,4 @@ PRs merged:
 - #4f4a37 remove debugging from Model.
 - #1699 Fix install link in user guide
 - #1696 Fix page structure etc
-- #1695 Tidy up code blocks in the user guide
+- #1695 Tidy up code blocks in the user guide

user_guide_src/source/changelogs/v4.0.0-beta.2.rst

@@ -153,7 +153,6 @@ The list of changed files follows, with PR numbers shown.
  - ViewTest #1827, #1836
  - ControllerTest #1850
 
-
 - user_guide_src/
  - cli/
  - cli_commands #1777
@@ -265,4 +264,4 @@ PRs merged:
 - #1769 Correction in Methods and Spellings
 - #1762 Fix: decimal rule. shouldn't it accept integers?
 - #1746 Improve: Update Model, to selective update created_at / updated_at field.
-- #1590 Improve: Enhance 404Override
+- #1590 Improve: Enhance 404Override

user_guide_src/source/changelogs/v4.0.0-beta.4.rst

@@ -17,7 +17,6 @@ New messages:
 
 App changes:
 
-
 Testing changes:
 
 - enhanced database & migration testing in tests/_support
@@ -152,7 +151,6 @@ The list of changed files follows, with PR numbers shown.
  - testing/
  - database #2051, #2053
 
-
 PRs merged:
 -----------
 

user_guide_src/source/changelogs/v4.0.0-rc.2.rst

@@ -162,7 +162,6 @@ The list of changed files follows, with PR numbers shown.
  - news_section #2221
  - static_pages #2221
 
-
 PRs merged:
 --------------------------
 

user_guide_src/source/changelogs/v4.0.0-rc.3.rst

@@ -16,7 +16,6 @@ App changes:
 
 Message changes:
 
-
 The list of changed files follows, with PR numbers shown.
 
 - admin/
@@ -121,7 +120,6 @@ The list of changed files follows, with PR numbers shown.
  - outgoing/
  - table #2337
 
-
 PRs merged:
 -----------
 

user_guide_src/source/changelogs/v4.0.0-rc.4.rst

@@ -12,7 +12,6 @@ Enhancements:
 - Add validation function `is_not_unique`
 - Various improvements and cleanup to the Email class
 
-
 PRs merged:
 -----------
 - #2527 Update manual.rst

user_guide_src/source/changelogs/v4.0.4.rst

@@ -31,7 +31,6 @@ Enhancements:
 - Cookies and headers can be copied from the global Response object when doing a redirect using the new ``withCookies()`` and ``withHeaders()`` methods.
 - Support for special prefix "hex2bin:" which can be used with ``$key`` parameter in :doc:`Encryption class</libraries/encryption>` or in .env file.
 
-
 Bugs Fixed:
 
 - Fixed location for the SQLite3 database which by default will be now located in a ``writable`` folder instead of the ``public`` folder.
@@ -56,4 +55,3 @@ Bugs Fixed:
 - Fix is_unique/is_not_unique validation called on POST/PUT via API in Postgresql
 - Added ``$arguments`` parameter to after() and before() in FilterInterface. This is a breaking change, so all code implementing the FilterInterface must be updated
 - Fixed a bug where filter arguments were not passed to after()
-

user_guide_src/source/changelogs/v4.2.0.rst

@@ -14,7 +14,6 @@ BREAKING
 
 - The method signature of ``Validation::setRule()`` has been changed. The ``string`` typehint on the ``$rules`` parameter was removed. Extending classes should likewise remove the parameter so as not to break LSP.
 
-
 Enhancements
 ************
 

user_guide_src/source/cli/cli.rst

@@ -36,21 +36,9 @@ Let's try it: Hello World!
 
 Let's create a simple controller so you can see it in action. Using your
 text editor, create a file called Tools.php, and put the following code
-in it::
+in it:
 
- <?php
-
- namespace App\Controllers;
-
- use CodeIgniter\Controller;
-
- class Tools extends Controller
- {
- public function message($to = 'World')
- {
- echo "Hello {$to}!" . PHP_EOL;
- }
- }
+.. literalinclude:: cli/001.php
 
 Then save the file to your **app/Controllers/** directory.
 
@@ -94,9 +82,10 @@ CLI-Only Routing
 In your **Routes.php** file you can create routes that are only accessible from
 the CLI as easily as you would create any other route. Instead of using the ``get()``,
 ``post()``, or similar method, you would use the ``cli()`` method. Everything else
-works exactly like a normal route definition::
+works exactly like a normal route definition:
 
- $routes->cli('tools/message/(:segment)', 'Tools::message/$1');
+.. literalinclude:: cli/002.php
+ :lines: 2-
 
 For more information, see the :doc:`Routes </incoming/routing>` page.
 

user_guide_src/source/cli/cli/001.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace App\Controllers;
+
+use CodeIgniter\Controller;
+
+class Tools extends Controller
+{
+ public function message($to = 'World')
+ {
+ echo "Hello {$to}!" . PHP_EOL;
+ }
+}

user_guide_src/source/cli/cli/002.php

@@ -0,0 +1,3 @@
+<?php
+
+$routes->cli('tools/message/(:segment)', 'Tools::message/$1');

user_guide_src/source/cli/cli_commands.rst

@@ -47,9 +47,8 @@ Calling Commands
 Commands can also be ran from within your own code. This is most often done within a controller for cronjob tasks,
 but they can be used at any time. You do this by using the ``command()`` function. This function is always available.
 
-::
-
- echo command('migrate:create TestMigration');
+.. literalinclude:: cli_commands/001.php
+ :lines: 2-
 
 The only argument is string that is the command called and any parameters. This appears exactly as you would call
 it from the command line.
@@ -101,26 +100,9 @@ An Example Command
 
 Let's step through an example command whose only function is to report basic information about the application
 itself, for demonstration purposes. Start by creating a new file at **/app/Commands/AppInfo.php**. It
-should contain the following code::
-
- <?php
-
- namespace App\Commands;
-
- use CodeIgniter\CLI\BaseCommand;
- use CodeIgniter\CLI\CLI;
+should contain the following code:
 
- class AppInfo extends BaseCommand
- {
- protected $group = 'demo';
- protected $name = 'app:info';
- protected $description = 'Displays basic application information.';
-
- public function run(array $params)
- {
- // ...
- }
- }
+.. literalinclude:: cli_commands/002.php
 
 If you run the **list** command, you will see the new command listed under its own ``demo`` group. If you take
 a close look, you should see how this works fairly easily. The ``$group`` property simply tells it how to organize
@@ -142,24 +124,18 @@ any CLI arguments after the command name for your use. If the CLI string was::
 
  > php spark foo bar baz
 
-Then **foo** is the command name, and the ``$params`` array would be::
+Then **foo** is the command name, and the ``$params`` array would be:
 
- $params = ['bar', 'baz'];
+.. literalinclude:: cli_commands/003.php
+ :lines: 2-
 
 This can also be accessed through the :doc:`CLI </cli/cli_library>` library, but this already has your command removed
 from the string. These parameters can be used to customize how your scripts behave.
 
-Our demo command might have a ``run`` method something like::
+Our demo command might have a ``run`` method something like:
 
- public function run(array $params)
- {
- CLI::write('PHP Version: '. CLI::color(phpversion(), 'yellow'));
- CLI::write('CI Version: '. CLI::color(\CodeIgniter\CodeIgniter::CI_VERSION, 'yellow'));
- CLI::write('APPPATH: '. CLI::color(APPPATH, 'yellow'));
- CLI::write('SYSTEMPATH: '. CLI::color(SYSTEMPATH, 'yellow'));
- CLI::write('ROOTPATH: '. CLI::color(ROOTPATH, 'yellow'));
- CLI::write('Included files: '. CLI::color(count(get_included_files()), 'yellow'));
- }
+.. literalinclude:: cli_commands/004.php
+ :lines: 2-
 
 ***********
 BaseCommand
@@ -176,22 +152,19 @@ be familiar with when creating your own commands. It also has a :doc:`Logger </g
  :param string $command: The name of another command to call.
  :param array $params: Additional CLI arguments to make available to that command.
 
- This method allows you to run other commands during the execution of your current command::
+ This method allows you to run other commands during the execution of your current command:
 
- $this->call('command_one');
- $this->call('command_two', $params);
+ .. literalinclude:: cli_commands/005.php
+  :lines: 2-
 
  .. php:method:: showError(Throwable $e)
 
  :param Throwable $e: The exception to use for error reporting.
 
- A convenience method to maintain a consistent and clear error output to the CLI::
+ A convenience method to maintain a consistent and clear error output to the CLI:
 
- try {
- . . .
- } catch (\Exception $e) {
- $this->showError($e);
- }
+ .. literalinclude:: cli_commands/006.php
+ :lines: 2-
 
  .. php:method:: showHelp()
 
@@ -202,14 +175,7 @@ be familiar with when creating your own commands. It also has a :doc:`Logger </g
  :param array $array: The $key => $value array.
  :param integer $pad: The pad spaces.
 
- A method to calculate padding for $key => $value array output. The padding can be used to output a will formatted table in CLI::
-
- $pad = $this->getPad($this->options, 6);
-
- foreach ($this->options as $option => $description) {
- CLI::write($tab . CLI::color(str_pad($option, $pad), 'green') . $description, 'yellow');
- }
+ A method to calculate padding for $key => $value array output. The padding can be used to output a will formatted table in CLI:
 
- // Output will be
- -n Set migration namespace
- -r override file
+ .. literalinclude:: cli_commands/007.php
+ :lines: 2-