Merge pull request #7674 from kenjis/docs-Factories

docs: improve Factories and Config

Author: kenjis

user_guide_src/source/concepts/factories.rst

@@ -4,7 +4,7 @@ Factories
 
 .. contents::
     :local:
-    :depth: 2
+    :depth: 3
 
 Introduction
 ************
@@ -41,17 +41,14 @@ On the other hand, Services have code to create instances, so it can create a co
 that needs other services or class instances. When you get a service, Services require a service name,
 not a class name, so the returned instance can be changed without changing the client code.
 
+.. _factories-loading-class:
+
 Loading Classes
 ***************
 
 Loading a Class
 ===============
 
-.. _factories-example:
-
-Model 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()``.
 
@@ -64,7 +61,17 @@ In the following code, if you have ``App\Models\UserModel``, the instance will b
 
 .. literalinclude:: factories/001.php
 
-Or you could also request a specific class:
+If you don't have ``App\Models\UserModel``, it searches for ``Models\UserModel`` in all namespaces.
+
+Next time you ask for the same class anywhere in your code, Factories will be sure
+you get back the instance as before:
+
+.. literalinclude:: factories/003.php
+
+preferApp option
+----------------
+
+You could also request a specific class:
 
 .. literalinclude:: factories/002.php
    :lines: 2-
@@ -78,13 +85,6 @@ If you want to get ``Blog\Models\UserModel``, you need to disable the option ``p
 .. literalinclude:: factories/010.php
    :lines: 2-
 
-See :ref:`factories-options` for the details.
-
-Next time you ask for the same class anywhere in your code, Factories will be sure
-you get back the instance as before:
-
-.. literalinclude:: factories/003.php
-
 Loading a Class in Sub-directories
 ==================================
 

user_guide_src/source/concepts/factories/002.php

@@ -1,3 +1,5 @@
 <?php
 
 $users = Factories::models('Blog\Models\UserModel');
+// Or
+$users = Factories::models(\Blog\Models\UserModel::class);

user_guide_src/source/general/common_functions.rst

@@ -110,7 +110,7 @@ Service Accessors
     More simple way of getting model instances.
 
     The ``model()`` uses ``Factories::models()`` internally.
-    See :ref:`factories-example` for details on the first parameter ``$name``.
+    See :ref:`factories-loading-class` for details on the first parameter ``$name``.
 
     See also the :ref:`Using CodeIgniter's Model <accessing-models>`.
 

user_guide_src/source/general/configuration.rst

@@ -18,37 +18,52 @@ the application configuration files in the **app/Config** folder.
 Working with Configuration Files
 ********************************
 
+Getting a Config Object
+=======================
+
 You can access configuration files for your classes in several different ways.
 
-- By using the ``new`` keyword to create an instance:
+new keyword
+-----------
 
-  .. literalinclude:: configuration/001.php
+By using the ``new`` keyword to create an instance:
 
-- By using the ``config()`` function:
+.. literalinclude:: configuration/001.php
 
-  .. literalinclude:: configuration/002.php
+config()
+--------
 
-All configuration object properties are public, so you access the settings like any other property:
+By using the ``config()`` function:
 
-.. literalinclude:: configuration/003.php
+.. literalinclude:: configuration/002.php
 
-If no namespace is provided, it will look for the file in all defined namespaces
-as well as **app/Config/**.
+If no namespace is provided, it will look for the file in the **app/Config**
+folder first, and if not found, look for in the **Config** folder in all defined
+namespaces.
 
 All of the configuration files that ship with CodeIgniter are namespaced with
 ``Config``. Using this namespace in your application will provide the best
 performance since it knows exactly where to find the files.
 
-You can put configuration files in any folder you want by using a different namespace.
-This allows you to put configuration files on the production server in a folder
-that is not web-accessible while keeping it under **/app** for easy access
-during development.
+.. note:: ``config()`` finds the file in **app/Config/** when there is a class with the same shortname,
+    even if you specify a fully qualified class name like ``config(\Acme\Blog\Config\Blog::class)``.
+    This is because ``config()`` is a wrapper for the ``Factories`` class which uses ``preferApp`` by default. See :ref:`factories-loading-class` for more information.
+
+Getting a Config Property
+=========================
+
+All configuration object properties are public, so you access the settings like any other property:
+
+.. literalinclude:: configuration/003.php
 
 Creating Configuration Files
 ****************************
 
 When you need a new configuration, first you create a new file at your desired location.
 The default file location (recommended for most cases) is **app/Config**.
+
+You can put configuration files in any **Config** folder by using a different namespace.
+
 The class should use the appropriate namespace, and it should extend
 ``CodeIgniter\Config\BaseConfig`` to ensure that it can receive environment-specific settings.
 

user_guide_src/source/general/modules.rst

@@ -194,7 +194,7 @@ Config files are automatically discovered whenever using the ``config()`` functi
 
 .. note:: ``config()`` finds the file in **app/Config/** when there is a class with the same shortname,
     even if you specify a fully qualified class name like ``config(\Acme\Blog\Config\Blog::class)``.
-    This is because ``config()`` is a wrapper for the ``Factories`` class which uses ``preferApp`` by default. See :ref:`Factories Example <factories-example>` for more information.
+    This is because ``config()`` is a wrapper for the ``Factories`` class which uses ``preferApp`` by default. See :ref:`factories-loading-class` for more information.
 
 Migrations
 ==========
@@ -250,7 +250,7 @@ Model files are automatically discovered whenever using the :php:func:`model()`
 
 .. note:: ``model()`` finds the file in **app/Models/** when there is a class with the same shortname,
     even if you specify a fully qualified class name like ``model(\Acme\Blog\Model\PostModel::class)``.
-    This is because ``model()`` is a wrapper for the ``Factories`` class which uses ``preferApp`` by default. See :ref:`Factories Example <factories-example>` for more information.
+    This is because ``model()`` is a wrapper for the ``Factories`` class which uses ``preferApp`` by default. See :ref:`factories-loading-class` for more information.
 
 Views
 =====

user_guide_src/source/models/model.rst

@@ -29,7 +29,7 @@ You can access models within your classes by creating a new instance or using th
 .. literalinclude:: model/001.php
 
 The ``model()`` uses ``Factories::models()`` internally.
-See :ref:`factories-example` for details on the first parameter.
+See :ref:`factories-loading-class` for details on the first parameter.
 
 CodeIgniter's Model
 *******************