Merge pull request #7182 from kenjis/fix-docs-factories.rst

docs: improve factories.rst

Author: kenjis

user_guide_src/source/concepts/factories.rst

@@ -15,6 +15,11 @@ What are Factories?
 Like :doc:`./services`, **Factories** are an extension of autoloading that helps keep your code
 concise yet optimal, without having to pass around object instances between classes.
 
+Factories are similar to CodeIgniter 3's ``$this->load`` in the following points:
+
+- Load a class
+- Share the loaded class instance
+
 At its
 simplest, Factories provide a common way to create a class instance and access it from
 anywhere. This is a great way to reuse object states and reduce memory load from keeping
@@ -44,8 +49,10 @@ Example
 Take a look at **Models** as an example. You can access the Factory specific to Models
 by using the magic static method of the Factories class, ``Factories::models()``.
 
+The static method name is called *component*.
+
 By default, Factories first searches in the ``App`` namespace for the path corresponding to the magic static method name.
-``Factories::models()`` searches the path **Models/**.
+``Factories::models()`` searches the **app/Models** directory.
 
 In the following code, if you have ``App\Models\UserModel``, the instance will be returned:
 
@@ -54,6 +61,7 @@ In the following code, if you have ``App\Models\UserModel``, the instance will b
 Or you could also request a specific class:
 
 .. literalinclude:: factories/002.php
+   :lines: 2-
 
 If you have only ``Blog\Models\UserModel``, the instance will be returned.
 But if you have both ``App\Models\UserModel`` and ``Blog\Models\UserModel``,
@@ -62,6 +70,7 @@ the instance of ``App\Models\UserModel`` will be returned.
 If you want to get ``Blog\Models\UserModel``, you need to disable the option ``preferApp``:
 
 .. literalinclude:: factories/010.php
+   :lines: 2-
 
 See :ref:`factories-options` for the details.
 
@@ -119,8 +128,8 @@ Key        Type           Description
 ========== ============== ============================================================ ===================================================
 component  string or null The name of the component (if different than the static      ``null`` (defaults to the component name)
                           method). This can be used to alias one component to another.
-path       string or null The relative path within the namespace/folder to look for    ``null`` (defaults to the component name)
-                          classes.
+path       string or null The relative path within the namespace/folder to look for    ``null`` (defaults to the component name,
+                          classes.                                                     but makes the first character uppercase)
 instanceOf string or null A required class name to match on the returned instance.     ``null`` (no filtering)
 getShared  boolean        Whether to return a shared instance of the class or load a   ``true``
                           fresh one.
@@ -143,6 +152,9 @@ Configurations
 To set default component options, create a new Config files at **app/Config/Factory.php**
 that supplies options as an array property that matches the name of the component.
 
+Example: Filters Factories
+--------------------------
+
 For example, if you want to create **Filters** by Factories, the component name wll be ``filters``.
 And if you want to ensure that each filter is an instance of a class which implements CodeIgniter's ``FilterInterface``,
 your **app/Config/Factory.php** file might look like this:
@@ -155,6 +167,22 @@ and the returned instance will surely be a CodeIgniter's filter.
 This would prevent conflict of an third-party module which happened to have an
 unrelated ``Filters`` path in its namespace.
 
+Example: Library Factories
+--------------------------
+
+If you want to load your library classes in the **app/Libraries** directory with
+``Factories::library('SomeLib')``, the path `Libraries` is different from the
+default path `Library`.
+
+In this case, your **app/Config/Factory.php** file will look like this:
+
+.. literalinclude:: factories/011.php
+
+Now you can load your libraries with the ``Factories::library()`` method:
+
+.. literalinclude:: factories/012.php
+   :lines: 2-
+
 setOptions Method
 =================
 

user_guide_src/source/concepts/factories/003.php

@@ -1,5 +1,7 @@
 <?php
 
+use CodeIgniter\Config\Factories;
+
 class SomeOtherClass
 {
     public function someFunction()

user_guide_src/source/concepts/factories/004.php

@@ -1,4 +1,4 @@
 <?php
 
-$conn  = db_connect('AuthDatabase');
+$conn  = db_connect('auth');
 $users = Factories::models('UserModel', [], $conn);

user_guide_src/source/concepts/factories/007.php

@@ -1,4 +1,4 @@
 <?php
 
-$users = Factories::models('UserModel', ['getShared' => true]); // Default; will always be the same instance
+$users = Factories::models('UserModel', ['getShared' => true]);  // Default; will always be the same instance
 $other = Factories::models('UserModel', ['getShared' => false]); // Will always create a new instance

user_guide_src/source/concepts/factories/010.php

@@ -1,3 +1,3 @@
 <?php
 
-$widgets = Factories::models('Blog\Models\UserModel', ['preferApp' => false]);
+$users = Factories::models('Blog\Models\UserModel', ['preferApp' => false]);

user_guide_src/source/concepts/factories/011.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\Factory as BaseFactory;
+
+class Factory extends BaseFactory
+{
+    public $library = [
+        'path' => 'Libraries',
+    ];
+}

user_guide_src/source/concepts/factories/012.php

@@ -0,0 +1,5 @@
+<?php
+
+use CodeIgniter\Config\Factories;
+
+$someLib = Factories::library('SomeLib');